SMPP Protocol
NOTE:
To enable SMPP for your account, contact a Telesign expert. This option is available for full-service accounts only.
This page provides the necessary technical details for software architects and developers to create Short Message Peer-to-Peer (SMPP) clients to integrate with Telesign’s SMPP interface. These details include integration requirements, supported methods, bind types, authentication requirements, data coding schemes, timers, delivery reports, error codes, and other message details.
NOTE:
Telesign is compliant with SMPP versions 3.4 and 5.0.
About SMPP
SMPP is an open, industry standard protocol (see definition at Wikipedia) designed to simplify interconnections between various entities. SMPP also enables sending and receiving of short text messages (SMS) over the internet.
Key terms
- External Short Message Entity (ESME): A client application in an SMPP integration.
- Messaging Center (MC):
The server application in an SMPP integration, in this case the Telesign platform.
NOTE:
Connecting to Telesign using the SMPP protocol requires a thorough understanding of SMPP. To learn more before reading further about the specifics of Telesign SMPP integration, visit smpp.org. There you can also find reference documents for v3.4 and v5.0 of the specification (the versions that Telesign supports).
Message mode
The Telesign message mode is “Store and Forward”.
Required client features
The following SMPP features must be configured in each ESME:
Feature | Description |
---|---|
SMPP gateway address | The address of the Telesign MC (server) the client will be connecting to. |
Port | The port that the client will be connecting to and that the Telesign MC will be listening on. |
System ID | Identifies the client requesting to bind to the Telesign MC. Serves as a username. Type: C-Octet String Maximum Size: 16 octets. |
Password | Authenticates the client requesting to bind to the Telesign MC Type: C-Octet String Maximum Size: 9 octets |
Supported protocol data units
The Telesign MC supports the following protocol data unit (PDU) commands:
ESME to MC | MC to ESME |
---|---|
bind_transceiver | bind_transceiver_resp |
bind_transmitter | bind_transmitter_resp |
bind_receiver | bind_receiver_resp |
submit_sm | submit_sm_resp |
enquire_link | enquire_link_resp |
enquire_link_resp | enquire_link |
deliver_sm_resp | deliver_sm |
unbind | unbind_resp |
unbind_resp | unbind |
Supported session types
Telesign allows three types of ESME-initiated sessions:
- Transmitter (TX)
- Receiver (RX)
- Transceiver (TRX)
Clients can enable up to all three session types, although persistent TRX binds are preferred. Contact your Telesign Client Services representative to enable and configure these sessions.
Connection information
Use the following SMPP gateway address:
smpp.tsentcloud.com
And the following port:
3550
Telesign delivers web services from geographically-distanced data centers represented by the above endpoint.
Operational requirements
Clients must follow these operational requirements when connecting to Telesign via SMPP, in order for Telesign to provide the highest level of quality, security, and connectivity.
Clients must:
-
Have sufficient number of binds to support 100% of client traffic.
-
Make sure that the field with the SMPP gateway address is configurable. Occasionally Telesign may change the SMPP gateway address.
-
Make sure that application code is pointing to the Telesign-provided SMPP gateway address and not directly to the IP address.
-
Avoid whitelisting the Telesign gateway address by IP on any device residing on the client application’s path to the internet.
-
Have automatic failover logic in place to reroute traffic to the active binds available at any time.
-
Implement Transport Layer Security (TLS) v1.2 encryption for all SMPP communication.
Supported ciphers include:
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
- TLS_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
NOTE:
Telesign uses load balancing across multiple redundant MCs to maintain high availability and performance.
Authentication
Each ESME requesting to bind to the Telesign MC must provide a system ID for identification and a password for authentication.
Obtain these credentials in one of two ways:
-
Create them yourself:
- Go to your account page in TelePortal (the client portal for Telesign services).
- Go to the SMPP Credentials Generation section.
- Click the Create button. Your username (system ID) and password will be automatically generated.
-
Ask us to create them:
Ask your Telesign Client Services representative to create credentials for you. Once your account has been created, they will provide you with your username (System ID) and password.
NOTE:
SMPP passwords cannot be recovered for you by Telesign.
Password reset
You can either reset the SMPP password yourself in your account, or ask your Client Services representative to do so for you. Once the password is reset, the old password becomes obsolete, but only after a defined expiration window has elapsed.
This means that for a limited period of time two passwords can coexist.
Possible expiration windows for a reset password to become obsolete are:
- Immediately
- 1 hour
- 24 hours
- 7 days
- 30 days
- 60 days
- 90 days
If you are doing the reset yourself, select one of these options in your account when you reset the password. If CS is doing the reset for you, let them know which expiration window you want to be applied.
NOTE:
If one client uses more than one ESME to connect to Telesign, one set of credentials is shared for all binds.
TON and NPI parameters
Type of Number (TON) and Numbering Plan Identification (NPI) are special parameters in SMS messages that describe the type of the source and destination addresses for the message.
Before using a sender ID as a source address, send that sender ID to Telesign so it can be whitelisted. Once the sender ID has been whitelisted (if it is supported for the destination), set it in the submit_sm
PDU command by using the source address in each request. The source address is comprised of the source_addr_ton
, source_addr_npi
, and source_addr
fields.
Because each destination address is usually represented in full international format, set the destination TON value (dest_addr_ton
) in the submit_sm
PDU command to 1
(for International) and the destination NPI value (dest_addr_npi
) to 1
(for ISDN E163/E164). The destination address consists of those two fields as well as the dest_addr
field.
Supported data coding schemes
SMPP supports several data coding schemes (DCSs); indicate your chosen DCS using the data_coding
parameter. DCSs supported by Telesign and their corresponding parameter values are indicated below.
The default value is 0
.
Supported timers
The Telesign MC supports the following timers:
- Session Init Timer: Specifies the time lapse allowed between a network connection being established by a client and a
bind_transmitter
,bind_receiver
, orbind_transceiver
request being sent to the MC. After the timer expires, the network connection should be terminated. The Telesign MC has this timer set to 10s. - Enquire Link Timer: Specifies the time lapse allowed between operations after which the SMPP entity (ESME or MC) should interrogate whether its peer continues to have an active session. The
enquire_link
command is used to check the connectivity between the client and SMPP server, which can be issued from either entity. After the timer expires, anenquire_link
request should be initiated. The Telesign MC has this timer set to 30s. - Response Timer: Specifies the time lapse allowed between the SMPP request and the corresponding SMPP response. After the timer expires, the given operation is assumed to have failed. The Telesign MC has this timer set to 30s.
Delivery reports
The Telesign MC can provide delivery reports (DLRs) in response to a client request. To check the status of each message sent, set registered_delivery
in the submit_sm
packet to one of the following values:
Value | Meaning |
---|---|
0 | Do not send DLRs |
1 | Delivery receipt requested where final delivery outcome is delivery success or failure |
2 | Delivery receipt requested where the final delivery outcome is failure |
3 | Delivery receipt requested where the final delivery outcome is success |
The DLRs are sent to the client using the deliver_sm
PDU. To detect whether a deliver_sm
is a DLR or a message, check the esm_class
field. If bit 2 of the byte is set, it sends a DLR.
DLRs include information about how many parts a message was split into in order to be sent. This information is provided using the message_parts_count
parameter.
To use DLRs, the client has to setup a transceiver or receiver connection to the Telesign MC.
To be compatible with both SMPP v3.4 and v5.0, delivery status is provided in two ways each time:
- In the
short_message
parameter (withstat
anderr
fields) - In the
receipted_message_id
,message_state
, andnetwork_error_code
TLVs
Telesign routes DLRs based on system ID by default. So if you are connecting to Telesign via SMPP from multiple data centers, DLRs are sent randomly to any of your connected data centers. If you want responses to be sent to the exact same data center that sent the request, include the system_type
parameter in each submit_sm
request to specify the data center the response should be routed back to. Contact our Customer Support Team to get a list of values you can use for system_type
if you want to enable this type of routing.
Validity period parameter
The validity_period
parameter indicates the MC (Messaging Center) expiration time, after which the message
should be discarded if not delivered to the destination. The EXPIRED status will be returned for messages that exceeded validity period in operator's MC.
Validity period is optional parameter in the submit_sm
, but if set, it's format will be validated and message will be rejected via submit_sm_resp
if validation fails with the network_error_code 0x00000062
- Invalid message validity period (Expiry time)
.
Validity period can be defined using absolute time format or relative time format.
Absolute time format
Absolute time format is the default format used by SMPP. Scheduled delivery times, expiry times and message completion dates are specified in UTC format, including the quarter hour offset and direction symbol ‘+’ or ‘-’.
Absolute time is formatted as a 16-character string (encoded as a 17-octet C-octet String) “YYMMDDhhmmsstnnp” where:
Digits | Meaning |
---|---|
YY | year (00-99) |
MM | month (01-12) |
DD | day (01-31) |
hh | hour (00-23) |
mm | minute (00-59) |
ss | second (00-59) |
t | tenths of second (0-9) |
nn | Time difference in quarter hours between local time (as expressed in the first 13 octets) and UTC (Universal Time Constant) time (00-48). |
p | “+” Local time is in quarter hours advanced in relation to UTC time. “-” Local time is in quarter hours in relation to UTC time. |
Relative time format
Relative time format can be indicated by setting the UTC orientation flag to ‘R’ instead of ‘+’ or ‘-’. In this form, the MC interprets the time format as the number of years, months, days, hours, minutes and seconds from the current MC time.
Relative time is formatted as a 16 character string (encoded as a 17-octet C-octet String) “YYMMDDhhmmsstnnp” where:
Digits | Meaning |
---|---|
YY | year (00-99) |
MM | month (00-12) |
DD | day (00-31) |
hh | hour (00-23) |
mm | minute (00-59) |
ss | second (00-59) |
t | Unused. Should be set to ‘0‘ |
nn | Unused. Should be set to ‘00‘ |
p | “R” Local time is relative to the current MC time. |
According to SMPP v3.4 and v5.0 standard specification, day and month flags don’t allow values 0
in relative time format. Telesign will accept 0
for day and month and forward it that way, but cannot guarantee downstream providers or operators will support this usage.
For validity period support in specific markets, contact your Telesign Customer Success Manager (CSM).
Outbound SMS
Sending your own short messages is enabled in a Telesign SMPP integration by default.
Short message user data
Short message user data is the content of the SMS that you want the recipient to see. User data should be inserted in either the short_message
parameter or the message_payload
TLV. Use short_message to send a short message of up to 255 octets in size, including user data. Use message_payload
to send messages longer than 255 octets; in this case, the sm_length field should be set to 0. Both fields should not be used simultaneously. If both fields are used, Telesign MC ignores the short_message
parameter and uses only message_payload
.
Sending concatenated messages
The size of each message you send is limited by your specified encoding. A larger message can still be sent, however, by splitting it into connected parts; this is called a “concatenated message”. You have two options for sending a concatenated message:
- Split it yourself: Send a separate
submit_sm
command for each part of the message. To enable the end-user device to connect the messages, make use of the User Data Header (UDH) and UDH Indicator (UDHI) as described in the SMPP spec. Telesign provides you with a unique reference ID for each part. - Let Telesign split it: Send one
submit_sm
command, with a message that exceeds the limit. Telesign then automatically splits up the message for you, adding matching UDHs to each part. You will be charged separately for each part of the concatenated message. Telesign assigns a different reference ID to each part of the message, but thesubmit_sm_resp
from Telesign provides you only with the reference ID for the first part of the message. The DLR is returned after all parts of the message are delivered, but also refers to just the reference ID of the first part of the message.
Tracking messages
For each short message sent by the client, Telesign generates a reference ID. This is a 32-digit hex value used to identify the original message request. This value is unique for each submit_sm
request and is randomly generated by Telesign.
Telesign returns the reference ID in the message_id
parameter of the submit_sm_resp
PDU command immediately following the original request. Using the reference ID, the client can identify and track each request sent to Telesign MC.
Inbound SMS
You can also consume MO (Mobile Originating) messages over SMPP. Telesign delivers these messages using the deliver_sm
PDU and the short_message
parameter. For inbound SMS to work, it must be enabled by our Customer Support Team.
Tagged length values (TLVs)
These TLVs are supported when using SMPP to hit any Telesign API. Some are used for features that you must ask our Customer Support Team to enable.
For more information about using TLVs, go to these topics:
- SMS - SMPP TLVs - The technical details needed to develop SMPP clients using Telesign SMS.
- SMS Verify API - SMPP TLVs - The technical details for the TLVs that are supported when using SMPP to query Telesign SMS Verify API.
message_payload
Put user data here when sending a message longer than 255 octets.
Field | Octets Size | Type | Description |
---|---|---|---|
Parameter Tag | 2 | Integer | 0x0424 |
Length | 2 | Integer | Set to length of user data |
Value | Variable | Octet String | Short message user data |
mobile_country_code
Contains the mobile country code (MCC) for the destination phone number. Available in the deliver_sm
PDU used for sending DLRs. To use this tag, ask our Customer Support Team to turn on the associated feature.
Field | Octets Size | Type | Description |
---|---|---|---|
Parameter Tag | 2 | Integer | 0x0410 |
Length | 2 | Integer | Length of Value field in octets |
Value | Variable | Octet String | The mobile country code |
mobile_network_code
Contains the mobile network code (MNC) for the destination phone number. Available in the deliver_sm
PDU used for sending DLRs. To use this tag, ask our Customer Support Team to turn on the associated feature.
Field | Octets Size | Type | Description |
---|---|---|---|
Parameter Tag | 2 | Integer | 0x0411 |
Length | 2 | Integer | Length of Value field in octets |
Value | Variable | Octet String | The mobile network code |
price
The price from the operator of this transaction. Available in the deliver_sm
PDU used for sending DLRs. To use this tag, ask our Customer Support Team to turn on the associated feature.
Field | Octets Size | Type | Description |
---|---|---|---|
Parameter Tag | 2 | Integer | 0x0412 |
Length | 2 | Integer | Length of Value field in octets |
Value | Variable | Octet String | The price for this transaction, including the currency type. Example: 0.0075 USD |
Error codes
Telesign provides error information as part of the command_status
and error_status_code
parameters. Telesign supports both a complete set of SMPP-defined error codes as well as some Telesign-specific error codes.
In DLRs, Telesign provides status as a numeric code in the message_state
parameter and as an abbreviated description in the stat
field in the short_message
parameter:
message_state Value | state Value | Description |
---|---|---|
2 | DELIVRD | DELIVERED |
3 | EXPIRED | EXPIRED |
4 | DELETED | DELETED |
5 | UNDELIV | UNDELIVERABLE |
6 | ACCEPTD | ACCEPTED |
7 | UNKNOWN | UNKNOWN |
8 | REJECTD | REJECTED |
9 | SKIPPED | SKIPPED |
Telesign provides additional context in the err
field of the short_message
parameter. This field contains a hexadecimal value that is 3-octets long.
Possible values for this field are described below:
Hexadecimal Value | Description |
---|---|
0x00000000 | Successful Delivery |
0x00000008 | System Error |
0x0000000A | Invalid Source Address |
0x0000000B | Invalid Destination Address |
0x00000014 | Message Queue Full |
0x000000FF | Unknown Error |
0x00000401 | Send error |
0x00000402 | Other party is not connected |
0x00000403 | Unknown provider error |
0x00000404 | Unknown user error |
0x00000405 | Invalid request |
0x00000407 | Absent subscriber error |
0x00000408 | Generic error for system exceptions |
0x000004A0 | Temporary phone error |
0x000004A1 | Permanent phone error |
0x000004A2 | Gateway/network cannot route message |
0x000004A3 | Message expired before delivery |
0x000004A4 | SMS not supported |
0x000004A5 | Message blocked by customer request |
0x000004A6 | Message blocked by Telesign |
0x000004A7 | Invalid/unsupported message content |
0x000004A8 | Transaction not attempted |
0x000004A9 | Not authorized |
0x000004AA | Status not available |
0x000004AB | DLR sending could not be guaranteed. Please check status of the message manually. |
0x000004AC | This product is not enabled for this Customer ID |
0x000004AD | Not allowed host |
0x000004AE | SMS exceeded transaction hard cap. Request denied. |
0x000004AF | Invalid country code |
0x000004B0 | Campaign error |
0x000004B1 | Carrier rejected - temporary problem |
0x000004B2 | Carrier rejected - permanent error |
0x000004B3 | Error on gateway - temporary error |
0x000004B4 | Error on gateway - permanent error |
0x000004B5 | Parameters problem |
0x000004B6 | Message blocked by subscriber action or request |
0x000004B7 | Subscriber low on credit |
0x000004B8 | Roaming error |
0x000004B9 | Mobile number portability error |
0x000004BA | Suspected spam |
0x000004BC | Message blocked due to high risk recommendation |
0x000004BD | The message was delivered, but a final DLR never arrived. This error only exists for DLRs with a status of EXPIRED. |
0x000004BF | Message not sent due to the price exceeding your set maximum price. |
0x000004C0 | Destination blocked by prefix |
0x000004C1 | Content sent is not allowed |
0x000004C2 | The Sender ID included in this request cannot be used to send messages to this destination phone number. The Sender ID may either be blocklisted for this country or needs to be added to a whitelist for this country. |
Additional error context can also be found in the network_error_code
field.
SMPP Abbreviations
Abbreviation | Definition |
---|---|
DCS | Data Coding Scheme |
DLR | Delivery Report |
ESME | External Short Message Entity |
MC | Messaging Center |
NPI | Numbering Plan Identification |
PDU | Protocol Data Unit |
SMPP | Short Message Peer-to-Peer |
TLS | Transport Layer Security |
TLV | Tag Length Value |
TON | Type of Number |
UDH | User Data Header |
Updated about 2 months ago