PDU Details

A detailed explanation of each of the supported PDU types.

As per the SMPP 3.4 specification, each PDU has a mandatory header section that is the same for each PDU transmitted. These will not be outlined below (except for the command_status parameter in the submit_sm_resp PDUs).

Only parameters from the PDU body (mandatory parameters) and optional parameters are explained.

📘

NOTE

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

PDU Types

The following PDU types and their responses are supported:

Command IDValue (hex)Description
bind_receiver0x00000001Establish a receiver bind.
bind_transmitter0x00000002Establish a transmitter bind.
bind_transceiver0x00000009Establish a transceiver bind.
submit_sm0x00000004Submit message to the SMSC for onward delivery to mobile device.
deliver_sm0x00000005Send message to ESME from SMSC (typically delivery receipt or MO message).
unbind0x00000006Unbind from SMSC and close SMPP session.
enquire_link0x00000015Initiate a check to confirm ESME/SMSC is still reachable.
generic_nack0x80000000Acknowledge unrecognized or corrupt PDU.

📘

NOTE

data_sm, query_sm, cancel_sm, replace_sm and submit_sm_multi are not supported.

Bind PDU

An SMPP bind_receiver, bind_transmitter or bind_transceiver PDU request has a fixed set of fields many of which are irrelevant to us.

NameDescription
system_idYour SMPP username (maximum of 15 characters allowed)
passwordYour SMPP password (maximum of 8 characters allowed)
system_typeIgnored with the exception of "test" which is no longer supported and will be rejected.
interface_versionThe SMPP version that you want to use. Only version 3.4 (0x34) is supported.
addr_tonIgnored
addr_npiIgnored
address_rangeIgnored

enquire_link

To avoid being disconnected, you need to send at least one enquire_link PDU on every successfully established connection (bound session) every 2 minutes.

It’s recommended that you send the enquire_link PDU once 30 seconds to timeously detect any lost connections. SMSPortal will also send an enquire_link every 30 seconds to detect any lost connections.

submit_sm

You can use the submit_sm PDU to send us your MT messages. Like a bind request, the submit_sm PDU request also has a couple of fields that are unused by our platform and can safely be ignored.

NameDescription
service_typeIgnored
source_addr_tonIgnored but needs to be a valid value as per the SMPP specification
source_addr_npiIgnored but needs to be a valid value as per the SMPP specification
source_addrThe sender ID or valid two-way number. If the sender ID is not valid on the network, this will be replaced by SMSPortal using a valid Sender ID. The original source_addr you provided will still be returned in the deliver_sm for matching purposes.
dest_addr_tonIgnored but needs to be a valid value as per the SMPP specification
dest_addr_npiIgnored but needs to be a valid value as per the SMPP specification
destination_addrThe mobile number of the handset to which the message must be delivered (MSISDN).

Note: The MSISDN needs to be in international numbering format (E.164) without any symbols (e.g. plus sign) or it will be rejected with an ESME_RINVDSTADR error response.
esm_classMessage mode and type. Refer to the SMPP specification for more information.
protocol_idIgnored
priority_flagIgnored
schedule_delivery_timeNot supported - Any messages with a scheduled time are overridden and sent out for immediate delivery.
validity_periodThe validity period of the message. If the first attempt fails, the mobile network operator will make several delivery attempts during this timeframe. This is usually specified using the absolute time format but relative time format is also valid.

SMSPortal's default validity_period is 48 hours if no value is provided.

For One-Time Passwords, we recommend setting the validity to a shorter period (e.g. 1 hour). This will make the message expire when the content is no longer relevant and potentially force the mobile network operator to perform more retries within a short time frame after sending the message, hence increasing the chance of delivery.
registered_deliverySet 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_flagIgnored
data_codingSMSC default character set is GSM7
See Data Coding Schemes for further information.
sm_default_msg_idIgnored
sm_lengthThe length of the short_message field. Valid values are 0 – 254.
short_messageThe contents of the message to be sent.
sar_msg_ref_num
sar_total_segments
sar_segment_seqnum
Optional parameters; see SMPP specification on how they should be constructed.

The sar parameters can be used to identify concatenated message parts instead of encoding UDH in the short_message field.
Customer ReferenceVendor Specific TLV Type 0x1400

Can be used when generating reports using the control panel.
Cost Center ReferenceVendor Specific TLV Type 0x1401

Can be used when generating reports using the control panel.

submit_sm_resp

NameDescription
command_statusAs per the SMPP specification
message_idThe message_id will always be returned as a 64 (or less) character string as per the SMPP specification.

deliver_sm for delivery receipts (DLR)

