SMPP Protocol
Introduction
SMPP is an industry standard, reliable method of sending a high number of messages. Our documentation leads you through the process of integrating with our SMPP service.
Interface
Developing and implementing your SMPP based application can be difficult to do without an industry standard test platform. We offer a fully compliant SMPP test profile as part of our wholesale service. The test profile allows your developers to simulate a real production environment (including delivery receipting) without incurring the costs of sending messages.
Introduction to the aql SMPP Service
aql supports SMPP v3.4. The following contains a list of the PDUs supported by aql:
Client to aql
- BIND_TRANSMITTER
- BIND_RECEIVER
- BIND_TRANSCEIVER
- ENQUIRE_LNK
- SUBMIT_SM
- QUERY_SM
- UNBIND
- DELIVER_SM_RESP
aql to Client
- BIND_TRANSMITTER_RESP
- BIND_RECEIVER_RESP
- BIND_TRANSCEIVER_RESP
- DELIVER_SM
- ENQUIRE_LINK
- ENQUIRE_LINK_RESP
- SUBMIT_SM_RESP
- QUERY_SM_RESP
- UNBIND_RESP
- GENERIC_NACK
Binding to aql
There are two options available when binding to aql. You can either bind using the transmitter and receiver pair from SMPP v3.3 or bind using the transceiver mode new to SMPP v3.4.
When the SMPP account is set up for you, you will be given a username (system_id), password and a system_type value to connect with.
Maximum Number of Binds
You are initially restricted to the number of binds you can make to aql. Depending on the version of SMPP you are using it will be either 1 transceiver connection or 1 transmitter and 1 receiver connection. In most cases this is sufficient. If however, you require this configuration changing on your account, please raise a support ticket via our support system (see bottom of page). We will then be able to discuss your needs and make the appropriate changes.
IMPORTANT: You can only connect to aql via certain IP addresses that you have registered. If you wish to connect from multiple IP addresses, please raise a support ticket via our support system.
Submitting Messages to aql
The following table gives a breakdown of the SUBMIT_SM PDU. It contains details regarding each of the parameters of the PDU and how they should be used when passing messages to the aql servers.
| Parameter | Description |
|---|---|
| Parameter: command_length | Description: As in SMPP specification |
| Parameter: command_id | Description: As in SMPP specification |
| Parameter: command_status | Description: As in SMPP specification |
| Parameter: sequence_number | Description: As in SMPP specification |
| Parameter: service_type | Description: Use the system_type parameter that is given to you by aql |
| Parameter: source_addr_ton | Description: See explanation of source_addr_ton and source_addr_npi at end of this section |
| Parameter: source_addr_npi | Description: See explanation of source_addr_ton and source_addr_npi at end of this section |
| Parameter: source_addr | Description: The originator to be used for this message. If left blank, the default originator on your account will be used. Either 16 digits (in international format) for a mobile number or 11 alphanumeric characters for text |
| Parameter: dest_addr_ton | Description: The destination number in international format (e.g. 447911111111) |
| Parameter: esm_class | Description: As in SMPP specification |
| Parameter: protocol_id | Description: Not supported, use any value in accordance with SMPP specification |
| Parameter: priority_flag | Description: Not supported, use any value in accordance with SMPP specification |
| Parameter: schedule_delivery_time | Description: If left blank, the message will be sent immediately. To send message at a different time, set the time as defined in the SMPP specification |
| Parameter: validity_period | Description: Not supported, use any value in accordance with SMPP specification |
| Parameter: registered_delivery | Description: If a delivery report is required set to 1 otherwise set to 0 (zero) |
| Parameter: replace_if_present_flag | Description: Not supported, use any value in accordance with SMPP specification |
| Parameter: data_coding | Description: As in SMPP specification |
| Parameter: sm_default_msg_id | Description: Not supported, use any value in accordance with SMPP specification |
| Parameter: sm_length | Description: Length in octets of the short_message parameter |
| Parameter: short_message | Description: The short message itself as defined by the SMPP specification |
N.B. Optional parameters are not required by aql and are not supported.
source_addr_ton and source_addr_npi Parameters
When mimicking a mobile number, the international format must be used. In this case both source_addr_ton and source_addr_npi must be set to 1. In other cases, it is generally acceptable to leave these parameters set to 0 (zero).
Querying a Previously Submitted Message
aql supports the QUERY_SM PDU. This can be used to determine the state of a message at a time that is suitable to you. The table below gives a breakdown of the QUERY_SM PDU and how it should be used with aql.
| Parameter | Description |
|---|---|
| Parameter: command_length | Description: As in SMPP specification |
| Parameter: command_id | Description: As in SMPP specification |
| Parameter: command_status | Description: As in SMPP specification |
| Parameter: sequence_number | Description: As in SMPP specification |
| Parameter: message_id | Description: The message id that was originally sent back in the SUBMIT_SM_RESP PDU |
| Parameter: source_addr_ton | Description: Must be 0 (zero). This is auto-detect mode |
| Parameter: source_addr_npi | Description: Must be 0 (zero). This is auto-detect mode |
| Parameter: source_addr | Description: Not used. Set to NULL |
The QUERY_SM_RESP PDU is as defined in the SMPP specification.
Error Response Codes
The error responses that can be sent back are as defined in the SMPP specification. The additional error codes specific to aql are outlined in the table below.
| Parameter | Description |
|---|---|
| Parameter: 0x00000400 | Description: You do not have enough credits to send message. Please contact us to credit your account |
| Parameter: 0x00000401 | Description: Number of concurrent connections exceeds the limit for your account |
Delivery Responses
If the register_delivery parameter is set to 1 in the original SUBMIT_SM PDU then a DELIVER_SM response will be sent back to you when the message has reached a final state. This could take anywhere between seconds and hours. Some cases could take even longer.
The following table shows a breakdown of the parameters that are sent in a DELIVER_SM and how to interpret them when received from aql.
| Parameter | Description |
|---|---|
| Parameter: command_length | Description: As in SMPP specification |
| Parameter: command_id | Description: As in SMPP specification |
| Parameter: command_status | Description: As in SMPP specification |
| Parameter: command_number | Description: As in SMPP specification |
| Parameter: service_type | Description: The system_type value that the connection that the message was submitted with is echoed in this parameter |
| Parameter: source_addr_ton | Description: Will always be 0 (zero) |
| Parameter: source_addr_npi | Description: Will always be 0 (zero) |
| Parameter: source_addr | Description: This is the mobile number that the original message was sent to |
| Parameter: dest_addr_ton | Description: Will always be 0 (zero) |
| Parameter: dest_addr_npi | Description: Will always be 0 (zero) |
| Parameter: destination_addr | Description: This is set to the originator of the original message |
| Parameter: esm_class | Description: Always set to 4 (00000100) |
| Parameter: protocol_id | Description: Not used, will always be 0 (zero) |
| Parameter: priority_flag | Description: Not used, will always be 0 (zero) |
| Parameter: schedule_delivery_time | Description: Always set to NULL |
| Parameter: validity_period | Description: Always set to NULL |
| Parameter: registered_delivery | Description: Always set to 0 |
| Parameter: replace_if_present_flag | Description: Always set to 0 |
| Parameter: data_coding | Description: Always set to 0 |
| Parameter: sm_default_msg_id | Description: Always set to 0 |
| Parameter: sm_length | Description: Length in octets of the short_message parameter |
| Parameter: short_message | Description: The short message itself as defined by the SMPP specification |
The short message for a delivery receipt is a string and will look like the following:
"id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:E Text: ..."
The fields in the delivery receipt are explained in the following table:
| Field | Type | Required | Length | Description |
|---|---|---|---|---|
| Field: ID | Type: Blank | Required: Yes | Length: 10 (max) | Description: id supplied by aql in the original SUBMIT_SM PDU |
| Field: sub | Type: Blank | Required: Yes | Length: 3 (max) | Description: Always 000 |
| Field: dlvrd | Type: Blank | Required: Yes | Length: 3 | Description: Always 000 |
| Field: submit date | Type: Blank | Required: Yes | Length: 10 | Description: Date + time submitted. See SMPP Specification for the format |
| Field: done date | Type: Blank | Required: Yes | Length: 10 | Description: Date + time submitted. See SMPP Specification for the format |
| Field: stat | Type: Blank | Required: Yes | Length: 7 | Description: Final status of the message. See table below |
| Field: err | Type: Blank | Required: Yes | Length: 3 | Description: Associated error code. See table below |
| Field: text | Type: Alphanumeric | Required: Yes | Length: 20 | Description: Will always contain the text 'Not available' (without quotes) |
The stat parameter contains the status of the message. The values it can take along with associated error codes are described below:
| Status Value | Description |
|---|---|
| Status Value: DELIVRD 000 | Description: The message has been delivered |
| Status Value: UNDELIV 101 | Description: The message is undeliverable |
| Status Value: UNKNOWN 102 | Description: The message is in a final invalid state. It is unknown if the message has been delivered |
In the near future we will be adding additional status codes. This will allow us to pass along more detailed information.
As with all SMPP communications, the aql servers expect a DELIVER_SM_RESP PDU in response to a delivery report.
Terminating the Connection
In order to stop the connection to aql you must first issue the UNBIND PDU. aql will send back an UNBIND_RESP PDU at which point it is safe to terminate the connection.
Additional Notes
You will require an SMPP client to send messages via the aql SMPP server. The following section may prove useful in this regard.
There is an excellent open source SMPP client for Linux available at: http://www.kannel.org. This provides functionality above and beyond what is required to send messages via aql. It is fairly complex to configure but it is extremely reliable and worth considering.
If you would like to develop your own SMPP client, then there is a Java API available to download. This can be found at:
https://sourceforge.net/projects/smstools/
An equivalent Perl API is available at:
http://search.cpan.org/author/SAMPO/Net-SMPP-1.03/SMPP.pm
SMPP Specification
If you need further information relating to SMPP, a good starting point is:
http://www.smpp.org
