PDU Details
Overview
Below are detailed explanations of some of the supported PDUs.
As per the SMPP specification, each PDU has a mandatory header section that is the same for each PDU transmitted between ESME and SMSC. These will not be discussed below (except for the command_status parameter in the submit_sm_resp and data_sm_resp PDUs).
Only parameters from the PDU body (mandatory parameters) and optional parameters are discussed.
Note: If an optional parameter is not mentioned, then it is not supported/is ignored.
Bind PDUs (ESME to SMSC)
All three different bind PDUs are identical and therefore only listed once here. It only contains a body and no optional parameters.
Note: If the ESME has 10 consecutive unsuccessful login (bind) attempts to the SMSC, the ESME’s IP address will be blocked for 60 seconds.
|
Field name |
Description |
|---|---|
|
system_id |
The ESME’s API username; mandatory and a maximum of 15 characters allowed |
|
password |
The ESME’s API password; mandatory and a maximum of 8 characters allowed |
|
system_type |
The ESME’s API ID; mandatory and must be numeric |
|
interface_version |
The SMPP version that the ESME wants to use; must be 0x33 or 0x34 |
|
addr_ton |
ignored |
|
addr_npi |
ignored |
|
address_range |
ignored |
enquire_link PDU (ESME to SMSC)
The ESME needs to send at least one enquire_link PDU on every successfully established connection (bound session) to the SMSC once every five minutes to avoid being disconnected.
It’s recommended that you send the enquire_link PDU once per minute so that the ESME can timeously detect any lost connections.
submit_sm and data_sm PDUs (ESME to SMSC)
Note: Fields marked with * are only available in the submit_sm PDU
|
Field Name |
Description |
|---|---|
|
service_type |
ignored |
|
source_addr_ton |
ignored |
|
source_addr_npi |
ignored |
|
source_addr |
The ESME’s registered Sender ID or valid two-way number. Sender IDs need to be registered within your account before they can be used but note that alphanumeric Sender ID is not available on all networks. |
|
dest_addr_ton |
ignored |
|
dest_addr_npi |
ignored |
|
destination_addr |
The mobile number of the handset to which the message must be delivered (MSISDN). |
|
esm_class |
If the short_message or message_payload field starts with UDH content, then the UDHI bit should be set (0x40). All other values are ignored. |
|
protocol_id * |
ignored |
|
priority_flag * |
As per SMPP specification. The value is passed through to our suppliers unchanged. |
|
schedule_delivery_time * |
ignored |
|
validity_period * |
ignored |
|
registered_delivery |
Set to 1 to receive delivery receipts when delivery was successful or failed. Set to 2 to receive delivery receipts only when delivery failed. All other values are ignored (i.e. no delivery receipt will be generated). |
|
replace_if_present_flag * |
ignored |
|
data_coding |
The SMSC default character set is GSM, as per https://en.wikipedia.org/wiki/GSM_03.38. However, national language shift tables are not supported. The ESME can use data_coding 2 or 4 for 8-bit (binary) messages. For Unicode message (UCS-2BE) use data_coding 8. The other values (e.g. 1 for ASCII, 3 for ISO-8859-1) are not officially supported, however you can try to use them if you are unable to specify your message content in GSM format. MWI control as per the SMPP specification is not supported and will be ignored. Message class control is supported as per the GSM 03.38 specification. For instance, to specify a plain text flash message, a data_coding value of 0x10 or 0xF0 should be used. |
|
sm_default_msg_id * |
ignored |
|
sm_length * |
The length of the short_message field. Set to 0 if sending an empty message or using the message_payload TLV. Valid values are 0 – 254. If you want to send a message longer than 254 octets, use the message_payload TLV instead. |
|
short_message * |
The content of the message to be sent, cannot be used in conjunction with the message_payload optional parameter. |
|
Optional parameters; see SMPP 3.4 specification on how they should be constructed |
|
|
sar_msg_ref_num |
The sar parameters can be used to identify concatenated message parts instead of encoding UDH in the short_message or message_payload fields. All three parameters must be used together: if one is missing the others will be ignored, and they also cannot be used if the UDHI flag is set in the esm_class parameter. |
|
sar_total_segments |
|
|
sar_segment_seqnum |
|
|
message_payload |
The ESME must use this parameter in a data_sm PDU and should use this parameter in a submit_sm PDU to send messages longer than 254 octets, in which case the sm_length field should be set to zero and the short_message field set to NULL. The SMSC supports a maximum of 5600 octets excluding any user data header. |
|
Vendor-specific optional parameters – see TLV section for more details |
|
|
Client Message ID |
A message ID defined by the ESME for message tracking. Up to 32 characters allowed, anything longer will cause the parameter to be ignored. It will be returned to the ESME in the delivery receipt (if enabled via registered_delivery). |
|
Gateway Escalation |
Prompts an escalation to an alternative (more expensive) route, if messages are queued or delayed on the least-cost routes. If the ESME is using SMPP version 3.3 or if the parameter is not specified, the default value as configured in the ESME’s Developers’ Central account will be used (by default, gateway escalation is turned off). |
|
Delivery Queue |
Delivers the message through one of three queues assigned to each client account. Messages in the highest priority queue will be delivered first. If the ESME is using SMPP version 3.3 or if the parameter is not specified, the default value as configured in the ESME’s Developers’ Central account will be used (by default, the lowest priority queue will be used). |
|
Maximum Credits |
This parameter can be used to limit the cost of a message. It overrides the maximum charge associated with message delivery, as set by the routing profiles selected within the ESME’s Developers’ Central account. If the ESME is using SMPP version 3.3 or if the parameter is not specified, the default value as configured in the ESME’s Developers’ Central account will be used (by default, no maximum credit cost will apply). |
|
Mobile Originated |
This is only applicable to clients that have subscribed to a two-way messaging service. We route via a pre-defined carrier to enable the ability for a reply to be received. If the ESME is using SMPP version 3.3 or if the parameter is not specified, the default value as configured in the ESME’s Developers’ Central account will be used (by default, mobile originated is turned off). |
|
Required Features |
Some parameters and features are not set as “required” by default and may be dropped if the least-cost route does not support them. Set this parameter to ensure that the features set when an SMS is sent are supported by the gateway used. If the ESME is using SMPP version 3.3 or if the parameter is not specified, the default value as configured in the ESME’s Developers’ Central account will be used (by default, no required features are set). |
| Bypass DNC Check
|
Specify this parameter to bypass the destination country’s “Do Not Contact/Disturb” list check if the message content allows for such a check to be bypassed (e.g. sending transactional messages and not marketing content). Allowed values are 0 and 1. Specifying any other value will result in the message being rejected with command_status = 0x000000C4 (Invalid Optional Parameter Value) in the submit_sm_resp PDU. If the ESME is using SMPP version 3.3 or if the parameter is not specified, then the default action of always doing a DNC list check will apply. If the destination address is found to be on a country’s DNC list, the message will be rejected with command_status = 0x0000000B (Invalid Dest Addr) in the submit_sm_resp PDU. |
submit_sm_resp and data_sm_resp PDUs (SMSC to ESME)
|
Field name |
Description |
||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
command_status |
Apart from the list of possible values found in the SMPP specification, the following SMSC-specific values can also be returned:
|
||||||||||
|
message_id |
The SMSC will only return a message ID if the command_status field is 0 (i.e. the message was accepted by the SMSC). The message_id will always be 32 alphanumeric characters. |
deliver_sm PDU (SMSC to ESME) used for delivery receipts (DLR)
NOTE: If the ESME is not bound as a receiver or transceiver, the SMSC will queue delivery receipts for a maximum of seven days, after which they will be discarded. If a message has not transitioned into a final state within five days, then no delivery receipt will be created.
|
Field name |
Description |
|---|---|
|
service_type |
The Clickatell credit cost of the message. |
|
source_addr_ton |
These will be the values that the ESME specified in the destination address fields of the original submit_sm PDU. |
|
source_addr_npi |
|
|
source_addr |
|
|
dest_addr_ton |
These will be the values that the ESME specified in the source address fields of the original submit_sm PDU. |
|
dest_addr_npi |
|
|
destination_addr |
|
|
esm_class |
Always 4 (use this to differentiate between a DLR and MO message). |
|
protocol_id |
Always 0, can be ignored. |
|
priority_flag |
Always 0, can be ignored. |
|
schedule_delivery_time |
Always NULL, can be ignored. |
|
validity_period |
Always NULL, can be ignored. |
|
registered_delivery |
Always 0, can be ignored. |
|
replace_if_present_flag |
Always 0, can be ignored. |
|
data_coding |
Always 0, the SMSC always uses the GSM alphabet in delivery receipts. |
|
sm_default_msg_id |
Always 0, can be ignored. |
|
sm_length |
The length of the short_message field. |
|
short_message |
Informational content of the delivery receipt, see below |
|
Optional parameters; see SMPP 3.4 specification on how they are constructed. |
|
|
network_error_code |
The Clickatell error code indicating the reason why delivery failed. This parameter will be omitted if delivery was successful. |
|
message_state |
The status of the message. |
|
receipted_message_id |
The same 32 alphanumeric character message_id that was returned in the submit_sm_resp or data_sm_resp PDU when the message was accepted. |
|
Vendor-specific optional parameters; see TLV section for more details |
|
|
Client Message ID |
The message ID specified by the ESME in the submit_sm PDU. If no client message ID was provided in the submit_sm PDU, then no parameter will be returned in the deliver_sm PDU. |
|
Network |
The ID of the mobile network operator (MNO) that the handset belongs to. The parameter will only be specified if the feature is enabled on the ESME’s account. |
Delivery receipt short_message_format
The short_message parameter in the deliver_sm PDU for a delivery receipt will contain report information regarding the delivery result of the message. The format will be:
id:xxx sub:001 dlvrd:NNN submit date:YYMMDDHHMMSS done date:YYMMDDHHMMSS stat:xxx err:000 text: |
|
Field name |
Description |
|---|---|
|
id |
The same 32 alphanumeric character message_id that was returned in the submit_sm_resp or data_sm_resp PDU when the SMSC accepted the message. |
|
sub |
Always 001. |
|
dlvrd |
Will be 001 if delivery was successful, else 000. |
|
submit date |
The date and time when the ESME submitted the message to the SMSC. |
|
done date |
The date and time when the message transitioned into the specified status. |
|
stat |
DELIVRD, UNDELIV, or REJECTD. |
|
err |
Always 000, for successful and failed delivery. The network_error_code optional parameter will contain the Clickatell delivery error code. |
|
text |
Always empty. |
deliver_sm PDU (SMSC to ESME) used for MO messages
Note: If the ESME is not bound as a receiver or transceiver, the SMSC will queue MO messages for a maximum of seven days, after which they will be discarded.
|
Field Name |
Description |
|---|---|
|
service_type |
The ESME’s API ID associated with the two-way number. |
|
source_addr_ton |
Set according to the value of source_addr. |
|
source_addr_npi |
Set according to the value of source_addr. |
|
source_addr |
The sender of the MO message. |
|
dest_addr_ton |
Set according to the value of destination_addr. |
|
dest_addr_npi |
Set according to the value of destination_addr. |
|
destination_addr |
The ESME’s two-way number to which the MO message was sent. |
|
esm_class |
Will be 0 or 64. A value of 64 (UDHI) indicates the presence of user data header in the short_message field. |
|
protocol_id |
Always 0, can be ignored. |
|
priority_flag |
Always 0, can be ignored. |
|
schedule_delivery_time |
Always NULL, can be ignored. |
|
validity_period |
Always NULL, can be ignored. |
|
registered_delivery |
Always 0, can be ignored. |
|
replace_if_present_flag |
Always 0, can be ignored. |
|
data_coding |
Will be 0 for plain-text message content which will be in the SMSC’s default character set of GSM as per https://en.wikipedia.org/wiki/GSM_03.38 Will be 4 for binary message content. Will be 8 for Unicode message content which will be in the UCS-2BE character set. |
|
sm_default_msg_id |
Always 0, can be ignored. |
|
sm_length |
The length of the short_message field. |
|
short_message |
The MO message content. |
|
Vendor-specific optional parameters; see TLV section for more details |
|
|
Linked MT Message ID |
If MT message linking is enabled on the ESME’s two-way setup, this parameter will contain the 32 alphanumeric character message ID of the original MT message that this MO message is in reply to. |
|
MO Message ID |
A unique 32 alphanumeric character string to identify the message at the SMSC. This message ID can be used when contacting support if there are any issues regarding the message. |
|
Network |
The ID of the mobile network operator (MNO) that the handset (sender) belongs to. The parameter will only be specified if the feature is enabled on the ESME’s two-way setup. |
|
MO Keyword |
By default, if the ESME is using a keyword two-way service, the destination address field will contain the ESME’s two-way number and the keyword, separated by the colon ‘:’ character, e.g. 35050:sport If the ESME would prefer to receive the two-way number and keyword separately, it can be enabled on the ESME’s two-way setup, in which case the destination_addr field will only contain the two-way number, and the MO keyword TLV will contain the keyword. |
deliver_sm_resp PDU (ESME to SMSC)
|
Field Name |
Description |
|---|---|
|
message_id |
ignored |
Submit a Comment
Other Resources
Ask the Community
Visit Stack Overflow to join our community of developers and find the answer you need
Contact Support
Contact our support team and one of our agents will be in touch with you to answer any questions you have