SMPP API
Using SMPP
If you are sending a much larger volume of messages then you could benefit from using SMPP, a high-throughput protocol designed for sending lots of SMS in a short period of time. Our SMSC is compatible with both versions of SMPP, 3.4 and 5.0, but we recommend using 3.4 for best results.
The specification for the protocol is available at http://opensmpp.org/specs/SMPP_v3_4_Issue1_2.pdf.
Connecting
Our SMSC SMPP server is listening for connections at the following endpoint:
http://smsc.txtnation.com:2775
A bind_transmitter or bind_transceiver PDU should be sent immediately after establishing a connection.
The system_id and password fields need to be set. All other parameters are ignored.
Upon a successful bind, a bind_transmitter_resp or bind_transceiver_resp PDU will be returned with a command_status of 0 (ESME_ROK).
If the bind fails due to an incorrect system_id or password (or other reasons), a generic_nack PDU will be returned.
If your chosen SMPP application requires TON and NPI to be set as part of the bind parameters, please set them to match the service you are using.
enquire_link PDU to ensure the bind stays alive. If you don't send
enquire_link PDU, we will send them to you instead and you will be required to reply to them with
enquire_link_resp responses in order to maintain the bind. If you do not reply to these requests then the bind will be closed.
Sending a Message
To submit messages for delivery to handsets, you must use the submit_sm PDU. Typically, this contains the following parameters:
| Body Parameter | Values |
|---|---|
service_type |
Set to Default or null |
source_addr_ton |
For non-premium BULK set to TON=5 or TON=1 or TON=6( TON=5 Source address may be alpha or numeric to a maximum length of 11 characters )( TON=1 International, numeric to a maximum length of 11 characters )( TON=6 Abbreviated, occasionally used when sending shortcode. |
source_addr_npi |
For non-premium BULK set to NPI=0 or NPI=1( NPI=0 Unknown )( NPI=1 ISDN/telephone numbering plan (E163/E164) (normal cli sending)) |
destination_addr_ton |
For non-premium BULK set to TON=1 or TON=5 or TON=6( TON=1 International, numeric to a maximum length of 11 characters )( TON=6 Abbreviated, occasionally used when sending shortcode.( TON=5 Destination address may be alpha or numeric to a maximum length of 11 characters ) |
destination_addr_npi |
For non-premium BULK set to NPI=1 or NPI=0( NPI=1 ISDN/telephone numbering plan (E163/E164) (normal cli sending))( NPI=0 Unknown ) |
source_addr |
For non-premium BULK set to numeric shortcode / MSISDN or alphanumeric, maximum 11 chars |
destination_address |
Set to MSISDN of subscriber, international format, example: 447123456789 |
sm_length |
Set to length of short_message field |
short_message |
Insert text of message, maximum 160 chars. Longer message content may be used by individual agreement & route, and will form part of the SLA. |
Disposition Notifications
When a message is accepted for delivery, a submit_sm_resp PDU is sent with a message identifier in its message_id field. If the submit_sm PDU fails any of the validation checks, then a generic_nack PDU will be returned.
Changes to the disposition of a message that has been accepted for onwards delivery will be sent through deliver_sm PDUs with the following properties:
| Body Parameter | Values |
|---|---|
destination_addr |
The MSISDN of the handset that is being reported |
short_message |
id: nnnnnnnnnnnnnnnnn sub: 001 dlvrd: 000 submit date: nnnnnnnnnnnn done date: nnnnnnnnnnnn stat: UNDELIV err: 60 text: |
You may also receive a TLV parameter for receipted_message_id which contains the ID of the transaction that you received in a submit_sm_resp PDU.
Supplementary information may be available for debugging in specific cases. For example, UNDELIV statuses often provide more information is the err field. You may also receive err: 60 (charging issue), err: 88 (onward SMSC throttle issue), err: 288 (internal throttle issue) or err: 0 for other errors.
Disposition States
The stat value determines the status of the sent message. Typically it can be one of the following:
| Status | Description | Final State? |
|---|---|---|
DELIVERED |
The message was successfully delivered | ✓ |
DELIVRD |
The message was successfully delivered | ✓ |
ACK |
The message has been acknowledged for delivery | ✗ |
ACKED |
The message has been acknowledged for delivery | ✗ |
ACKNOWLEDGED |
The message has been acknowledged for delivery | ✗ |
ACCEPTD |
The message has been accepted for delivery | ✗ |
REJECT or REJCTED |
The message was rejected | ✓ |
REJECTED |
The message was rejected | ✓ |
REJECTD |
The message was rejected | ✓ |
UNDELIV or UNDELIVE |
The message could not be delivered | ✓ |
UNDELIVER |
The message could not be delivered | ✓ |
UNDELIVERED |
The message could not be delivered | ✓ |
EXPIRD |
The message validity has expired | ✓ |
EXPIRED |
The message validity has expired | ✓ |
DELETED |
The message was deleted before delivery | ✓ |
DELETE |
The message was deleted before delivery | ✓ |
OPSDELETED |
The message was deleted by the network before delivery | ✓ |
ABANDONED |
Delivery of the SMS was abandoned | ✓ |
RETRY |
The message could not be delivered but is being retried | ✗ |
RETRYNG |
The message could not be delivered but is being retried | ✗ |
RETRYING |
The message could not be delivered but is being retried | ✗ |
CREDIT ERROR |
The MSISDN did not have sufficient credit to receive the message | ✗ |
STORE BUSY |
The store was busy | ✓ |
INTERFACE BUSY |
The interface was busy | ✓ |
OTHER ERROR |
An unspecified error occurred | ✓ |
FACILITY NOT SUPPORTED |
The type of message was not supported by the receiving network of handset | ✓ |
DATABASE FULL |
The network database is full so the message could not be accepted | ✓ |
SME BUSY |
The SME was too busy to accept the message | ✓ |
NETWORK FAILURE |
There was a failure at the network level | ✓ |
DESTINATION NOT KNOWN |
The destination address was not recognised | ✓ |
UNIDENTIFIED SUBSCRIBER |
The destination address was unknown | ✓ |
CALL BARRED |
The type of message was barred by the receiving MSISDN | ✓ |
USER CALL BARRED |
The type of message was barred by the receiving MSISDN | ✓ |
MEMORY CAPACITY EXCEEDED |
The capacity for messages was exceeded at the network layer | ✓ |
ABSENT IMSI DETACHED |
The receiving MSISDN was absent | ✓ |
SMS NOT PROVISIONED |
The SMS was not provisioned by the network | ✓ |
ERROR IN MS |
There was an unspecified error with the MSISDN | ✓ |
ABSENT IMSI DETACHED GPRS |
The receiving MSISDN was absent | ✓ |
ABSENT DEREGISTERED IN HLR |
The receiving MSISDN was absent in the Home Location Register | ✓ |
ABSENT MS PURGED |
The receiving MSISDN was absent so the message was purged | ✓ |
ABSENT PAGE FAIL |
The receiving MSISDN was absent | ✓ |
ABSENT ROAMING RESTRICTION |
The receiving MSISDN was absent | ✓ |
CALL BARRED (NO CREDIT) |
The MSISDN did not have sufficient credit to receive the message | ✓ |
CALL BARRED (NO ACCESS TIME) |
The MSISDN did not have sufficient credit to receive the message | ✓ |
SYSTEM FAILURE |
There was an unspecified system failure during the send | ✓ |
UNEXPECTED DATA VALUE |
There was an unexpected data value set in the submission | ✓ |
TRANSMISSION ERROR |
There was an error when sending the message to the network | ✓ |
DEFERRED DELIVERY |
The delivery of the SMS has been deferred | ✓ |
NOCRED |
The MSISDN did not have sufficient credit to receive the message | ✓ |
FAILED |
The message delivery failed | ✓ |
BUFFRED |
The message has been buffered for delivery | ✗ |
UNDELIVERABLE |
The message was undeliverable | ✓ |
PORTED OUT MSISDN |
The MSISDN is no longer served by the network | ✓ |
UNKNOWN |
An unknown error occurred during the send | ✓ |
Request Throttling
By default, requests from each account are throttled on a requests-per-second basis. If you exceed this limit at any time you will receive an UNDELIVERABLE error, followed by a numeric code that indicates which throttle has been exceeded.
| Error code | Description |
|---|---|
60 |
Charging failure. Make sure that you have enough credits to send all the messages! |
88 |
The upstream SMPP throttle was exceeded. |
288 |
The internal throttle limit was exceeded. |
0 |
Unspecified throttling error. |
Disconnecting
It is recommended that you should disconnect from the SMSC by sending an unbind PDU. The SMSC will respond with an unbind_resp PDU to confirm that the unbind was successful. If you disconnect without waiting for the unbind_resp then it is possible that new connection requests will fail for a short period of time.