Write to email@example.com.
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.
TeleSign is compliant with SMPP versions 3.4 and 5.0.
- About SMPP
- Key Terms
- Message Mode
- Required Client Features
- Supported Protocol Data Units
- Supported Session Types
- Connection Information
- TON and NPI Parameters
- Supported Data Coding Schemes
- Supported Timers
- Delivery Reports
- Outbound SMS
- Inbound SMS
- Tagged Length Values (TLVs)
- Error Codes
- SMPP Abbreviations
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.
- 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.
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).
The TeleSign message mode is “Store and Forward”.
Required Client Features
The following SMPP features must be configured in each ESME:
|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|
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.
Use the following SMPP gateway address:
And the following port:
TeleSign delivers web services from geographically-distanced data centers represented by the above endpoint.
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.
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.1 or 1.2 encryption for all SMPP communication. Supported ciphers include:
TeleSign uses load balancing across multiple redundant MCs to maintain high availability and performance.
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.
SMPP passwords cannot be recovered for you by TeleSign.
You can either reset the SMPP password yourself in TelePortal, 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:
- 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 TelePortal when you reset the password. If CS is doing the reset for you, let them know which expiration window you want to be applied.
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
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 (
1 (for ISDN E163/E164). The destination address consists of those two fields as well as the
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||Default alphabet, GSM 03.38|
|3||Latin 1 (ISO-8859-1)|
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_transceiverrequest 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_linkcommand is used to check the connectivity between the client and SMPP server, which can be issued from either entity. After the timer expires, an
enquire_linkrequest 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.
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:
|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
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
- In the
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 your CSM to get a list of values you can use for
system_type if you want to enable this type of routing.
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
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_smcommand 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_smcommand, 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 the
submit_sm_respfrom 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.
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.
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 your CSM.
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 your CSM to enable.
Put user data here when sending a message longer than 255 octets.
|Length||2||Integer||Set to length of user data|
|Value||Variable||Octet String||Short message user data|
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 your CSM to turn on the “MCC” feature.
|Length||2||Integer||Length of Value field in octets|
|Value||Variable||Octet String||The mobile country 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 your CSM to turn on the “MNC” feature.
|Length||2||Integer||Length of Value field in octets|
|Value||Variable||Octet String||The mobile network code|
The price from the operator of this transaction. Available in the
deliver_sm PDU used for sending DLRs. To use this tag, ask your CSM to turn on the “Price” feature.
|Length||2||Integer||Length of Value field in octets|
|Value||Variable||Octet String||The price for this transaction, including the currency type.
TeleSign provides error information as part of the
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
|message_state Value||state Value||Description|
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. TeleSign-specific codes are in italics:
||Invalid Source Address|
||Invalid Destination Address|
||Message Queue Full|
||Other party is not connected|
||Unknown provider error|
||Unknown user error|
||Absent subscriber error|
||Generic error for system exceptions|
||Temporary phone error|
||Permanent phone error|
||Gateway/network cannot route message|
||Message expired before delivery|
||SMS not supported|
||Message blocked by customer request|
||Message blocked by TeleSign|
||Invalid/unsupported message content|
||Transcation not attempted|
||Status not available|
||DLR sending could not be guaranteed. Please check status of the message manually.|
||Invalid country code|
||Carrier rejected - temporary problem|
||Carrier rejected - permanent error|
||Error on gateway - temporary error|
||Error on gateway - permanent error|
||Message blocked by subscriber action or request|
||Subscriber low on credit|
||Mobile number portability error|
||Transaction rejected because the destination number has a high risk score. (The score is determined by you with help from your CSM.)|
||The message was delivered, but a final DLR never arrived. This error only exists for DLRs with a status of EXPIRED.|
Additional error context can also be found in the
|DCS||Data Coding Scheme|
|ESME||External Short Message Entity|
|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|