DLRs will be sent to you via a deliver_sm PDU. The fields are exactly the same as a submit_sm PDU, but there will be differences in which fields you are free to ignore, and which you are not.

NameDescription
service_typeAlways NULL, can be ignored
source_addr_tonAutodetected value based on the value returned by the Mobile Network Operator
source_addr_npiAutodetected value based on the value returned by the Mobile Network Operator
source_addrThe value that you specified in the destination_addr field of the original submit_sm PDU.
dest_addr_tonAutodetected value based on the value returned by the Mobile Network Operator
dest_addr_npiAutodetected value based on the value returned by the Mobile Network Operator
destination_addrThe value that you specified in the source_addr field of the original submit_sm PDU.
esm_classUsually 4 (can be used to differentiate between a DLR and MO message).

Refer to the SMPP specification for more information.
protocol_idAlways 0, can be ignored.
priority_flagAlways 0, can be ignored.
schedule_delivery_timeAlways NULL, can be ignored.
validity_periodAlways NULL, can be ignored.
registered_deliveryAlways 0, can be ignored.
replace_if_present_flagAlways 0, can be ignored.
data_codingAlways 0, the SMSC always uses the GSM alphabet in delivery receipts.
sm_default_msg_idAlways 0, can be ignored.
sm_lengthThe length of the short_message field.
short_messageInformational content of the delivery receipt, see Delivery receipt short_message_format below.
receipted_message_idOptional Parameter: The same message_id that was returned in the submit_sm_resp PDU when the message was accepted.

🚧

IMPORTANT

If you are not bound with a receiver or transceiver, the SMSC will queue delivery receipts for a maximum of 12 hours or until a maximum queue size of 1 million PDUs has been reached, after which the oldest deliver_sm PDUs will be discarded to make room for newer deliver_sm PDUs.

deliver_sm for MO messages

MOs will also be sent to you via a deliver_sm PDU. The fields are exactly the same as a submit_sm PDU, but there will be differences in which fields you are free to ignore, and which you are not.

NameDescription
service_typeAlways NULL, can be ignored
source_addr_tonAutodetected and set according to the value of source_addr.
source_addr_npiAutodetected and set according to the value of source_addr.
source_addrThe sender of the MO
dest_addr_tonAutodetected and set according to the value of destination_addr.
dest_addr_npiAutodetected and set according to the value of destination_addr.
destination_addrThe value that you specified in the source_addr field of the original submit_sm PDU.

On request, this setting can be changed to return the value that the mobile network operator provided in the source_addr field.
esm_classTypically 0 or 64. A value of 64 (UDHI) indicates the presence of a user data header in the short_message field.

Refer to the SMPP specification for more information.
protocol_idAlways 0, can be ignored.
priority_flagAlways 0, can be ignored.
schedule_delivery_timeAlways NULL, can be ignored.
validity_periodAlways NULL, can be ignored.
registered_deliveryAlways 0, can be ignored.
replace_if_present_flagAlways 0, can be ignored.
data_codingWill 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 8 for Unicode message content which will be in the UCS-2 character set.
sm_default_msg_idAlways 0, can be ignored.
sm_lengthThe length of the short_message field.
short_messageThe MO message content.
receipted_message_idOptional Parameter: The same message_id that was returned in the submit_sm_resp PDU when the message was accepted.

🚧

IMPORTANT

If you are not bound with a receiver or transceiver, the SMSC will queue MO messages for a maximum of 12 hours or until a maximum queue size of 1 million PDUs has been reached, after which the oldest deliver_sm PDUs will be discarded to make room for newer deliver_sm PDUs.

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 standard format as per the SMPP specification is used:

id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:EEE Text: . . . . . . . . . .

*id:03/199440/UKQKF/5XrwwB/00004 sub:000 dlvrd:000 submit date:2111152111 done date:2111152111 stat:DELIVRD err:000 text:Hello World Test Mes*
NameDescription
idThe same message_id that was returned in the submit_sm_resp when the message was accepted.
subAlways set to 0
dlvrdAlways set to 0
submit dateThe date and time when the ESME submitted the message to the SMSC.
done dateThe date and time when the SMSC received the specified status.
statDELIVRD, UNDELIV, BLIST, ACCEPTD or REJECTD.

See Delivery Statuses for more information.
errAlways 000 for successful and failed delivery. The only exception is 001 which indicates that number is on the DNC list and that SMS delivery is restricted due to a request by the owner or WASPA.
textThe first 20 characters of the original submit_sm as per the SMPP specification.

deliver_sm_resp

NameDescription
message_idIgnored