txtNation SMSC HTTP API

From txtNation Wiki
Jump to: navigation, search

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

HTTP Bulk refers to the method of sending your MT messages using the HTTP GET/POST interface our SMPP SMSC.

The HTTP interface to the txtNation SMSC has been tested and benchmarked to 100 tps, for an individual service account, using parallel HTTP requests and measuring the result with jmeter

The default service account configuration, provides 10 concurrent HTTP GET/POST connections. If your service requires a greater throughput, please contact your txtNation account manager.

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

Contents

Connecting

The HTTP API uses the HTTP POST or GET methods.

To facilitate quick configuration and testing, txtNation by default set this option to HTTP GET.

The following example represents a simple GET request to the service.

  http://smsc.txtnation.com:8091/sms/send_sms.php?src=440000000000&dst=447777000000&type=0&dr=1&user=YOUR_ACCOUNT _USERNAME&password=YOUR_ACCOUNT _PASSWORD&msg=txtNation%20best%20to%20test%20at%20the%20end%20of%20the%20road.

Quick Start

Post URL for txtNation Ent HUB (Bulk SMS): http://smsc.txtnation.com:8091/sms/send_sms.php

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 (src): {May be an 11 digit MSISDN or a shortcode or Alphanumeric of maximum 11 characters}

Charactersetsend = GSMDefaultAlphabet

Charactersetreceive = GSMDefaultAlphabet

Scripts

Scripts for easy SMS messaging. Choose from our ready-made scripting languages, which offer simple modification and the ability to send SMS messages with your own sender ID and delivery reports.

Choose from Java, PHP, C#/.Net, C++/CLI, VB.NET, ASP, RUBY, NodeJS, Python, Curl

View code on our Website Scripts Page

Find these on GitHub

Messaging; Bulk SMS - Sending Messages

To submit messages for delivery to handsets, you must use the following variables which are used to populate the SMPP submit_sm primitive.

Please use the values which are notified to you in your Welcome Service pack for the parameters,

Commonly described as follows:

Body Parameter Values
src For non-premium BULK Set to 440000000000 Source address may be alpha or numeric to a maximum length of 11 characters )
dst For non-premium BULK Set to 440000000000 Destination address must be numeric to a maximum length of 11 characters )
type For non-premium BULK set to 0 or 0 = std SMS, u = Unicode, v = VCard, f = Flash, b = Binary.
dr For non-premium BULK set to 1 = Required or 0 = Not Required.
user [provided to you in your Welcome Service pack] (min-6 ,max-20 chars)
password [provided to you in your Welcome Service pack] (min-6 ,max-20 chars)
msg Insert text of message, maximum 160 chars urlencoded(UTF8), Longer message content may be used by individual agreement & route, and will form part of the SLA.

All other parameters may be ignored.

Example:

  http://smsc.txtnation.com:8091/sms/send_sms.php?
  src=447777000000&dst=447777111111
  &dr=1
  &user=YOUR_USERNAME_HERE
  &password=YOUR_PASSWORD_HERE
  &type=0
  &msg=txtNation%20best%20to%20test%20at%20the%20end%20of%20the%20road.
  http://smsc.txtnation.com:8091/sms/send_sms.php?src=447777000000&dst=447777111111&dr=1&user=YOUR_USERNAME_HERE&password=YOUR_PASSWORD_HERE&type=0&msg=txtNation%20best%20to%20test%20at%20the%20end%20of%20the%20road.


Acceptance Notification

The Enterprise HUB will immediately respond in the same HTTP GET or POST session with either and acceptance notification or an error message, your service should collect evaluate and store this data.


Parameter Values
message Message key or other error Value.
value Message Reference or other Value.

Examples:

   Operation success: 5918189961178883   or  Operation fail: Route Error
   msg_max_length_exeed

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.

Disposition Notifications

When a message is accepted for delivery, a submit_sm_resp primitive is returned 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.

This is translated to an HTTP request which is sent by HTTP GET to a URL of your choosing (You must notify this URL to txtNation technical support team).

The variables for this HTTP notification are:

Body Parameter Values
sms For non-premium BULK A JSON string containing the following parameters.

id:0000000000000000 Receipted_message_id

sub:001 Number of short messages originally submitted. This is only relevant when the original message was submitted to a distribution list.The value is padded with leading zeros if necessary

dlvrd:001 Number of short messages delivered. This is only relevant where the original message was submitted to a distribution list.The value is padded with leading zeros if necessary.

submit date:1410311037 Unix date format

done date:1410311038 Unix date format

stat:DELIVRD The final status of the message. For settings for this field see Table B-2 smpp_3.4_spec.pdf. final stat table value -> DELIVRD / ACCEPTD / REJECTD / EXPIRED / UNDELIV / DELETED / UNKNOWN

err:000 Where appropriate this may hold a Network specific error code or an SMSC error code for the attempted delivery of the message. These errors are in the majority of cases Network or SMSC specific, 60(charging related), 88(onward smsc throttle), 288(txtNation internal throttle), 0 for other errors (see above for further information regarding retrying throttled messages). text The first 20 Chars to the outbound (MT) msg variable.

msisdn For non-premium BULK set to numeric shortcode / MSISDN , maximum 11 chars as per the message sent.
src For non-premium BULK set to numeric shortcode / MSISDN or alphanumeric, maximum 11 chars as per the message sent.
dcs data coding scheme, default 0 = Std SMS ( 0 = Normal plain sms, 8 = Unicode, 240/244 Flash SMS, 245 = vcard )
type Optional parameter Message type ( 0 = Normal plain sms, u = Unicode, f Flash SMS, b = binary )

Example:

  Array
  (
  [sms] => id:5918351498722606 sub:001 dlvrd:001 submit date:1410311037 done date:1410311038 stat:DELIVRD err:000 text:New HTTP Test TxtN
  [msisdn] => 447777000000
  [src] => 447777666666
  [dcs] => eng
  )


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 or general service or platform errors, these should be logged, and werever possible associated with the correct outbound MT SMS message.

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