Using SMPP

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.

After binding you should periodically send 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.