Overview
This document describes how to send messages to, and receive messages from handsets using our SMPP service. This service requires specialist knowledge. If you are unsure about using SMPP, please talk to your account manager as there are other services available, including: HTTPS, REST, RESTv2 and SOAP.
Our SMPP default character set is the GSM 7-bit default alphabet, GSM 03.38.
Reference Information
Wikipedia article detailing the SMPP protocol.
We support SMPP versions 3.3 and 3.4.
SMPP over TLS (version 1.2 or higher) must be used to ensure messages remain private.
If your application does not have TLS support, please refer to: Enabling TLS for plain-text SMPP Applications
Supported SMPP Operations
Protocol Description Units - PDUs
We support the following operations:
| Client To Server | Server to Client |
|---|---|
| bind_transmitter | bind_transmitter_resp |
| bind_receiver | bind_receiver_resp |
| bind_transceiver | bind_transceiver_resp |
| submit_sm | submit_sm_resp |
| enquire_link | enquire_link_resp |
| enquire_link_resp | enquire_link |
| deliver_sm_resp | deliver_sm |
Authentication
Your system_id (or ‘Application Name’) and password will be provided once your account has been activated. You will need to log in to set them.
Authorised IP Addresses
You can whitelist your servers’ IPs or IP ranges using the ‘Add IP Address’ button under “Authorised IP Addresses”
Please note: once one or more IP addresses or IP ranges have been added connections from all other IP addresses will be rejected, any attempt from an IP not in the list will receive an Authentication error.
SMPP Security Information
The SMPP protocol limits maximum password length to eight characters. Because of this limitation, we employ the following mechanisms to prevent your account from being abused:
SMPP over TLS: Required for all connections, and will protect both your SMPP account credentials, as well as the message data.
Clients must utilise TLS to ensure privacy is protected. Please refer to our Privacy Policy for more information. https://modicagroup.com/privacy
Host Name for SMPP Connection
- Public Host Name: api.sms.optus.com.au
- IP Address(es): 54.66.199.3
SMPP Port Information
| Security | Port |
|---|---|
| SMPP over TLS | 2776 |
Character Set
We will map the character set the customer submits messages in to the character set supported by the route to the network. In most cases all characters will be available, in some cases there may be characters not available, which may be ignored or mapped to their closest equivalents.
Please set your data_coding field with one of the following values, reflecting
the encoding of your short_message:
data_coding value |
Encoding |
|---|---|
| 0 | GSM 7-bit default alphabet, GSM 03.38 |
| 1 | ASCII |
| 3 | ISO-8859-1 - Latin1 |
| 8 | Unicode UCS2 |
SMPP Parameters
The ‘submit_sm’ PDU is used to send messages to handsets, important fields of this PDU are:
| Parameter | Description |
|---|---|
| service_type | NULL |
| source_addr | 0, Short Code or MSISDN (*allocated by us) or Alphanumeric Mask |
| source_addr_ton |
|
| source_addr_npi | 1 |
| destination_addr | The handset number in international format, ie: 64210123456 |
| dest_addr_ton | 1: (international) should be used to send to handset MSISDN |
| data_coding |
|
| short_message | The content of the message to be sent |
| sm_length | The length of the short_message field |
| validity_period | The validity period of this message. Set to NULL to request the SMSC default validity period |
Notes:
dest_addr: The mobile phone number the message is to be delivered to. This
string must be a valid mobile phone number in international format. This usually
means removing the leading zero and replacing with the country code.
For example delivery to the an Australian mobile phone number 0413 123 4567 would require dropping the 0 and including the 61 (Australian Country Code) giving the international format: 614131234567
If the source_addr_ton is 0 or 1, the shortcode or MSISDN must be
allocated/provisioned by us. If masking with a shortcode or MSISDN that is not
allocated by us, it is a mask, and the source_addr_ton must be 5
Set source_addr to 0 and source_addr_ton to 0 for us to allocate
respective Short Code automatically. If you set source_addr to 0 then the
source_addr_ton needs to be set to 0, If not it will generate a response
code 10 error.
Optional SMPP Parameters - Tag Length Value (TLV)
| Parameter Name | Tag | Length | Value | Description |
|---|---|---|---|---|
| user_message_reference | 0x0204 | 2 | Integer | ESME assigned message reference number. Delivery receipts will return with this reference. |
| request_source | 0x1400 | Variable | Octet String | Alternative source parameter when an alphanumeric (mask) source_addr is used. |
Message Length, Encoding and Concatenation
Please see the Message Length and Concatenation section.
Delivery Receipt Format
Delivery Reports are requested by use of the registered_delivery parameter.
A message delivery success will have a message_state value of 0x02.
Delivery receipts are contained in the short_message field of deliver_sm
PDUs.
Example: id:<ID> sub:001 dlvrd:001 submit date:<SDATE> done date:<DDATE> stat:<STAT> err:<ERR>
| Parameter | Description |
|---|---|
ID |
The message ID as returned by the corresponding submit_sm_resp PDU |
SDATE |
The date the message was submitted and accepted by the SMPP gateway |
DDATE |
The date the message reached a permanent delivery status |
STAT |
The status of the message transaction in plain text |
ERR |
The status of the message transaction 000 on success, all other values relate to non delivery, see values below |
List of STAT status values:
- ENROUTE
- DELIVRD
- EXPIRED
- DELETED
- UNDELIV
- ACCEPTD
- UNKNOWN
- REJECTD
- STATERR (only if there was an error matching the status)
List of error codes
| Error Code | Description |
|---|---|
| 000 | Unknown/Default |
| 001 | Unknown Subscriber |
| 002 | SMS not provisioned |
| 003 | No credit |
| 004 | Unknown or Deactivated Subscriber |
| 010 | Invalid Source Configuration - Check notes under SMPP Parameters |
Message ID
All messages within the our platform are assigned unique identifier.
This value can be returned on submit_sm_resp and deliver_sm (for both
Delivery Receipt and MO message cases).
In the case of Delivery Receipt the ID will match the ID returned on the
corresponding submit_sm_resp for the message.
By default the ID is returned in the SMPP message_id field of
the submit_sm_resp PDU.
Gateway Capacity
Our gateway is capable of receiving messages at a rapid rate.
However, some mobile carriers limit the allowed throughput rates of their Short Message Service Centres (SMSC) and SMSC gateways. In such cases message delivery may be throttled.
In such instances messages will be queued on our gateway and will be delivered in the order received by the gateway.
If you require very high throughput rates, (ie more than 30msg per second), please inform your account manager to discuss applicable throughput rates on the various connections.
Delivery Retry
On delivery failure of a message the gateway will automatically re-queue the message and retry it 60 seconds later. The gateway will continue retrying up to 50 times at which point the message is flagged as ‘frozen’. This means that if an external party (e.g. A customer or carrier server) is temporarily overloaded, or the network connection drops out, the retry process will ensure ultimate delivery pending the resource becoming available within the 50 minute window.
Failed Message Overflow
Whenever a customer using our standard Web Services interface is unreachable due to network issues or a server outage we re-queue their message (see Delivery Retry). However to minimise the impact of a slow-responding server, all of that customer’s messages are moved off the main queue to a second queue. This ensures continued rapid delivery rates to other customers whose service will not be impacted, whilst the unreachable customer does not lose any messages.
Gateway Monitoring
The gateway is able to detect, alert and in many cases automatically resolve issues. All such events are recorded and externally monitored. Consequently should any component of the entire gateway system cease to function correctly our engineering team are notified.
Problems
If you encounter difficulties with the above, please get in touch: optussd@modicagroup.com.
