| title | excerpt | updated |
|---|---|---|
SMPP Technical Specifications |
Discover the technical specifications of the OVHcloud SMPP solution |
2025-03-05 |
Discover the technical specifications of the OVHcloud SMPP solution.
- PDU: Protocol Data Unit is the object/entity for exchanging requests and responses
- SMPP: Short Message Peer to Peer Protocol
- SMSC: Short Message Service Centre (server)
- ESME: External Short Message Entity (client)
- UDH: User Data Header
- SM: Short Message
- DLR: Delivery Receipt
- PTT: Premium Tracking Technical is an error code communicated in the message of a DLR
- MT: Mobile Terminated
- MO: Mobile Originated
For more explanation of abbreviations, see page 10 of smpp.org's SMPP specifications.
The SMPP (Short Message Peer-to-Peer) is a protocol for exchanging SMS messages to telecom operators and by content providers. It typically uses two TCP/IP connections, one for sending and one for receiving data.
- The protocol is standardised and can be integrated with many market tools
- It provides high throughput with low latency
Client SMS sending application (ESME) has three means of communication with SMSC:
- Transmitter: sending a message
- Receive: receiving a message
- Transceiver: sending and receiving a message
[!primary]
Find more information on the means of communication in the chapter List of PDUs.
Once a connection has been established between the ESME and an OVHcloud SMSC, a message can be sent and/or received.
Authentication of the connection to the SMSC is done with the system_id (identifier), the password and the IP address of your application.
The OVHcloud SMPP solution allows you to:
- Send SMS messages with (or without) acknowledgement of receipt (DLR)
- Receive a message sent from a mobile phone
| Source | Destination | |
|---|---|---|
| Sending an SMS (MT) | - Shortcode (Metropolitan France and Belgium) - Alphanumeric - Virtual number* |
International number in E.164 format |
| Send an SMS message authorising a reply | - Shortcode (Metropolitan France) | International number in E.164 format |
| Send an SMS message authorising a response with a MT/MO ratio of 1:1 | - Virtual number* | Virtual number* |
| Receiving an SMS sent from a mobile (MO) | - Mobile phone number | Virtual number* |
Virtual number*: transactional channel only
An ESME can connect in one of three modes: Transmitter, Receiver, Transceiver.
These connection requests are supported in accordance with the SMPP v3.4 protocol specification.
During the login process, the ESME makes a Bind Request providing the system_id (identifier) and its password.
This information, along with your application's IP, is used to authenticate the connection request.
A response is then sent by the SMSC with a status that defines whether authentication is successful or not.
This type of bind is used to initiate a two-way communication connection between the SMSC and the ESME (the fusion of the transmitter and receiver modes).
This type of bind is used to initiate a connection that only allows ESME to communicate to the SMSC (sending SMS to a mobile). The SMSC sends responses associated with query PDUs on the same connection.
This type of bind is used to initiate a connection that only allows communication from the SMSC to the ESME (sending acknowledgement (DLR) or messages sent from a mobile phone). ESME sends responses associated with query PDUs on the same connection.
A request to close a connection that is initiated by the SMSC or ESME. The party receiving the request returns a response when it is ready to cut the connection.
OVHcloud SMSC unbinds the connections every 24h, the ESME must reconnect automatically.
Not supported
The submit_sm is used by an ESME to submit an SMS to the SMSC for transmission to a mobile number.
Mandatory parameters:
| Parameter name | Ref. Spec 3.4 | Supported |
|---|---|---|
| service_type | 5.2.11 | No |
| source_addr_ton | 5.2.5 | Yes |
| source_addr_npi | 5.2.6 | Yes |
| source_addr | 5.2.8 | Yes |
| dest_addr_ton | 5.2.5 | Yes |
| dest_addr_npi | 5.2.6 | Yes |
| destination_addr | 5.2.9 | Yes |
| esm_class | 5.2.12 | Yes |
| protocol_id | 5.2.13 | No |
| priority_flag | 5.2.14 | No |
| schedule_delivery_time | 5.2.15 | Yes |
| validity_period | 5.2.16 | Yes |
| registered_delivery | 5.2.17 | Yes |
| replace_if_present_flag | 5.2.18 | No |
| data_coding | 5.2.19 | Yes |
| sm_default_msg_id | 5.2.20 | No |
| sm_length | 5.2.21 | Yes |
| short_message | 5.2.22 | Yes |
source_addrcan be an international number, an alphanumeric number or a shortcode number:- alphanumeric: those phone numbers are composed of letters and numbers (e.g. ovh123).
source_addr_ton= 5source_addr_npi= 0
- shortcode: those phone numbers contain between 3 and 8 numbers (e.g. 38069). The shortcode is only set to notify our service that we will have to use one, the real shortcode used to send the sms will be set by the telecom operator.
source_addr_ton= 3source_addr_npi= 1
- international: those phone numbers are composed of the country identifier and usual number without the first 0 (e.g. 33601020304).
source_addr_ton= 1source_addr_npi= 1
- alphanumeric: those phone numbers are composed of letters and numbers (e.g. ovh123).
destination_addrmust be an international number (e.g. 33600000001).dest_addr_ton= 1dest_addr_npi= 1
Optional settings:
| Parameter name | Ref. Spec 3.4 | Supported |
|---|---|---|
| user_message_reference | 5.3.2.17 | No |
| source_port | 5.3.2.20 | No |
| source_addr_subunit | 5.3.2.2 | No |
| destination_port | 5.3.2.21 | No |
| dest_addr_subunit | 5.3.2.1 | Yes |
| sar_msg_ref_num | 5.3.2.22 | No |
| sar_total_segments | 5.3.2.23 | No |
| sar_segment_seqnum | 5.3.2.24 | No |
| more_messages_to_send | 5.3.2.34 | No |
| payload_type | 5.3.2.10 | No |
| message_payload | 5.3.2.32 | No |
| privacy_indicator | 5.3.2.14 | No |
| callback_num | 5.3.2.36 | No |
| callback_num_pres_ind | 5.3.2.37 | No |
| callback_num_atag | 5.3.2.38 | No |
| source_subaddress | 5.3.2.15 | No |
| dest_subaddress | 5.3.2.16 | No |
| user_response_code | 5.3.2.18 | No |
| display_time | 5.3.2.26 | No |
| sms_signal | 5.3.2.40 | No |
| ms_validity | 5.3.2.27 | No |
| ms_msg_wait_facilities | 5.3.2.13 | No |
| number_of_messages | 5.3.2.39 | No |
| alert_on_msg_delivery | 5.3.2.41 | No |
| language_indicator | 5.3.2.19 | No |
| its_reply_type | 5.3.2.42 | No |
| its_session_info | 5.3.2.43 | No |
| ussd_service_op | 5.3.2.44 | No |
The submit_sm_resp is confirmation that the SMSC has received the submit_sm.
It contains a message_id which is the SMSC message identifier to link to the acknowledgement (DLR) sent later when the mobile phone received the SMS (provided that the DLR request is specified in the submit_sm).
The deliver_sm is issued by the SMSC to send a DLR to the ESME if requested by the ESME in the submit_sm or for an incoming message (response to a shortcode or an SMS sent to your virtual number).
Mandatory parameters:
| Parameter name | Ref. Spec 3.4 | Supported |
|---|---|---|
| service_type | 5.2.11 | No |
| source_addr_ton | 5.2.5 | Yes |
| source_addr_npi | 5.2.6 | Yes |
| source_addr | 5.2.8 | Yes |
| dest_addr_ton | 5.2.5 | Yes |
| dest_addr_npi | 5.2.6 | Yes |
| destination_addr | 5.2.9 | Yes |
| esm_class | 5.2.12 | Yes |
| protocol_id | 5.2.13 | No |
| priority_flag | 5.2.14 | No |
| schedule_delivery_time | 5.2.15 | No |
| validity_period | 5.2.16 | No |
| registered_delivery | 5.2.17 | No |
| replace_if_present_flag | 5.2.18 | No |
| data_coding | 5.2.19 | Yes |
| sm_default_msg_id | 5.2.20 | No |
| sm_length | 5.2.21 | Yes |
| short_message | 5.2.22 | Yes |
Optional settings:
| Parameter name | Ref. Spec 3.4 | Supported |
|---|---|---|
| receipted_message_id | 5.3.2.12 | Yes |
| user_message_reference | 5.3.2.17 | No |
| source_port | 5.3.2.20 | No |
| destination_port | 5.3.2.21 | No |
| sar_msg_ref_num | 5.3.2.22 | No |
| sar_total_segments | 5.3.2.23 | No |
| sar_segment_seqnum | 5.3.2.24 | No |
| user_response_code | 5.3.2.18 | No |
| privacy_indicator | 5.3.2.14 | No |
| payload_type | 5.3.2.10 | No |
| message_payload | 5.3.2.32 | No |
| callback_num | 5.3.2.36 | No |
| source_subaddress | 5.3.2.15 | No |
| dest_subaddress | 5.3.2.16 | No |
| language_indicator | 5.3.2.19 | No |
| its_session_info | 5.3.2.43 | No |
| network_error_code | 5.3.2.31 | No |
| message_state | 5.3.2.35 | No |
OVHcloud-specific settings:
| Parameter name | Tag TLV (hex) | Field type | Size | Description |
|---|---|---|---|---|
| outgoing_id | 0x1401 | Null-terminated character string (\0) | 64 bytes | OVHcloud internal ID used in the case of a DLR |
| incoming_id | 0x1402 | Null-terminated character string (\0) | 64 bytes | OVHcloud internal ID used in the case of a MO |
Our service will attempt to send the deliver_sm to ESME for up to 7 days.
| Error code (PTT) | Description |
|---|---|
| 0 | No Error |
| 1 | Internal Error |
| 2 | Network Error |
| 3 | Unreachable Destination |
| 4 | Equipment Error |
| 5 | Subscriber / Credit Related (e.g. Account or sender is invalid, Recipient number unreachable) |
| 6 | Timeout |
| 7 | Operator Related |
| 8 | Parental Lock |
| 9 | Undeliverable |
| 10 | Account Credit (e.g. Not enough credit, Auto-recredit issue) |
| 50 | Internal Error |
| 51 | Internal Error |
| 52 | Missing Template (e.g. US destination requires approved templates) |
| 53 | Blacklisted (a STOP response sent by the recipient to block the sender) |
| 54 | Forbidden destination |
| 55 | Sender Temporarily Ratelimited (maximum sms sent exceeded during a short period) |
| 100 | Invalid Destination Numbering Plan |
| 101 | Invalid Content |
| 102 | Invalid GSM7 Coding (e.g. error with packed/unpacked GSM7) |
| 103 | Message too long for the number of allowed segments |
| 254 | Pending |
| 255 | Unknown Error |
| 800 | Undeliverable |
| 801 | Expired |
| 802 | Deleted |
| 803 | Rejected |
| 804 | Unknown |
PDU used by SMSC and ESME to check if a connection is still active.
It is recommended that you follow a 30-second interval between each request.
PDU returned by SMSC when a PDU is not supported or corrupted.
Not supported.
Not supported.
Not supported.
Not supported.
Not supported.
Not supported.
Any response PDU (those ending with _resp) has a status. The SMPP specification provides a list of generic status (SMPP 3.4, 5.1.3 command_status) common to all SMSCs.
A specific range of statuses is reserved for SMSCs. These are the ones used by OVHcloud:
| Error code | Value | Description |
|---|---|---|
| ESME_RBINDTHROTTLED | 0x00000400 | Too many bind authentication |
| ESME_RUNSDATACODING | 0x00000401 | Data Coding unsupported |
| ESME_RINVGSM7CODING | 0x00000402 | Short message GSM7 (GSM 03.38) encoding issues, contact support |
The data coding is used by the submit_sm and the deliver_sm to encode the message.
List of supported data coding:
- GSM 03.38 (GSM 7 bits)*
- UCS2
GSM 03.38*: this encoding represents each character on a septet, but some SMPP clients represent it on a byte. Since the byte format is the most used, your SMPP account is configured on this format by default. If you experience encoding issues with your SMPP client, please contact OVHcloud support to have the format changed.
A TLV (Tag, Length, Value) can be used to enrich a PDU by adding optional information. Some are common and used by multiple SMSCs, and others may be more OVHcloud specific.
SMPP connection identifier, it's generated with random characters.
The password is generated and provided each time an SMPP account is created.
A list of IPs is required to authorise the machine(s) to connect to the SMSC.
- Secure connection: encrypted connection with TLS 1.3 minimum.
- Insecure connection: a connection that does not have TLS encryption for backward compatibility (all exchanges are in plain text and are therefore visible to third parties).
By default, an SMPP account can have only one pair of Transmitter/Receiver or one Transceiver per zone.
By default, an SMPP account is allowed to process up to 10 messages simultaneously.
By default, an SMPP account is allowed to process up to 20 messages per second per connection.
The protocol version is 3.4.
- Kannel 1.4.5