Introduction to SMPP Introduction SMPP stands for Short Message Peer to Peer Protocol SMPP is used to send and receive messages from and to GSM, UMTS, iDEN,CDMA and TDMA cell phones. The protocol is a level-7 TCP/IP protocol, which allows fast deliver of SMS messages. Using the SMPP protocol instead of sending messages using a GSM modem has the following advantages: •
The SMPP protocol is TCP/IP based, GSM hardware is not required;
•
Users can send SMS to a simple shortcode, this is not possible when sending to a GSM
phone; •
High throughput ( up to 200 msgs/second);
•
Alphanumeric sender address can be assigned.
Applications SMPP can be used for the followi ng applications: •
Sending Voicemail alerts to mobile users;
•
Sending SMS notifications to mobile users, for instance when a server is down, or to notify
students that a lesson is cancelled; •
Information services : sending stock exchanges, traffic jam alerts or weather forecasts;
•
Voting, process votes from mobile users (Requesting music on the radio;
•
MMS notifications, when users pay for ringtones and Java applications, the download
location is send by a MMS notification or WAP Push message; •
Telemetry applications.
Connections SMPP is used by clients to connected to a SMSC (Short Message Service Centre). In SMPP terms, the client is called ESME (Extended Short Message Entity). SMSC's can also exchange data using a SMPP connection. Messages Send to a SMSC are called MT (Mobile Terminated) messages, because they are sent to a mobile phone. Messages received from a SMSC are called MO (Mobile Originated) messages, because they were sent from a mobile phone. When an ESME establishes a connection using SMPP, this can be done in three modes: Transmitter, the ESME can only submit messages to the SMSC; Receiver, the ESME can only receive messages or delivery reports from the SMSC; Transceiver, the EMSE can bot send and receive messages to and from the SMSC.
SMPP PDU's The TCP packets between the ESME and the SMSC are called PDU's (Protocol Data Units). The following types of PDU's are used in SMPP connections: Session Management PDU� s Connecting, disconnection and connection keep alive. Message Submission PDU� s Submitting messages to a mobile phone. Message Delivery PDU� s Delivery of messages to the SMPP client. Ancillary Operations PDU� s Message query, cancel and replacement. The following SMPP PDU's are used the most: bind_transmitter / bind_receiver / bind_transceiver Used to connect connect the client client with the SMSC, SMSC, in SMPP SMPP session sessions s a �system system ID� and password password are are used used for authentication. submit_sm Used to submit a single message from the client to the SMSC ( MT ). This packet contains the sender and recipient address, message body and some optional parameters. deliver_sm When a messages has to be delivered to the client this packet is used ( MO ). It contains information about the sender of the message and the me ssage body. This PDU is also used to send delivery reports to the ESME. query_sm To query the state of a previously sent message, this command is used. You need a message reference to query a message. Most provider require you to use delivery reports instead of querying the messages all the time. enquire_link This packet is sent once in every x minutes to check if the connection is still alive. If not, the connection is terminated. This packet is also used to keep dial-up connections alive ( for instance ISDN ). The most used timeout for SMPP connections is one minute. unbind Used to end the session and disconnect the TCP/IP connection.
Connection examples
Sending Messages
Receiving Messages
SMPP optional parameters
To extend the SMPP protocol with extra parameters, TLV parameters, also called optional parameters were introduced in the SMPP protocol since version 3.4: •
TLV�s are used to make the existing PDU�s more efficient;
•
TLV�s are used to enhance existing PDU�s with new features;
•
TLV Stands for Tag-Length-Value field;
•
TLV�s are supported in SMPP version 3.4 and higher.
Some commonly used TLV's are: message_payload TLV Used to encode large messages. The submit_sm PDU can be used to messages up to 255 chars only. This PDU improves performance, for instance: when you need to send a message containing 315 characters you only have to send one packet instead of two. This doubles the throughput. sar_msg_ref_num, sar_segment_seqnum, sar_total_segments TLV � s Segmentation And Reassembly. These TLV�s are used to send a long message in multiple parts . sar_msg_ref_num - Reference of the concatenated message. sar_segment_seqnum - ID of the current segment. sar_total_segments - Total number of segments. Please note that not all SMPP providers implement all TLV parameters.
SMPP Error Codes The following list is an overview of codes SMPP providers will return in the "command_status" field in case of an error.
Error Number 0x00000000 0x00000001 0x00000002
ESME_ROK ESME_RINVMSGLEN ESME_RINVCMDLEN
0x00000003
ESME_RINVCMDID
0x00000004
ESME_RINVBNDSTS
0x00000005 0x00000006 0x00000007 0x00000008 0x0000000A 0x0000000B 0x0000000C 0x0000000D 0x0000000E
ESME_RALYBND ESME_RINVPRTFLG ESME_RINVREGDLVFLG ESME_RSYSERR ESME_RINVSRCADR ESME_RINVDSTADR ESME_RINVMSGID ESME_RBINDFAIL ESME_RINVPASWD
Error Name
Error Description
No Error Message too long Command length is invalid Command ID is invalid or not supported Incorrect bind status for given command Already bound Invalid Priority Flag Invalid registered delivery flag System error Invalid source address Invalid destination address Message ID is invalid Bind failed Invalid password
Error Number 0x0000000F 0x00000011 0x00000013 0x00000014 0x00000015 0x00000033 0x00000034 0x00000040
ESME_RINVSYSID ESME_RCANCELFAIL ESME_RREPLACEFAIL ESME_RMSSQFUL ESME_RINVSERTYP ESME_RINVNUMDESTS ESME_RINVDLNAME ESME_RINVDESTFLAG
0x00000042
ESME_RINVSUBREP
0x00000043 0x00000044 0x00000045
ESME_RINVESMCLASS ESME_RCNTSUBDL ESME_RSUBMITFAIL
0x00000048
ESME_RINVSRCTON
0x00000049
ESME_RINVSRCNPI
0x00000050
ESME_RINVDSTTON
0x00000051
ESME_RINVDSTNPI
0x00000053 0x00000054 0x00000055 0x00000058 0x00000061 0x00000062 0x00000063 0x00000064 0x00000065
ESME_RINVSYSTYP ESME_RINVREPFLAG ESME_RINVNUMMSGS ESME_RTHROTTLED ESME_RINVSCHED ESME_RINVEXPIRY ESME_RINVDFTMSGID ESME_RX_T_APPN ESME_RX_P_APPN
0x00000066
ESME_RX_R_APPN
0x00000067
ESME_RQUERYFAIL
Error Name
0x000000C0 ESME_RINVTLVSTREAM 0x000000C1 0x000000C2 0x000000C3 0x000000C4 0x000000FE 0x000000FF
ESME_RTLVNOTALLWD ESME_RINVTLVLEN ESME_RMISSINGTLV ESME_RINVTLVVAL ESME_RDELIVERYFAILURE ESME_RUNKNOWNERR
Error Description
Invalid System ID Cancelling message failed Message recplacement failed Message queue full Invalid service type Invalid number of destinations Invalid distribution list name Invalid destination flag Invalid submit with replace request Invalid esm class set Invalid submit to ditribution list Submitting message has failed Invalid source address type of number ( TON ) Invalid source address numbering plan ( NPI ) Invalid destination address type of number ( TON ) Invalid destination address numbering plan ( NPI ) Invalid system type Invalid replace_if_present flag Invalid number of messages Throttling error Invalid scheduled delivery time Invalid Validty Period value Predefined message not found ESME Receiver temporary error ESME Receiver permanent error ESME Receiver reject message error Message query request failed Error in the optional part of the PDU body TLV not allowed Invalid parameter length Expected TLV missing Invalid TLV value Transaction delivery failure Unknown error
Error Number
Error Name
Error Description
ESME not authorised to use specified servicetype ESME prohibited from using 0x00000101 ESME_RPROHIBITED specified operation Specified servicetype is 0x00000102 ESME_RSERTYPUNAVAIL unavailable 0x00000103 ESME_RSERTYPDENIED Specified servicetype is denied 0x00000104 ESME_RINVDCS Invalid data coding scheme Invalid source address subunit 0x00000105 ESME_RINVSRCADDRSUBUNIT Invalid destination address 0x00000106 ESME_RINVSTDADDRSUBUNIR subunit Insufficient credits to send 0x0000040B ESME_RINVBALANCE message Destination address blocked by 0x0000040C ESME_RUNESME_SPRTDDESTADDR the ActiveXperts SMPP Demo Server 0x00000100
ESME_RSERTYPUNAUTH
TLV Parameters SMPP TLV Parameters intro TLV stands for Tag Length Value. These extra parameters were added to the SMPP protocol in version 3.4. The parameters can be used to extend the SMPP protocol with more advanced features. TLV's are also called 'optional fields'. TLV's are simply added as byte stream at the end of the standard SMPP pdu's. The first two bytes are used to identify the parameter, the firth and fourth byte indicate the length of the actual data which follows directly after these bytes.
Supported SMPP TLV Parameters Below you can find a list of all TLV parameters defined in SMPP versions 3.4 and 5.0. Some providers are also using some vendor specific SMPP TLV Parameters.
additional_status_info_text The additional_status_info_text parameter gives an ASCII textual description of the meaning of a response PDU. It is to be used by an implementation to allow easy diagnosis of problems. TLV Parameter Tag: TLV Parameter Type: 0x001D COCTET alert_on_msg_delivery The alert_on_message_delivery parameter is set to instruct a MS to alert the user (in a MS implementation specific manner) when the short message arrives at the MS.
TLV Parameter Tag: 0x130C
alert_on_msg_delivery TLV Parameter Type: 1BYTE
billing_identification Billing information passed from ESME to MC TLV Parameter Tag: TLV Parameter Type: 0x060B OCTET broadcast _frequency _interval The broadcast_frequency_interval parameter specifies the frequency interval at which the broadcasts of a message should be repeated. TLV Parameter Tag: TLV Parameter Type: 0x0605 OCTET broadcast_area_identifier The broadcast_area_identifier defines the Broadcast Area in terms of a geographical descriptor. TLV Parameter Tag: TLV Parameter Type: 0x0606 OCTET broadcast_area_success The broadcast_area_success parameter is a success rate indicator, defined as the ratio of the number of BTSs who accepted the message and the total number of BTSs who should accept the message, for a particular broadcast_area_identifier. TLV Parameter Tag: TLV Parameter Type: 0x0608 1BYTE broadcast_channel_indicator The broadcast_channel_indicator parameter specifies the Cell Broadcast channel that should be used for broadcasting the message. TLV Parameter Tag: TLV Parameter Type: 0x0600 1BYTE broadcast_content_type The broadcast_content_type parameter specifies the content_type of the message content. TLV Parameter Tag: TLV Parameter Type: 0x0601 OCTET broadcast_content_type_info The broadcast_content_type_info parameter contains additional information specific to the broadcast_content_type. TLV Parameter Tag: TLV Parameter Type:
broadcast_content_type_info 0x0602
OCTET
broadcast_end_time The broadcast_end_time parameter indicates the date and time at which the broadcasting state of this message was set to terminated in the Message Centre. TLV Parameter Tag: TLV Parameter Type: 0x0609 COCTET broadcast_error_status The broadcast_error_status parameter specifies the nature of the failure associated with a particular broadcast_area_identifier specified in a broadcast request. TLV Parameter Tag: TLV Parameter Type: 0x0607 4BYTE broadcast_message_class The broadcast_message_class parameter is used to route messages when received by a mobile station to user-defined destinations or to Terminal Equipment. TLV Parameter Tag: TLV Parameter Type: 0x0603 1BYTE broadcast_rep_num This field indicates the number of repeated broadcasts requested by the Submitter. TLV Parameter Tag: TLV Parameter Type: 0x0604 2BYTE broadcast_service_group The broadcast_service_group parameter is used to specify special target groups for broadcast information. TLV Parameter Tag: TLV Parameter Type: 0x060A OCTET callback_num A call-back number associated with the short message. This parameter can be included a number of times for multiple call-back addresses TLV Parameter Tag: TLV Parameter Type: 0x0381 OCTET callback_num_atag The callback_num_atag parameter associates an alphanumeric display with the call back number. TLV Parameter Tag: TLV Parameter Type: 0x0303 OCTET
callback_num_pres_ind This parameter controls the presentation indication and screening of the CallBackNumber at the mobile station. If present, the callback_num parameter must also be present. TLV Parameter Tag: TLV Parameter Type: 0x0302 1BYTE congestion_state The congestion_state parameter is used to pass congestion status information between ESME and MC as a means of providing flow control and congestion avoidance capabilities to the sending peer. The TLV can be used in any SMPP operation response PDU as a means of passing congestion status from one peer to another. Typical uses of this would be in submit_sm/submit_sm_resp sequences where an ESME would drive a batch of submissions at a high rate and use continual tracking of the returned congestion_state values as a means of gauging the congestion. Reaction to a variation in congestion_state would involve increasing/decreasing the rate as required to maintain the balance in the Optimum range. TLV Parameter Tag: TLV Parameter Type: 0x0428 1BYTE delivery_failure_reason The delivery_failure_reason parameter is used in the da ta_sm_resp operation to indicate the outcome of the message delivery attempt (only applicable for transaction message mode). If a delivery failure due to a network error is indicated, the ESME may check the network_error_code parameter (if present) for the actual network error code. TLV Parameter Tag: TLV Parameter Type: 0x0425 1BYTE dest_addr_np_country The dest_addr_np_country TLV is used to carry E.164 information relating to the operator country code. TLV Parameter Tag: TLV Parameter Type: 0x0613 4BYTE dest_addr_np_information The dest_addr_np_information TLV is used to ca rry number portability information. TLV Parameter Tag: TLV Parameter Type: 0x0612 OCTET dest_addr_np_resolution The dest_addr_np_resolution TLV is used to pass an indicator relating to a number portability query. If this TLV is omitted, the default value is assumed. TLV Parameter Tag: TLV Parameter Type: 0x0611 1BYTE
dest_addr_subunit The dest_addr_subunit parameter is used to route messages when received by a mobile station, for example to a smart card in the mobile station or to an external device connected to the mobile station. TLV Parameter Tag: TLV Parameter Type: 0x0005 1BYTE dest_bearer_type The dest_bearer_type parameter is used to request the desired bearer for delivery of the message to the destination address. In the case that the receiving system (e.g. MC) does not support the indicated bearer type, it may treat this a failure and return a response PDU reporting a failure. TLV Parameter Tag: TLV Parameter Type: 0x0007 1BYTE dest_network_id The dest_network_id assigned to a wireless network operator or ESME operator is a unique address that may be derived and assigned by the node owner without establishing a central assignment and management authority. When this TLV is specified, it must be accompanied with a dest_node_id TLV Ref.4.8.4.27. TLV Parameter Tag: TLV Parameter Type: 0x060E COCTET dest_network_type The dest_network_type parameter is used to indicate a network type associated with the destination address of a message. In the case that the receiving system (e.g. MC) does n ot support the indicated network type, it may treat this a failure and return a response PDU reporting a failure. TLV Parameter Tag: TLV Parameter Type: 0x0006 1BYTE dest_node_id The dest_node_id is a unique number assigned within a single ESME or MC network and must uniquely identify a destination node within the context of the MC or ESME. The content of a dest_node_id is comprised of decimal digits and is at the discretion of the owning ESME or MC. TLV Parameter Tag: TLV Parameter Type: 0x0610 OCTET dest_port The dest_port parameter is used to indicate the application port number associated with the destination address of the message. TLV Parameter Tag: TLV Parameter Type:
dest_port 0x020B
2BYTE
dest_subaddress The dest_subaddress parameter specifies a subaddress associated with the destination of the message. TLV Parameter Tag: TLV Parameter Type: 0x0203 OCTET dest_telematics_id This parameter defines the telematic interworking to be used by the delivering system for the destination address. This is only useful when a specific dest_bearer_type parameter has also been specified, as the value is bearer dependent. In the case that the receiving system (e.g. MC) does not support the indicated telematic interworking, it may treat this a failure and return a response PDU reporting a failure. TLV Parameter Tag: TLV Parameter Type: 0x0008 2BYTE display_time The display_time parameter is used to associate a display time of the short message on the MS. TLV Parameter Tag: TLV Parameter Type: 0x1201 1BYTE dpf_result The dpf_result parameter is used to indicate if delivery pending flag (DPF) was set for a delivery failure of a short message. TLV Parameter Tag: TLV Parameter Type: 0x0420 1BYTE its_reply_type The its_reply_type parameter is a required parameter for the CDMA Interactive Teleservice as defined by the Korean PCS carriers [KORITS]. It indicates and controls the MS user’s reply method to an SMS delivery message received from the ESME. TLV Parameter Tag: TLV Parameter Type: 0x1380 1BYTE its_session_info The its_session_info parameter is a required parameter for the CDMA Interactive Teleservice as defined by the Korean PCS carriers [KORITS]. It contains control information for the interactive session between an MS and an ESME. TLV Parameter Tag: TLV Parameter Type: 0x1383 OCTET
language_indicator The language_indicator parameter is used to indicate the language of the short message. TLV Parameter Tag: TLV Parameter Type: 0x020D 1BYTE message_payload The message_payload parameter contains the user data. Its function is to provide an alternative means of carrying text lengths above the 255 octet limit of the short_message field. Applications, which need to send messages longer than 255 octets, should use the message_payload TLV. When used in the context of a submit_sm PDU, the sm_length field should be set to zero. TLV Parameter Tag: TLV Parameter Type: 0x0424 OCTET message_state The message_state TLV is used by the MC in the deliver_sm and data_sm PDUs to indicate to the ESME the final message state for a MC Delivery Receipt. The message_state TLV is also returned by the MC to the ESME as part of the query_broadcast_sm_resp PDU. TLV Parameter Tag: TLV Parameter Type: 0x0427 1BYTE more_messages_to_send The more_messages_to_send parameter is used by the ESME in the submit_sm and data_sm operations to indicate to the MC that there are further messages for the same destination SME. The MC may use this setting for network resource optimisation. TLV Parameter Tag: TLV Parameter Type: 0x0426 1BYTE ms_availability_status The ms_availability_status parameter is used in the alert_notification operation to indicate the availability state of the MS to the ESME. If the MC does not include the parameter in the alert_notification operation, the ESME should assume that the MS is in an “available” state. TLV Parameter Tag: TLV Parameter Type: 0x0422 1BYTE ms_msg_wait_facilities The ms_msg_wait_facilities parameter allows an indication to be provided to an MS that there are messages waiting for the subscriber on s ystems on the PLMN. The indication can be an icon on the MS screen or other MMI indication. TLV Parameter Tag: TLV Parameter Type: 0x0030 1BYTE
ms_validity The ms_validity parameter is used to provide an MS with validity information associated with the received short message. TLV Parameter Tag: TLV Parameter Type: 0x1204 4BYTE network_error_code The network_error_code parameter is used to indicate the actual network error code for a delivery failure. The network error code is technology specific. TLV Parameter Tag: TLV Parameter Type: 0x0423 OCTET number_of_messages The number_of_messages parameter is used to indicate the number of messages stored in a mailbox. TLV Parameter Tag: TLV Parameter Type: 0x0304 1BYTE payload_type The payload_type parameter defines the higher layer PDU type contained in the message payload. TLV Parameter Tag: TLV Parameter Type: 0x0019 1BYTE privacy_indicator The privacy_indicator indicates the privacy level of the message. TLV Parameter Tag: TLV Parameter Type: 0x0201 1BYTE qos_time_to_live This parameter defines the number of seconds which the sender requests the MC to keep the message if undelivered before it is deemed expired. If the parameter is not present, the MC may apply a default value. TLV Parameter Tag: TLV Parameter Type: 0x0017 4BYTE receipted_message_id The receipted_message_id parameter indicates the ID of the message being receipted in a MC Delivery Receipt. This is the opaque MC message identifier that was returned in the message_id parameter of the SMPP response PDU that acknowledged the submission of the original message. TLV Parameter Tag: TLV Parameter Type: 0x001E COCTET
sar_msg_refnum The sar_msg_ref_num parameter is used to indicate the reference number for a particular concatenated short message. TLV Parameter Tag: TLV Parameter Type: 0x020C 2BYTE sar_segment_seqnum The sar_segment_seqnum parameter is used to indicate the sequence number of a particular short message within the concatenated short message. TLV Parameter Tag: TLV Parameter Type: 0x020F 1BYTE sar_total_segments The sar_total_segments parameter is used to indicate the total number of short messages within the concatenated short message. TLV Parameter Tag: TLV Parameter Type: 0x020E 1BYTE sc_interface_version The sc_interface_version parameter is used to indicate the SMPP version supported by the MC. It is returned in the bind response PDUs. TLV Parameter Tag: TLV Parameter Type: 0x0210 1BYTE set_dpf An ESME may use the set_dpf parameter to request the setting of a delivery pending flag (DPF) for certain delivery failure scenarios, such as MS unavailability (as indicated by the HLR). The MC should respond to such a request with an alert_notification PDU when it detects that the destination MS has become available. TLV Parameter Tag: TLV Parameter Type: 0x0421 1BYTE sms_signal The sms_signal parameter is used to provide a TDMA MS with alert tone information associated with the received short message. TLV Parameter Tag: TLV Parameter Type: 0x1203 2BYTE source_addr_subunit The source_addr_subunit parameter is used to indicate where a message originated in the mobile station, for example a smart card in the mobile station or an external device connected to the mobile station. TLV Parameter Tag: TLV Parameter Type:
source_addr_subunit 0x000D
1BYTE
source_bearer_type The source_bearer_type parameter indicates the wireless bearer over which the message originated. TLV Parameter Tag: TLV Parameter Type: 0X000F 1BYTE source_network_id The source_network_id assigned to a wireless network operator or ESME operator is a unique address that may be derived and assigned by the node owner without establishing a central assignment and management authority. TLV Parameter Tag: TLV Parameter Type: 0x060D COCTET source_network_type The source_network_type parameter is used to indicate the network type associated with the device that originated the message. TLV Parameter Tag: TLV Parameter Type: 0x000E 1BYTE source_node_id The source_node_id is a unique number assigned within a single ESME or MC network and must uniquely identify an originating node within the context of the MC or ESME. The content of a source_node_id is comprised of decimal digits and is a t the discretion of the owning ESME or MC. TLV Parameter Tag: TLV Parameter Type: 0x060F OCTET source_port The source_port parameter is used to indicate the application port number associated with the source address of the message. TLV Parameter Tag: TLV Parameter Type: 0x020A 2BYTE source_subaddress The source_subaddress parameter specifies a subaddress associated with the originator of the message. Field Size TLV Parameter Tag: TLV Parameter Type: 0x0202 OCTET
source_telematics_id The source_telematics_id parameter indicates the type of telematics interface over which the message originated. TLV Parameter Tag: TLV Parameter Type: 0x0010 1BYTE user_message_reference A reference assigned by the originating SME to the short message. Depending on the destination network technology, this field may be passed directly to the mobile device. TLV Parameter Tag: TLV Parameter Type: 0x0204 2BYTE user_response_code A response code set by the user in a User Acknowledgement/Reply message. The response codes are application specific. TLV Parameter Tag: TLV Parameter Type: 0x0205 1BYTE ussd_service_op The ussd_service_op parameter is required to define the USSD service operation when SMPP is being used as an interface to a (GSM) USSD system. TLV Parameter Tag: TLV Parameter Type: 0x0501 1BYTE
SMS Delivery Reports with SMPP protocol There are two ways to verify the delivery of SMS messages. •
Query the status of the message
•
Request delivery reports from the provider
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 thi s message. This is done by sending a 'query_sm' packet to the provider. If the message reference is known by the provider, it responds with a 'query_sm_resp' packet. This packet holds the status of the message. This can be one of the following values:
Status Number
0 1 2
Status
SCHEDULED ENROUTE DELIVERED
Explanation
The message is scheduled for later sending. The message is enroute. The message was successfully delivered.
Status Number
Status
Explanation
The SMSC was unable to deliver the message in a EXPIRED specified amount of time.For instance when the phone was turned off. DELETED The message was deleted. The SMS was unable to deliver the message.For UNDELIVERABLE instance, when the number does not exist. ACCEPTED The SMS was accepted and will be send. UNKNOWN Unknown error occured. The message was rejected.The provider could have REJECTED blocked phonenumbers in this range. SKIPPED The message was skipped.
3 4 5 6 7 8 9
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. Request delivery reports from the provider The best way to check t he status of each message sent, is to ask for delivery reports. This can be done by setting the 'registered_delivery' value of the 'submit_sm' packet. This parameter can have one of the following values:
Value Meaning 0 Do not send delivery reports 1 Always send delivery reports 2 Send delivery report in case of an error 3 Send 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 t he 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
id
Meaning The message reference of the message.
Field sub
dlvrd submit date
Meaning
Sub-ID, not used. Value '1' when the message has been delivered, if the message is still pending '0'. Submission date and time.
done date stat err text
Date and time the status has changed, or message delivery time when stat is set to 'DELIVRD'. Current status of the message. Additional error code, provider specific. Part of the original message text.
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.
Monitoring SMPP sessions with Ethereal Introduction Finding errors in a SMPP connection is not a simple matter. Most SMPP SDK and API's do not have built-in advanced debugging facilities. Most of the times they only displaying an error message when the connection failes, or when it is not possible to submit a message, but if MO (incoming) messages get lost, or delivery reports aren't delivered, in most cases you have to contact the provider to find out the cause. The best way to debug SMPP connections by yourself, is by using a realtime packet sniffer or packet monitor. The program 'Ethereal' is such a packet sniffer, besides that it also has the capability to display the decoded packets of various communication protocols amongst them: •
SMPP (Short Message Peer to Peer);
•
MMSE (MMS Encapsulation messages);
•
WAP (Wireless Access Protocol);
•
UCP (Universal Computer Protocol);
•
and lots of non SMS- and MMS related protocols.
Installing Ethereal Because Ethereal is an open source program, you can download it from their website for free. You can start your (Windows) download here. If you are not using Windows, there are also versions availble for other platforms here. In this article we will only discuss the installation on Windows environments. When the download has completed, you can i nstall the program by starting the installer. The following screen will popup. Click 'Next' to start the installation.
(Click on the picture to enlarge) Read the license agreement and click 'I agree' to accept it, and proceed.
(Click on the picture to enlarge) Do not change the selections, and click 'Next' to continue.
(Click on the picture to enlarge) Do not change the settings on this screen and click 'Next'.
(Click on the picture to enlarge) Choose a directory in which to install the Ethereal program, and click 'Next' to continue.
(Click on the picture to enlarge) The following dialog asks you whether to install WinPcap. This program is required to capture the packets in Windows. Leave the first checkbox checked. If there are users on the PC that also have to monitor packets which do not have administrative rights you should also check the second checkbox. Click 'Install' to continue. WinPCap will be installed now.
(Click on the picture to enlarge)
After the installation has completed, click the 'Finish' button to finish the installation and start the program.
(Click on the picture to enlarge) When the program has started, the following screen will appear. At this moment only the menu items and buttons are visible because there is no monitoring session started yet. To start a new monitoring session, click the highlighted button (the second button from the left).
(Click on the picture to enlarge) The capture options will now appear. First you have to select the network card which is used to connect to the SMPP provider. When you are using a dialup connection, you do not have to change this option. You can also specify a capture filter, setting this filter causes the program to display only the packets wi th a specific protocol, portnumber, direction or IP address. By setting this filter you will only see the SMPP data. In the example the filter is set to: 'tcp port 2775', this means: only capture i ncoming and outgoing TCP packets on TCP port 2775. Most providers are using another TCP port. In t his case, replace 2775 with the TCP portnumber your provider is using. If you select all the options in the 'Display Options' group box, the data will be displayed realtime. Click 'Start' to begin capturing SMPP data.
(Click on the picture to enlarge) When capturing has started, the SMPP packets will be displayed on the capture screen. By selecting a packet, it will be decoded and a HEX dump will be displayed. Below is an example of a small SMPP session. You can see that the SMPP packets are decoded. In the packet view (uppermost window) you can see the packets that are sent and received. In this view you can select the packet you want to decode. In the next view the selected packet is displayed. In this example you can see the fields of a 'submit_sm' SMPP packet. In the view at the bottom at the screen, the HEX dump of the SMPP packet is displayed. Using the 'File' => 'Save' option from the file menu, you can also save the captured data. You can then for instance send your captured data to your SMPP provider or software vendor.
(Click on the picture to enlarge)