SMPP Platform Documentation

Written by Jateen Mistry th Revised: 29 April 2004 th Revised: 8 December 2004

SUPPORT:
For support related issues please logon to the support system at http://www.aql.com/account/aqs_index.php and raise a new ticket.

Contact us
If you have a sales related question please call us on 08707 449227 08707 449228 (fax) If you have any technical questions regarding SMPP please raise a support ticket.

Introduction to the Service

The SMPP platform provided by aql.com is a high-speed method of sending global messages. NOTE: This documentation assumes the reader is familiar with SMPP technology and only contains information on how to use the SMPP in connection with aql.

Introduction to the aql SMPP API

aql supports SMPP v3.4. The following contains a list of the PDUs supported by aql:

Client to aql Bind Commands BIND_TRANSMITTER BIND_RECEIVER BIND_TRANSCEIVER Other Commands ENQUIRE_LINK SUBMIT_SM QUERY_SM UNBIND DELIVER_SM_RESP

aql to Client Bind Commands BIND_TRANSMITTER_RESP BIND_RECEIVER_RESP BIND_TRANSCEIVER_RESP Commands DELIVER_SM ENQUIRE_LINK ENQUIRE_LINK_RESP SUBMIT_SM_RESP QUERY_SM_RESP UNBIND_RESP GENERIC_NACK

Binding to aql
There are 2 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 1). 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 (see bottom of page 1)

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 command_length command_id command_status sequence_number service_type source_addr_ton source_addr_npi source_addr Description As in SMPP As in SMPP As in SMPP As in SMPP

Specification Specification Specification Specification

dest_addr_ton dest_addr_npi destination_addr esm_class protocol_id priority_flag schedule_delivery_time

validity_period registered_delivery replace_if_present_flag data_coding sm_default_msg_id sm_length short_message

Use the system_type parameter that is given to you by aql See explanation of source_addr_ton and source_addr_npi at end of table See explanation of source_addr_ton and source_addr_npi at end of table 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. Must be 0 (zero). This is auto-detect mode Must be 0 (zero). This is auto-detect mode The destination number in international format (e.g 447911111111). See explanation of esm_class and data_coding at end of table Not supported, use any value in accordance with SMPP Specification Not supported, use any value in accordance with SMPP Specification 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. Not supported, use any value in accordance with SMPP Specification If a delivery report is required set to 1 otherwise set to 0 (zero) Not supported, use any value in accordance with SMPP Specification See explanation of esm_class and data_coding at end of table Not supported, use any value in accordance with SMPP Specification Length in octets of the short_message parameter The short message itself as defined by the SMPP specification.

NOTE: Optional parameters are not required by aql and are not supported.

esm_class and data_coding parameters

The following table describes the values that need to be set for the esm_class and data_coding parameters depending on what type of content you require to be sent.

Message type Text Flash UDH

esm_class 00000011 00000011 01000011

data_coding 00010001 (mclass 1) or 00000000 (default mode) 00010000 (mclass 0) 00000100 (8bit binary data)

source_addr_ton and source_addr_npi parameters

When mimicking a mobile number, 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 support 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 command_length command_id command_status sequence_number message_id source_addr_ton source_addr_npi source_addr

Description As in SMPP As in SMPP As in SMPP As in SMPP

Specification Specification Specification Specification

The message id that was originally sent back in the SUBMIT_SM_RESP pdu Must be 0 (zero). This is auto-detect mode Must be 0 (zero). This is auto-detect mode 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. Error code 0x00000400 Description You do not have enough credits to send message. Please contact us to credit 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 command_length command_id command_status sequence_number service_type source_addr_ton source_addr_npi source_addr dest_addr_ton dest_addr_npi destination_addr esm_class protocol_id priority_flag schedule_delivery_time validity_period registered_delivery replace_if_present_flag data_coding sm_default_msg_id sm_length short_message

Description As in SMPP As in SMPP As in SMPP As in SMPP

Specification Specification Specification Specification

The system_type value that the connection that the message was submitted with is echoed in this parameter Will always be 0 (zero). Will always be 0 (zero). This is the mobile number that the original message was sent to Will always be 0 (zero). Will always be 0 (zero). This is set to the originator of the original message. Always set to 4 (00000100) Not used, will always be 0 (zero). Not used, will always be 0 (zero). Always set to NULL Always set to NULL Always set to 0 Always set to 0 Always set to 0 Always set to 0 Length in octets of the short_message parameter 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 id sub dlvrd submit date done date stat err text Size 10 (max) 3 (max) 3 10 10 7 3 20 Type NULL Terminated NULL Terminated NULL Terminated NULL Terminated NULL Terminated NULL Terminated NULL Terminated String without NULL termination Description id supplied by aql in the original SUBMIT_SM pdu Always 000 Always 000 Date + time submitted. See SMPP Specification for the format Date + time delivered. See SMPP Specification for the format Final status of the message. See table below Associated error code. See table below 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: stat value DELIVRD UNDELIV UNKNOWN err value 000 101 102 Description The message has been delivered The message is undeliverable 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 allows 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. There is a small SMPP client written in PHP located at: http://www.phpclasses.org/browse/package/1373.html

If you would like to develop your own SMPP client then there is a Java API available to download. This can be found at: http://www.logicacmg.com/wirelessnetworks http://opensmpp.logica.com/ 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 require the SMPP v3.4 specification, this can be downloaded from the following site: http://www.smpp.org/doc/public/index.html If you need further information relating to SMPP, a good starting point is: http://www.smpp.org