PDU Details

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.

If an optional parameter is not mentioned, then it is not supported/ignored.

 

Bind PDUs (ESME to SMSC)

All three different bind PDUs are identical and so 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. Learn more about Sender ID.

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).

 

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.

Hex value

Description

0x00000400

This implies that the SMSC is not currently routing messages to this network prefix.

0x00000401

The ESME's account is out of credit.

0x00000404

A value was specified in the data_coding parameter (not 0) but no message content was specified.  In other words, if the ESME wants to send an empty message, set data_coding to 0.

0x000004FF

The ESME sent a non-bind PDU but is not bound.

 

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