txtNation SMSC SMPP API

From txtNation Wiki
Jump to: navigation, search

txtNation's SMSC SMPP API allows you to perform SMS Messaging; Bulk SMS.

SMPP Bulk refers to the method of sending your MT messages using our SMPP SMSC.

If you require SMSC Bulk using HTTP please go to this HTTP API.

Contents

Connecting

A bind_transmitter, or bind_transceiver primitive should be sent immediately after establishing a connection.

The system_id and password field need to be set; all other parameters are ignored. Upon successful bind, a bind_transmitter_resp, or bind_transceiver_resp' primitive will be returned with a command_status of zero (ESME_ROK). If the bind fails due to mismatching system_id/password, or other reasons, a generic_nack primitive 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 (see Messaging; Bulk SMS - Sending Message. below).

Quick Start

Host / IP: smsc.txtnation.com

Server Port: 2775

SMPP Version: v3.4

User name /System ID: [provided to you in your Welcome Service pack]

Password: [provided to you in your Welcome Service pack]

Default source address: {May be an 11 digit MSISDN or a shortcode or Alphanumeric of maximum 11 characters}

Bind TON: 1

Bind NPI: 0

Charactersetsend = GSMDefaultAlphabet

Charactersetreceive = GSMDefaultAlphabet

Message Type = Automatic

ReceiptHandling = Automatic

Bound State

After binding you may choose to periodically send enquire_link primitives to ensure the link stays active. If you don't send enquire_link primitives, the txtNation HUB will send them instead, and you will be required to reply to them with enquire_link_resp in order to maintain the bind.

Messaging; Bulk SMS - Sending Messages

To submit messages for delivery to handsets, you must use the submit_sm primitive. Please use the values which are notified to you in your Welcome to Service pack for the parameters, These are commonly:

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.

All other body parameters must be valid according to SMPP SPEC, but may be ignored.

Disposition Notifications

When a message is accepted for delivery, a submit_sm_resp primitive is sent with a message identifier in its message_id field. If the submit_sm primitive fails any of the validation checks, then a generic_nack primitive will be returned.

Changes to the disposition of a message that has been accepted for onwards delivery, will be sent through deliver_sm primitives with the following properties:

Body Parameter Values
destination_addr MSISDN
short_message id: nnnnnnnnnnnnnnnnn sub: 001 dlvrd: 000 submit date: nnnnnnnnnnnn done date: nnnnnnnnnnnn stat: UNDELIV err: 60 text:


Supplementary information may be available for debug purposes in specific cases e.g. for UNDELIV you may also receive err: 60(charging issue), 88(onward smsc throttle), 288(txtNation internal throttle), 0 for other errors

TLV Parameter Values
receipted_message_id Same value as message_id in submit_sm_resp


Throttling

Every request sent to us counts towards a fixed limit of request/second. If you exceed the agreed rate (consult your account manager / SLA) if you receive one of the following error code alongside an UNDELIVERABLE delivery notification it would be advisable to resend them at a later time and within the agreed throttle limits. "UNDELIVERABLE 88" - Upstream SMPP throttle, "UNDELIVERABLE 288" - Internal throttle.

Note you may also receive "UNDELIVERABLE 60" - charging fail, which means contact your account manager for further credit allocation and "UNDELIVERABLE 0" which means it is an unspecified error, please contact txtNation support to investigate.

Disconnecting

It is desired that you send a UNBIND primitive and wait for the peer to reply with an UNBIND_RESP and connection reset. In case you don't do this, it is possible that new connection requests fail for a short period of time.

Disposition States

The seven most common return values are in bold

STATE SMSC Reported state Final state
DELIVERED DELIVERED Yes
DELIVERED DELIVRD Yes
ACKNOWLEDGED ACK No
ACKNOWLEDGED ACKED No
ACKNOWLEDGED ACKNOWLEDGED No
ACKNOWLEDGED ACCEPTD No
REJECTED REJECT or REJCTED Yes
REJECTED REJECTED Yes
REJECTED REJECTD Yes
NON DELIVERED UNDELIV or UNDELIVE Yes
NON DELIVERED UNDELIVER Yes
NON DELIVERED UNDELIVERED Yes
EXPIRED EXPIRD Yes
EXPIRED EXPIRED Yes
DELETED DELETED Yes
DELETED DELETE Yes
DELETED OPSDELETED Yes
ABANDONED ABANDONED Yes
RETRYING RETRY No
RETRYING RETRYNG No
RETRYING RETRYING No
CREDIT ERROR CREDIT ERROR No
NETWORK ERROR STORE BUSY Yes
NETWORK ERROR INTERFACE BUSY Yes
NETWORK ERROR OTHER ERROR Yes
NETWORK ERROR FACILITY NOT SUPPORTED Yes
NETWORK ERROR DATABASE FULL Yes
NETWORK ERROR SME BUSY Yes
NETWORK ERROR NETWORK FAILURE Yes
INVALID NUMBER DESTINATION NOT KNOWN Yes
INVALID NUMBER UNIDENTIFIED SUBSCRIBER Yes
SMS BLOCKED CALL BARRED Yes
SMS BLOCKED USER CALL BARRED Yes
SIM FULL MEMORY CAPACITY EXCEEDED Yes
HANDSET UNAVAILABLE ABSENT IMSI DETACHED Yes
HANDSET UNAVAILABLE SMS NOT PROVISIONED Yes
HANDSET UNAVAILABLE ERROR IN MS Yes
HANDSET UNAVAILABLE ABSENT IMSI DETACHED GPRS Yes
HANDSET UNAVAILABLE ABSENT DEREGISTERED IN HLR Yes
HANDSET UNAVAILABLE ABSENT MS PURGED Yes
ROAMING ERROR ABSENT PAGE FAIL Yes
ROAMING ERROR ABSENT ROAMING RESTRICTION Yes
CREDIT ERROR CALL BARRED (NO CREDIT) Yes
CREDIT ERROR CALL BARRED (NO ACCESS TIME) Yes
SENDING ERROR SYSTEM FAILURE Yes
SENDING ERROR CUG REJECT Yes
SENDING ERROR UNEXPECTED DATA VALUE Yes
SENDING ERROR TRANSMISSION ERROR Yes
SENDING ERROR DEFERRED DELIVERY Yes
CREDIT ERROR NOCRED Yes
SENDING ERROR FAILED Yes
BUFFERED BUFFRED No
SENDING ERROR UNDELIVERABLE Yes
FAILED MNP PORTED OUT MSISDN Yes
FAILED UNKNOWN Yes

Message Retry Policies

When sending messages to our SMPP gateway, you may experience unsuccessful submissions with statuses according to the above.

In certain cases you may be able to retry the message but this will often depend on the agreements with the operators in a given country.

Contact txtNation for more details.

Personal tools