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:

FeatureDescription
SMPP gateway addressThe address of the Telesign MC (server) the client will be connecting to.
PortThe port that the client will be connecting to and that the Telesign MC will be listening on.
System IDIdentifies the client requesting to bind to the Telesign MC. Serves as a username.

Type: C-Octet String

Maximum Size: 16 octets.
PasswordAuthenticates 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 MCMC to ESME
bind_transceiverbind_transceiver_resp
bind_transmitterbind_transmitter_resp
bind_receiverbind_receiver_resp
submit_smsubmit_sm_resp
enquire_linkenquire_link_resp
enquire_link_respenquire_link
deliver_sm_respdeliver_sm
unbindunbind_resp
unbind_respunbind

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:

  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.

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

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:

ValueMeaning
0Do not send DLRs
1Delivery receipt requested where final delivery outcome is delivery success or failure
2Delivery receipt requested where the final delivery outcome is failure
3Delivery 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.

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.

FieldOctets SizeTypeDescription
Parameter Tag2Integer0x0424
Length2IntegerSet to length of user data
ValueVariableOctet StringShort 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.

FieldOctets SizeTypeDescription
Parameter Tag2Integer0x0410
Length2IntegerLength of Value field in octets
ValueVariableOctet StringThe 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.

FieldOctets SizeTypeDescription
Parameter Tag2Integer0x0411
Length2IntegerLength of Value field in octets
ValueVariableOctet StringThe 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.

FieldOctets SizeTypeDescription
Parameter Tag2Integer0x0412
Length2IntegerLength of Value field in octets
ValueVariableOctet StringThe 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 Valuestate ValueDescription
2DELIVRDDELIVERED
3EXPIREDEXPIRED
4DELETEDDELETED
5UNDELIVUNDELIVERABLE
6ACCEPTDACCEPTED
7UNKNOWNUNKNOWN
8REJECTDREJECTED
9SKIPPEDSKIPPED

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 ValueDescription
0x00000000Successful Delivery
0x00000008System Error
0x0000000AInvalid Source Address
0x0000000BInvalid Destination Address
0x00000014Message Queue Full
0x000000FFUnknown Error
0x00000401Send error
0x00000402Other party is not connected
0x00000403Unknown provider error
0x00000404Unknown user error
0x00000405Invalid request
0x00000407Absent subscriber error
0x00000408Generic error for system exceptions
0x000004A0Temporary phone error
0x000004A1Permanent phone error
0x000004A2Gateway/network cannot route message
0x000004A3Message expired before delivery
0x000004A4SMS not supported
0x000004A5Message blocked by customer request
0x000004A6Message blocked by TeleSign
0x000004A7Invalid/unsupported message content
0x000004A8Transaction not attempted
0x000004A9Not authorized
0x000004AAStatus not available
0x000004ABDLR sending could not be guaranteed. Please check status of the message manually.
0x000004ACThis product is not enabled for this Customer ID
0x000004ADNot allowed host
0x000004AESMS exceeded transaction hard cap. Request denied.
0x000004AFInvalid country code
0x000004B0Campaign error
0x000004B1Carrier rejected - temporary problem
0x000004B2Carrier rejected - permanent error
0x000004B3Error on gateway - temporary error
0x000004B4Error on gateway - permanent error
0x000004B5Parameters problem
0x000004B6Message blocked by subscriber action or request
0x000004B7Subscriber low on credit
0x000004B8Roaming error
0x000004B9Mobile number portability error
0x000004BASuspected spam
0x000004BCMessage blocked due to high risk recommendation
0x000004BDThe message was delivered, but a final DLR never arrived. This error only exists for DLRs with a status of EXPIRED.
0x000004BFMessage not sent due to the price exceeding your set maximum price.
0x000004C0Destination blocked by prefix
0x000004C1Content sent is not allowed
0x000004C2The 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

AbbreviationDefinition
DCSData Coding Scheme
DLRDelivery Report
ESMEExternal Short Message Entity
MCMessaging Center
NPINumbering Plan Identification
PDUProtocol Data Unit
SMPPShort Message Peer-to-Peer
TLSTransport Layer Security
TLVTag Length Value
TONType of Number
UDHUser Data Header