SMS Delivery Reports with SMPP protocol

There are two ways to verify the delivery of SMS messages.

Query the status of the message

When a message is send using the SMPP protocol, the provider returns a message reference. Using this reference, we can query the provider for the delivery status of this message. This is done by sending a 'query_sm' PDU to the provider. If the message reference is known by the provider, it responds with a 'query_sm_resp' PDU. This packet holds the status of the message. This can be one of the following values:

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 the message in a specified amount of time. For instance when the phone was turned off.
4DELETEDThe message was deleted.
5UNDELIVERABLEThe SMS was unable to deliver the message.For instance, when the 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 this range.
9SKIPPEDThe message was skipped.

The disadvantage of this method is, that you have to poll once in a while to get the current message status. When a lot of messages are enroute for a couple of hours, this will cause heavy data traffic. Most providers recommend you to request delivery reports instead of querying, because there is only data sent by the provider when the status of a message has changed. Therefore, the 'query_sm' method is not supported by most SMPP providers.

Request delivery reports from the provider

The best way to check the status of each message sent, is to ask for delivery reports. This can be done by setting the 'registered_delivery' flag of the 'submit_sm' SMPP PDU. This parameter can have one of the following values:

Value Meaning
0Do not send delivery reports
1Always send delivery reports
2Send delivery report in case of an error
3Send delivery report only when message is delivered

By setting this value to '1', the provider will send a delivery report to the client every time the status of this message changes. You can set this value per message.

The delivery reports are sent to the client using the 'deliver_sm' packet. This is the same packet as used to deliver incoming messages. To detect whether a 'deliver_sm' is a delivery report or a message, you have to check the 'esm_class' field. If bit 2 of this byte is set ( 0x04 ), it is a delivery report. To use delivery reports, you have to setup a transceiver connection to the SMPP provider, because you are going to send and receive messages. The delivery status is encoded in the 'short_message' field as an ASCII text message. This format is product specific, but the following format is used by most SMPP providers:

id:c449ab9744f47b6af1879e49e75e4f40 sub:001 dlvrd:0 submit date:0610191018 done date:0610191018 
stat:ACCEPTD err:0 text:This is an Acti

id:7220bb6bd0be98fa628de66590f80070 sub:001 dlvrd:1 submit date:0610190851 done date:0610190951 
stat:DELIVRD err:0 text:This is an Acti

id:b756c4f97aa2e1e67377dffc5e2f7d9b sub:001 dlvrd:0 submit date:0610191211 done date:0610191211 
stat:REJECTD err:1 text:This is an Acti

id:bd778cd76ae9e79da2ddc8188c68f8c1 sub:001 dlvrd:0 submit date:0610191533 done date:0610191539 
stat:UNDELIV err:1 text:This is an Acti
Field Meaning
idThe message reference of the message.
subSub-ID, not used.
dlvrdValue '1' when the message has been delivered, if the message is still pending '0'.
submit dateSubmission date and time.
done dateDate and time the status has changed, or message delivery time when stat is set to 'DELIVRD'.
statCurrent status of the message.
errAdditional error code, provider specific.
textPart of the original message text.

NOTE: The message reference returned in this delivery report can be returned in hexadecimal or decimal format. This varies per provider. You have to specify the delivery report format your provider is using, by setting the 'DeliveryReportFormat' property to 'asSMPPDELIVERYREPORTFORMAT_HEX' for hexadecimal (default) or 'asSMPPDELIVERYREPORTFORMAT_DEC' for decimal.

When using SMPP version 3.4, sometimes the message has some optional parameters (TLV's) attached containing the message state, message reference and a network error code. Please refer to the SMPP version 3.4 documentation on how to use these TLV's.

Using delivery reports with the ActiveXperts SMS and MMS Toolkit

The SMS and MMS Toolkit (SMS API) only supports the second method (waiting for delivery report) to retrieve the delivery status of a message.

To use this method you have to connect with the 'SystemMode' property set to 'asSMPP_MODE_TRANSCEIVER'. Because the connection is setup for both sending and receiving, the SMS component will be listening for incoming delivery reports and store them in its internal cache memory.

Once the connection has been established using the 'Connect' function, you can submit messages. Please note, that to request a delivery report for a particular message, you should have the 'RequestDeliveryStatus' property of the SmsMessage object set to 'TRUE' or '1'. If a message is accepted by the provider it will return the reference number for this message.

Now you can call the 'QueryStatus' function. The QueryStatus will check the internal cache of the SMS component if there is a delivery report available for the given message reference. If the operation was successfull ( LastError = 0 ), it will return a SmsDeliveryStatus object. This object contains the following properties:

Poperty Meaning
StatusThe status of the message. See the above table for possible values
StatusDescriptionTextual representation of the returned status
StatusCodeOperator dependent additional info about the status of the message, or cause of the error
IsCompletedIndicates whether the message is in its final state. If this property is FALSE, the provider is still rertying
StatusCompletedTimeSecsTime in seconds after 1/1/1970 that message reached its final state
StatusCompletedTimeTime (formatted string) that message reached its final state
ProviderReferenceThe original reference returned by the provider. The message reference returned on the Send call is an internal message reference generated by the toolkit itself

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

Option Explicit

Dim objSmpp, objMessage, objStatus, objConstants
Dim strRef, strStatus, i

' Create Objects
Set objSmpp                 = CreateObject ( "ActiveXperts.SmsProtocolSmpp" )
Set objConstants            = CreateObject ( "ActiveXperts.SmsConstants" )
Set objMessage              = CreateObject ( "ActiveXperts.SmsMessage")

' Set Provider Settings
objSmpp.Server              = "smpp.activexperts-labs.com"
objSmpp.SystemID            = "AX008"
objSmpp.SystemPassword      = "812056"

' connect as Transceiver
objSmpp.SystemMode          = objConstants.asSMPPMODE_TRANSCEIVER       

objSmpp.Connect

If ( objSmpp.LastError ) Then
    WScript.Echo  "Connect failed: " & objSmpp.GetErrorDescription ( objSmpp.LastError )
    WScript.Quit
End If

objMessage.Data                  = "delivery report test"
objMessage.Recipient             = "+31647134226"
objMessage.RequestDeliveryStatus = True

' Send the message
strRef = objSmpp.Send ( objMessage )

If ( objSmpp.LastError ) Then
    WScript.Echo "Send failed: " & objSmpp.GetErrorDescription ( objSmpp.LastError )
    objSmpp.Disconnect
    WScript.Quit
End If

' Store message reference
WScript.Echo "Message submitted, ID = " & strRef	

For i = 1 To 20    
    WScript.Sleep  5000  
    
    ' Query the delivery status
    Set objStatus = objSmpp.QueryStatus	( strRef )	
    
    If ( objSmpp.LastError = 0 ) Then
        WScript.Echo "Message status after " & i * 5 & " seconds: " & objStatus.StatusDescription
	
        If ( objStatus.IsCompleted = True ) Then
            End Loop
		   
    End If
Next

objSmpp.Disconnect

WScript.Echo "Ready."

This VBScript will generate the following output:

Message submitted, ID = 00000E73

Message status after 5 seconds: Scheduled
Message status after 10 seconds: Enroute
Message status after 15 seconds: Enroute
Message status after 20 seconds: Delivered
Ready.
Ready.