SMS Delivery Reports using GSM Modems

SMS Delivery Reports Introduction

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 'request delivery report' flag turned on. This delivery report contains a message status, delivery time and an optional network specific error code, in case SMSC failed to deliver the message.

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 in the 'enroute' state.

Memory locations for storing delivery reports

When a delivery report has been 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 delivery reports.

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

NameDescription
SMMemory on tde SIM card
METhe device's memory
MTCombined storage (SIM and device memory)
SRDelivery reports memory, dedicated memory in tde device, used by WaveCom

Because these memories normally can hold just a few messages, it is recommended to remove these messages from the SIM or device after receive.

Requesting delivery reports using the SMS and MMS Toolkit

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 API 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 'SmsProtocolGsm' object.

Please refer to the manual of the GSM modem or GSM phone for details on what storage to use. If you are not sure, use 'asREPORTSSTORAGE_ALL,

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_ALLAutodetect all storages supported by this device
asSTORAGE_SIMUse SIM Memory for status reports
asSTORAGE_MEMORYUse Device Memory for status reports
asSTORAGE_ANYUse SIM and device memory for status reports
asSTORAGE_REPORTSUse special Reports memory of tde 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.

GSM error codes supported by the status field (TP-ST)

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

ValueDescription
0x00Short message delivered successfully
0x01Forwarded, but status unknown
0x02Replaced
0x20Congestion, still trying
0x21Recipient busy, still trying
0x22No response recipient, still trying
0x23Service rejected, still trying
0x24QOS not available, still trying
0x25Recipient error, still trying
0x40RPC Error
0x41Incompatible destination
0x42Connection rejected
0x43Not obtainable
0x44QOS not available
0x45No internetworking available
0x46Message expired
0x47Message deleted by sender
0x48Message deleted by SMSC
0x49Does 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
0SCHEDULEDThe message is scheduled for later sending.
1ENROUTEThe message is enroute.
2DELIVEREDThe message was successfully delivered.
3EXPIREDThe SMSC was unable to deliver tde message in a specified amount of time.
For instance when tde phone was turned off.
4DELETEDThe message was deleted.
5UNDELIVERABLEThe SMS was unable to deliver tde message.
For instance, when tde number does not exist.
6ACCEPTEDThe SMS was accepted and will be send.
7UNKNOWNUnknown error occured.
8REJECTEDThe message was rejected.
The provider could have blocked phonenumbers in tdis range.
9SKIPPEDThe message was skipped.

Query the delivery status of the message

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