SMPP Protocol

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.

Contents

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.1 or 1.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:

  1. Create them yourself:
    1. Go to your account page in TelePortal (the client portal for TeleSign services).
    2. Go to the SMPP Credentials Generation section.
    3. Click the Create button. Your username (system ID) and password will be automatically generated.
  2. 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 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:

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

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.

Value Meaning
0 Default alphabet, GSM 03.38
1 GSM 03.38
3 Latin 1 (ISO-8859-1)
8 Unicode

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, or bind_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, an enquire_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 (with stat and err fields)
  • In the receipted_message_id, message_state, and network_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.

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 the submit_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.

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 Transcation 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 score
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.

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