SMPP
Overview
The SMS Central SMPP Server can be used to implement high traffic two-way SMS messaging via a common protocol for SMS messaging. To connect to the SMS Central SMPP Server you will require an SMPP client running on your system.
This guide has been written to help with the implementation of such an SMPP client with regard to the settings specific to SMS Central.
If you are already familiar with SMPP, then jump to Quick Reference to get started. If you are new to SMPP, then read the remainder of this document for more detailed guidance or download the pdf version.
SMPP Version
The SMPP version to be used between the SMPP Server and client is specified by the client when first binding to the server.
SMS Central SMPP Server supports SMPP version 3.4.
The key differences between SMPP versions 3.3 and 3.4 are:
- SMPP version 3.4 supports an additional "transceiver" bind mode. With this mode, SMPP requests can be transmitted and received over the same SMPP session.
- SMPP version 3.3 supports only numeric message_id values for uniquely identifying SMS messages. SMPP version 3.4 also supports longer alpha-numeric message_id values.
- SMPP version 3.4 supports optional SMPP parameters (also known as TLVs). The SMS Central SMPP Servers use optional SMPP parameters in delivery receipts for message state identification.
Binding to the server
For an SMPP client to bind (or connect) to the SMPP Server, the destination address and port will be required. These are specified in the Quick Reference.
The bind request is issued by the SMPP client to the Server. To be authenticated, the SMPP parameters system_id and password must be specified. These values are provided by SMS Central, which refer to the username and password, respectively, of each user created in SMS Central web portal.
Please note when creating a user for SMPP:
- system_id (username) is limited to 15 characters
- password is limited to 8 characters
The bind mode is specified through the choice of the request command_id as shown in the following table.
Bind command_id | Session Functionality |
bind_transmitter | For SMPP sessions over which SMS messages will be sent. |
bind_receiver | For SMPP sessions over which SMS messages will be received. Delivery receipts, which indicate the delivery status of messages that have been sent, are also received on this type of connection. |
bind_transceiver | For SMPP sessions which combine both the transmitter and receiver functions. This bind mode can only be specified with SMPP version 3.4 |
The following SMPP bind parameters are ignored by the SMS Central SMPP Server:
- system_type
- addr_ton
- addr_npi
- address_range
Send an SMS
An SMPP client can send a message to a mobile phone using the SMPP submit_sm request. Messages may only be sent over transmitter or transceiver type SMPP sessions.
The SMS Central SMPP Server supports sending of both text and binary SMS (including WAP push and concatenated SMS).
Address Parameters
The SMPP specification defines several parameters, which relate to the source and destination addresses of a message.
The following table specifies the values that should be used when issuing submit_sm requests to the SMPP Server.
Field Name | Value |
Source_addr_ton | It is recommended that the address be always expressed in international format, i.e. prefixed with country code. In this case, the TON value is also ignored.However, if a longcode address is expressed in national format, the TON value should be set to 2. |
Source_addr_npi | This value is not used by the SMPP Server |
Dest_addr_ton | It is recommended that destination addresses be always expressed in international format, i.e. prefixed with a country code. Where this is the case, the SMPP Server will ignore the TON parameter.However, if the address is expressed in national format, the TON value should be set to 2. |
Dest_addr_npi | This value is not used by the SMPP Server |
Data Encoding
The encoding used with message data is specified with the SMPP parameter data_coding, also called DCS (data coding scheme). The SMPP Server will use this value to decode the data so that it can then be encoded with the encoding scheme required by the carrier.
The SMPP Server supports the following DCS values.
DCS value | Encoding |
0 | Default value. With the SMPP Server this is GSM 03.38. |
1 | ASCII (IA5) |
3 | Latin 1 (ISO-8859-1) |
4 | Octet (8 bit binary). To be used for binary content. |
8 | UCS2 (ISO/IEC-10646) |
Binary messages
The SMPP Server does support the sending of binary messages, such as WAP Push and concatenated SMS. This capability is subject to destination carriers also supporting these message types.
Binary messages should be encoded with data_coding DCS value of 4 (Octet encoding).
Concatenated SMS must be implemented by the encoding of a user data header stored along with the message data. For such messages, esm_class must have the User Data Header indicator set, i.e. the bit represented by the hex value 0x40.
Receive an SMS
The SMPP Server will forward the inbound/reply (MO) messages sent to numbers allocated to your account via the active SMPP bind. To forward these messages the SMPP Server will issue the SMPP request deliver_sm.
Messages will only be forwarded over SMPP sessions with bind modes receiver or transceiver.
Note that the deliver_sm request is also used for forwarding delivery receipts. For more details, refer to section ‘Receiving Delivery Receipts’.
In order to ensure inbound/reply (MO) messages are forwarded to your active SMPP bind with the SMS Central SMPP server, please enable Forward to a URL functionality via the Rules & Triggers settings available in the SMS Central web portal.
Address Parameters
The following table specifies the SMPP parameter values relating to the message
source and destination addresses that will be set by the SMPP Server in
deliver_sm requests.
Field Name | Value |
source_addr_ton | For messages sent from a mobile phone, the source address (MSISDN) will always be expressed in international format, i.e. prefixed with country code. The TON value will therefore always be set to 1. |
source_addr_npi | Will always be set to 1 by the SMPP Server. |
dest_addr_ton | The TON value for the destination address will be set according to type of number stored in the address.
|
dest_addr_npi | The NPI for the destination address will be set as follows:
|
Data Encoding
Messages will be forwarded to the SMPP client using the default encoding of the SMPP Server, i.e. Latin 1.
Receive DLRs
The SMPP Server will forward to your SMPP client, via the active SMPP bind, all delivery receipts received from carriers for all messages sent by the SMPP client. Delivery receipts will be forwarded using the SMPP deliver_sm request. This is the same SMPP request used for forwarding messages sent from the mobile phone. Delivery receipts can be distinguished from messages by checking the value of the esm_class parameter. If the 3rd bit is on, the request is for a delivery receipt.
The option to determine whether delivery receipts are forwarded is not available via SMPP, this option is available as a setting which can be created via the Rules & Triggers settings in the SMS Central web portal. Individual bits must be set in this field as specified in section 5.2.17 of the SMPP Specification.
Note that SMPP may not be the protocol used by the carrier from which the delivery receipt is received. The SMPP Server will translate the delivery receipts from the protocol used by the carrier into the format used with SMPP.
The SMPP delivery receipt format is detailed in the SMPP Protocol Specification Appendix B. The delivery receipt information is passed in the short_message parameter of the deliver_sm request.
Status Values
For delivery receipts forwarded by the SMPP Server, the stat sub-field value of short_message field may have one of the values defined in the following table.
stat value | esm_class value | Description |
ACCEPTD | 0x20 | The message has been accepted by the upstream carrier. |
BUFFRED | 0x20 | The message is currently with the carrier and in pending status |
NOCRED | 0x4 | Your SMS Central account has exceeded its credit limit (no credit). |
DELETED | 0x4 | The message has been deleted at the carrier level and will not be delivered. |
DELIVRD | 0x4 | Message was delivered. |
ENROUTE | 0x20 | Message is en route, ie is still being routed to the mobile phone. |
EXPIRED | 0x4 | Carrier has given up trying to deliver the message. |
REJECTD | 0x4 | Carrier rejected the message. |
SYSERR | 0x4 | An error has occurred at the carrier level and the message could not be delivered (system error). |
UNDELIV | 0x4 | The message could not be delivered. The err sub-field should be consulted for further explanation - refer to Error Codes section for a detail on the sub-field. |
FAILED | 0x4 | The message could not be delivered and has failed at the carrier level. The err sub-field should be consulted for further explanation - refer to Error Codes section for a detail on the sub-field. |
UNKNOWN | 0x4 | The message has been sent to the carrier and is in an unknown state (no further information provided by the carrier). It is likely to not delivered. |
The esm_class value of 0x20 indicates that the delivery receipt is intermediate - a further receipt should follow.
The esm_class value of 0x4 indicates the delivery receipt is final.
Error Codes
The following table lists the possible err sub-field values which may be returned by the SMPP server in delivery receipts.
err value | Description |
0 | Success; Message has been sent, delivery confirmation is pending |
1 | Success; Message has been successfully delivered |
500 | Failed; Internal SMS Central Server Error |
503 | Failed; Message has expired within the carrier |
511 | Rejected; Your username or password is incorrect |
513 | Rejected; Message rejected due to being a duplicate message |
514 | Rejected; No ‘RECIPIENT’ value was provided |
519 | Rejected; The number you tried sending to is blacklisted |
531 | Rejected; Your message contains no content |
532 | Rejected; Your message content has invalid characters. Please check your message text |
534 | Rejected; Credit limit exceeded. You have run out of SMS credit |
535 | Rejected: Your ‘ORIGINATOR’ value is not valid |
536 | Notice: Your message has been temporarily delayed |
550 | Failed: Message could not be delivered by carrier |
Quick Reference
Item | Description |
SMPP Server Address | smpp.smscentral.com.au |
SMPP server port | 8100 |
SMPP versions supported | 3.4 |
Session bind modes supported | transmitter, receiver, transceiver |
Max concurrent SMPP sessions | 2 (unless a higher limit is negotiated) |
Max concurrent outstanding SMPP requests | 10 (unless a higher limit is negotiated) |
SMPP commands supported | bind + bind_resp unbind + unbind_resp submit_sm + submit_sm_resp deliver_sm + deliver_sm_resp enquire_link + enquire_link_sm |
character set support | In submit_sm, data_coding may be set to: 0 (SMSC default) = Latin 1 (ISO-8859-1) 1 = ASCII 3 = Latin 1 (ISO-8859-1) 4 = Octet (8 bit binary) In deliver_sm, data_coding will be set to: 3 (SMSC default) = Latin 1 |
message_id formats | 32-character hash value (containing Hex digits only) |
Optional SMPP parameters | N/A |
Glossary
Term | Meaning |
DA | Destination Address (of a message) |
DCS | Data Coding Scheme. Defines the encoding scheme used with message data. |
DR/DLR | Delivery Receipt (an SMPP request that contains the delivery status of a message that has been sent) |
ESME | External Short Message Entity (i.e. the third party that uses an SMPP client to send and receive messages) |
longcode | A number provisioned with a carrier that has the same format as an MSISDN. Longcodes are much cheaper to provision than shortcodes, but do not support premium charges. |
MO | Mobile Originated (message) |
MSISDN | Mobile Station International ISDN Number (i.e. a mobile phone number) |
MNP | Mobility Number Portability (database) |
MT | Mobile Terminated (message) |
OA | Originating Address (of a message) |
shortcode | A national number normally provisioned with each carrier in a country. Shortcodes support premium charges applied to both MOs and MTs. |
SMPP | Short Message Peer to Peer (protocol) |
SMS | Short Message Service (message) |
SMSC | Short Message Service Centre (i.e. the SMPP server) |
TON | Type Of Number. For specifying the type of address of an OA or DA, e.g. national or international. |
TLV | Tag Length Value (ie an optional SMPP parameter) |
Copyright © 2024 SMS Central by Sinch MessageMedia