SMS Delivery Reports using GSM Modems

Like most cell phones, GSM modems are able to check the delivery of a SMS message using delivery reports.
If this option has been turned on, you will receive a delivery report for every message that was sent with the 'delivery report' flag turned on.
This delivery report contains a message status, delivery time and an optional network specific error code.

This message is only received when the message was delivered or has been failed.
You do not receive a delivery report when the message is still enroute.

When a delivery report is received, it is stored in the modems internal memory, or on the SIM card.
Where the report is stored depends on the device used. WaveCom and Multitech devices use a dedicated storage for status reports.

The following storages are supported by most GSM phones and modems:

Name	Description
SM	Memory on the SIM card
ME	The device's memory
MT	Combined storage (SIM and device memory)
SR	Status reports memory, dedicated memory in the device, used by WaveCom

Because these memories normally can hold just a few messages, it is recommended to remove these messages after receive.
The ActiveXperts SMS and MMS toolkit has built in support for requesting and processing delivery reports.

To request a delivery report for a message, you have to set the 'RequestDeliveryStatus' property of the 'SmsMessage' object to 'True'.
The SMS Component will then set the 'TP-SRR' bit in the SMS-SUBMIT PDU when a message is submitted.

Before you can receive delivery reports, you need to specify the storage used for delivery reports using the 'Storage' property of the 'GsmOut' object.
Please refer to the manual of the GSM modem for details on what storage to use. If you are not sure, use 'asREPORTSSTORAGE_MEMORY',
if you are using a WaveCom or Multitech modem, please use 'asSTORAGE_REPORT'.

If you select the incorrect storage, you will not receive any reports !

The following values are supported:

asSTORAGE_ALL	Autodetect all storages supported by this device
asSTORAGE_SIM	Use SIM Memory for status reports
asSTORAGE_MEMORY	Use Device Memory for status reports
asSTORAGE_ANY	Use SIM and device memory for status reports
asSTORAGE_REPORTS	Use special Reports memory of the device for all status reports. Only advanced GSM modems have such a Reports memory

Upon success or failure, a delivery report will be sent back to the GSM modem.
The delivery report will be delivered to the GSM modem as a SMS-STATUS-REPORT PDU.

Please note that not all providers support this feature, but most of them do. Most providers do not charge extra for status reports.

The delivery report contains a status field (TP-ST) which can hold one of the following values:

Value	Description
0x00	Short message delivered successfully
0x01	Forwarded, but status unknown
0x02	Replaced
0x20	Congestion, still trying
0x21	Recipient busy, still trying
0x22	No response recipient, still trying
0x23	Service rejected, still trying
0x24	QOS not available, still trying
0x25	Recipient error, still trying
0x40	RPC Error
0x41	Incompatible destination
0x42	Connection rejected
0x43	Not obtainable
0x44	QOS not available
0x45	No internetworking available
0x46	Message expired
0x47	Message deleted by sender
0x48	Message deleted by SMSC
0x49	Does not exist

The most common values return are 0x00 (success) or 0x46 (expired, for instance when a phone has been turned off for a few days).
The SMS and MMS Toolkit translates these status codes into more readable status descriptions (same as in SMPP):

Status Number	Status	Explanation
0	SCHEDULED	The message is scheduled for later sending.
1	ENROUTE	The message is enroute.
2	DELIVERED	The message was successfully delivered.
3	EXPIRED	The SMSC was unable to deliver the message in a specified amount of time. For instance when the phone was turned off.
4	DELETED	The message was deleted.
5	UNDELIVERABLE	The SMS was unable to deliver the message. For instance, when the number does not exist.
6	ACCEPTED	The SMS was accepted and will be send.
7	UNKNOWN	Unknown error occured.
8	REJECTED	The message was rejected. The provider could have blocked phonenumbers in this range.
9	SKIPPED	The message was skipped.

To Query the status of a message, you need to know the message reference of the sent message.
After sending a messages, this reference is stored in the 'MessageReference' property.
This is a 8-bit number (0-255). Please not that when you are sending a lot of messages, this number can be a duplicate.
You do not have to set this property if you want to query the last message sent.

When you call the 'QueryStatus' function, the SMS component will open the selected storage,
reads all new delivery reports and deletes them. Other messages in the selected storage will not be deleted.

Delivery reports for other messages are also cached in the internal memory of the SMS component.

If a delivery report for the specified message reference is found, a SmsDeliveryStatus object is returned.
The 'StatusCompletedTime' and 'StatusCompletedTimeSeconds' properties are set to the SMSC discharge time (TP-DT), this means the time the message was delivered,
or the time the SMSC detects an error and stops retrying.

The following VBScript code sample demonstrates how to use delivery reports with the SMS and MMS Toolkit:

Option Explicit

Dim objSmsProtocol
Dim objSmsMessage
Dim objSmsStatus 
Dim objConstants

Dim strReference

Set objSmsProtocol = CreateObject ( "ActiveXperts.SmsProtocolGsm" )
Set objSmsMessage  = CreateObject ( "ActiveXperts.SmsMessage"     )
Set objConstants   = CreateObject ( "ActiveXperts.SmsConstants"   )

' Set Logfile
objSmsProtocol.LogFile  = "c:\SmsLog.txt"

' Set Device
objSmsProtocol.Device   = "COM1"

' Set recipient
objSmsMessage.Recipient = "+31647134225" 

' Set message text
objSmsMessage.Data      = "SMS Message with delivery report request"

' Request status report
objSmsMessage.RequestDeliveryReport = TRUE

' Send the message 
strReference = objSmsProtocol.Send ( objSmsMessage )		 

' Show the result
If( objSmsProtocol.LastError <> 0 ) Then
    WScript.Echo "Failed to send message, error: " & objSmsProtocol.LastError & " (" &_
	              & objSmsProtocol.GetErrorDescription( objSmsProtocol.LastError ) & ")"
    WScript.Echo "To view the trace file, open " & objSmsProtocol.LogFile & "."
    WScript.Quit
Else
    WScript.Echo "Message successfully submitted" & vbCrlf & vbCrLf & "Message Reference = " & strReference 
End If

WScript.Sleep ( 30000 ) ' Wait some seconds to allow the SMS to get processed and delivered.

' Query the message 
WScript.Echo "Query the message, this can take some seconds..."

Set objSmsStatus = objSmsProtocol.QueryStatus ( strReference )			 

' Show the result
If( objSmsProtocol.LastError <> 0 ) Then
    WScript.Echo "Failed to query message, error: " & objSmsProtocol.LastError & " (" &_
	             & objSmsProtocol.GetErrorDescription( objGsmOut.LastError ) & ")"
    WScript.Echo "To view the trace file, open " & objSmsProtocol.LogFile & "."
    WScript.Quit
Else
    WScript.Echo "Message successfully queried"
    WScript.Echo
    WScript.Echo "Status = " & objSmsStatus.StatusDescription 
    WScript.Echo "Time   = " & objSmsStatus.StatusCompletedTime
End If

The ActiveXperts SMS and MMS Toolkit is a SMS development component (SDK). This control can be used by any Windows development platform, including Visual Basic .NET, Visual CSharp .NET, ASP .NET (VB,CS), ASP, Visual Basic, Visual Basic for Applications (VBA), Visual Studio/Visual C++, Borland Delphi and C++ Builder, PHP, ColdFusion, HTML, VBScript and any other ActiveX/COM compliant platform. The SMS and MMS Toolkit is an ActiveXperts Software B.V. Product.