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:

Supported protocol data units

The Telesign MC supports the following protocol data unit (PDU) commands:

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 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, 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:

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.

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:

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:

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

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.

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.

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.

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:

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:

Additional error context can also be found in the network_error_code field.

SMPP Abbreviations