ADVANCE MESSAGING

SYSTEM

SMS
SMS API DOCUMENT
ADVANCE MESSAGING SYSTEMS

INDEX

S. No Content Page No.

1 Introduction 3

2 SMPP 4

3 HTTP 6

3.1 Message Submission & Scheduling 7

3.2 Status Enquiry 12

3.3 Balance Enquiry 13

3.4 Coverage Download 14

3.5 Web DLR 15

4 XML 16

Page | 2
ADVANCE MESSAGING SYSTEMS

Introduction

This document provides SMPP specification including connection to

advance messaging systems server, bind options and specification for
sending sms over SMPP. This document also provides HTTP API used to
sending SMS, collecting delivery reports along with HTTP API
specification.

Page | 3
ADVANCE MESSAGING SYSTEMS

SMPP
The Short Message Peer-to-Peer (SMPP) is a protocol used by the
telecommunications industry for exchanging SMS messages between
Short Message Service Centers (SMSC) and External Short Messaging
Entities (ESME). The protocol is a level-7 TCP/IP protocol, which allows
fast delivery of SMS messages.

The connection between application and AMS SMPP Server is SMPP

version 3.4

BIND Operation: The purpose of the SMPP bind operation is to register

an instance of an ESME with the SMSC system and request an SMPP
session over this network connection for the submission or delivery of
messages. Thus, the Bind operation may be viewed as a form of SMSC
login request to authenticate the ESME entity wishing to establish a
connection.

BIND Mode: User may bind as either Tx (Transmitter), Rx (Receiver) or

TRx (Transceiver).

Tx: User bound as a Transmitter is authorized to send short messages

and to receive the corresponding SMPP responses.

Rx: User bound as a Receiver is authorized to receive short messages

and to return the corresponding SMPP message responses.

TRx: User bound as a Transceiver is allowed to send & receive messages

over a single SMPP session.

*Users are allowed to bound as only 1 TRx/Rx with multiple Tx

Session.

Page | 4
ADVANCE MESSAGING SYSTEMS

Requested Parameters:

Name Description

System id Provided System Id

Password Provided Password

IP 5.10.90.210

Port 8899

System type Null

Page | 5
ADVANCE MESSAGING SYSTEMS

HTTP

The Hypertext Transfer Protocol (HTTP) is an application-level protocol for

distributed, collaborative, hypermedia information systems. This is the
foundation for data communication for the World Wide Web (i.e. internet)

HTTP is a generic and stateless protocol which can be used for other
purposes as well using extensions of its request methods, error codes, and
headers. This document provides developers with instructions for
integrating SMS messaging services into various solutions using HTTP
API.

This HTTP API can be used in sending SMS, collecting delivery reports
along with HTTP API specification .This document also provide SMPP
specification including connection to advance messaging systems server,
bind options and specification for sending sms over SMPP

Users can Use Following Services via HTTP API:

1) Message Submission & Scheduling

2) Status Enquiry
3) Balance Enquiry
4) Coverage Download

Page | 6
ADVANCE MESSAGING SYSTEMS

3.1 Message Submission & Scheduling

HTTP API supports both GET and POST Methods. Using GET Method limit
of up to 100 numbers is allowed in a single request. For POST Method limit
of up to 10000 numbers is allowed in a single request.

Description:

URL for Message Submission:

http://5.10.90.210:8080/websmpp/websms?
user=xxxx&pass=xx&sid=xxxxx&mno=961xxxxx&type=x&text=xxx
URL for Message Scheduling:

http://5.10.90.210:8080/websmpp/websms?
user=xxxx&pass=xx&sid=xxxxx&mno=961xxxxx&type=x&text=xxx

&gmt=xxxxx&schtime=xxxxxxxxxxxx

Requested Parameters (mandatory):

Name Description

user Provided System Id

pass Provided Password

Source Number
sid
(Numeric/Alphanumric)
Destination Number or Comma
mno separated Destination Numbers
(Including Country Code)

type Message Type (1,2,3,4)

text Message Content

Page | 7
ADVANCE MESSAGING SYSTEMS

Optional Parameters (Scheduling):

Name Description

gmt GMT i.e. +0530

schtime Schedule time (yyyyMMddhhmm)

Message Type & Length:

Value Message Type Length (1 SMS)

1 English 160

2 Unicode 280

3 Special Character 160

4 Arabic 70

Examples:

● English Message:

http://5.10.90.210:8080/websmpp/websms?
user=testUser&pass=12345&sid=Test&mno=961xxxxx&type=1
&text=testing English message

Page | 8
ADVANCE MESSAGING SYSTEMS

● Unicode Message:

http://5.10.90.210:8080/websmpp/websms?
user=testUser&pass=12345&sid=Test&mno=961xxxxx&type=2
&text= 00740065007300740069006E006700200075006E006
90063006F006400650020006D006500730073006100670065

● Special Character Message:

http://5.10.90.210:8080/websmpp/websms?
user=testUser&pass=12345&sid=Test&mno=961xxxxx&type=3
&text=testing $@ Character

● Arabic:

http://5.10.90.210:8080/websmpp/websms?
user=testUser&pass=12345&sid=Test&mno=961xxxxx&type=4
&text= ‫ﻋرﺑﯾﺔ رﺳﺎﻟﺔ اﺧﺗﺑﺎر‬

● Scheduling:

http://5.10.90.210:8080/websmpp/websms?
user=testUser&pass=12345&sid=Test&mno=961xxxxx&type=1
&text=testing Schedule &gmt=+0530&schtime=201605101422

Note: The characters [ ] { } | \ ~ ^ will be counted twice. The characters & and # are restricted in
message content.

Page | 9
ADVANCE MESSAGING SYSTEMS

Response Format

On Successful Submission:
Response: 2541524

On Failed (Possible Errors):

ERROR - HTTP01 --> Invalid HTTP URL Format

ERROR - HTTP02 --> Invalid query string

ERROR - HTTP03 --> Message Submission Failed

ERROR - HTTP04 --> Invalid Password

ERROR - HTTP05 --> Invalid System ID

ERROR - HTTP06 --> Invalid Sender ID

ERROR - HTTP07 --> Invalid Type

ERROR - HTTP08 --> Invalid Message ID

ERROR - HTTP09 --> Invalid Destination Address

ERROR - HTTP10 --> Invalid number of messages

ERROR - HTTP11 --> Requested service is unavailable

ERROR - HTTP12 --> Submit Failed

ERROR - HTTP13 --> Query request failed

ERROR - HTTP14 --> Bind failed

ERROR - HTTP15 --> Not Authorized for the request.

ERROR - HTTP16 --> Invalid Request

Page | 10
ADVANCE MESSAGING SYSTEMS

ERROR - HTTP17 --> Invalid Message Length

ERROR - HTTP18 --> INSUFFICIENT CREDITS/BALANCE

ERROR - HTTP19 --> Invalid DATA CODING SCHEME

ERROR - HTTP20 --> Invalid ESM

ERROR - HTTP21 --> Invalid HEADER

ERROR - HTTP22 --> Invalid Schedule Time

ERROR - HTTP23 --> Routing Error

ERROR - HTTP24 --> Exceeded number of Destination

ERROR - HTTP25 --> No Record Found

ERROR - HTTP26 --> Account Expired

Page | 11
ADVANCE MESSAGING SYSTEMS

3.2 Status Enquiry

After Successful Submission, User can get Message Status via Following
URL:

http://5.10.90.210:8080/websmpp/websmsstatus?respid=2541524
Resulting status would be one of them from the following table:

Name Description

ATES Pending

DELIVRD Delivered

UNDELIV Undelivered

EXPIRED Message Validity Period Expired

REJECTD Rejected

ACCEPTD Accepted

DELETED Deleted

UNKNOWN Unknown

Page | 12
ADVANCE MESSAGING SYSTEMS

3.3 Balance Enquiry

After Successful Submission, User can get Message Status via Following
URL:

http://5.10.90.210:8080/websmpp/balanceReport?userid=systemid&
password=pwd

● The parameters userid & password are mandatory. Failing any

would result in a negative response.

Page | 13
ADVANCE MESSAGING SYSTEMS

3.4 Coverage Download

User can get Coverage via Following URL:

http://5.10.90.210:8080/websmpp/ downloadcoverage?
userid=systemid&password=pwd&format=x

● The parameters userid & password are mandatory.

● Format is optional parameter. If not specified the default format
will be 1.

Requested Formats:

Value Downloaded Format

1 XLS

2 PDF

3 CSV

Page | 14
ADVANCE MESSAGING SYSTEMS

3.5 Web DLR

User can get DLR via Provided Web Link. The URL for each client would
look like ‘http://www.test.com/dlr/dlr.aspx’.The method used for posting
delivery report onto the client’s URL is POST. After receiving DLR, the link
must return Ok as acknowledgement.

The parameters appended to the URL would be as below:

Parameter Discription

MessageId Message Id provided on submission

Source Source Address

Destination Destination Number

Status Status of the Request (i.e. DELIVRD,UNDELIV,ATES)

SubmitDate Time of Submission (yyMMddHHmm)

DoneDate Time of Delivery Report Receiving( yyMMddHHmm )

Page | 15
ADVANCE MESSAGING SYSTEMS

XML

Users can Use Following Services via XML API:

1. Message Submission
2. Status Enquiry

4.1 Message Submission: The URL used to post XML formatted data
is:

http://5.10.90.210:8080/websmpp/xmlsms

Request Format Example[1]:

<?xml version="1.0" encoding="UTF-8"?>

<campaign format="1">
<SMS>
<username>testUser</username>
<password>pass</password>
<type>1</type>
<sender>TEST-XML1</sender>
<text>testing xml request via http</text>
<recipients>
<gsm>961231213</gsm>
<gsm>961321987</gsm>
</recipients>
</SMS>
</campaign>

Page | 16
ADVANCE MESSAGING SYSTEMS

Request Format Example[2]:

<?xml version="1.0" encoding="UTF-8"?>

<campaign>
<SMS format="2">
<username>testUser</username>
<password>pass</password>
<type>1</type>
<sender>TEST-XML1</sender>
<custom>
<gsm>961231211</gsm>
<text>testing xml custom request 1 via http</text>
</custom>
<custom>
<gsm>961231212</gsm>
<text>testing xml custom request 2 via http</text>
</custom>
<custom>
<gsm>961231213</gsm>
<text>testing xml custom request 3 via http</text>
</custom>
</SMS>
</campaign>

Response: After Submission User will get Response as below:

<?xml version="1.0" encoding="UTF-8"?>

<response>
<status>000</status>
<batch_id>171117172801751</batch_id>
</response>

Page | 17
ADVANCE MESSAGING SYSTEMS

batch_id is unique id and used to identify all the messages( on all gsm
numbers) associated with this request.
Status will be 000 on successful Submission. For Other status please
check the xml status Code table.

Page | 18
ADVANCE MESSAGING SYSTEMS

4.2 Status Enquiry: After Successful Submission, User can get

Message Status via Following URL:

http://5.10.90.210:8080/websmpp/xmlstatus

To Enquire the Status of Submissions, A specified format is Required as

below:

<?xml version="1.0" encoding="UTF-8"?>

<enquiry>
<username>testUser</username>
<password>pass</password>
<batch_id>171117104025321</batch_id>
</enquiry>

Resulted Format : The Resulted XML Format Will be as below:

<?xml version="1.0" encoding="UTF-8"?>

<result>
<batch_id>171117172801751</batch_id>
<report>
<messageid>521452541</messageid>
<dlrstatus>DELIVRD</dlrstatus>
<status>000</status>
</report>
<report>
<messageid></messageid>
<dlrstatus></dlrstatus>
<status>006</status>
</report>
</result>

Page | 19
ADVANCE MESSAGING SYSTEMS

XML Status Code Table

This section Describes Errors Returned as Response On Submission (if

Failed):

Code Name Description

000 NO_ERROR success
001 INVALID_LOGIN Either System_id or password is
invalid
002 INVALID_REQUEST Required parameters are missing or
Invalid parameters or invalid values
of parameters
003 ACCOUNT_EXPIRED Account has been Expired
004 INSUF_BALANCE Insufficient balance
005 INVALID_DEST_ADD Invalid Destination Address
R
006 NO_COVERAGE Requested Destination is not
Allowed
007 SYSTEM_ERROR System Error
008 INVALID_SENDER Invalid Source Address
009 INVALID_TEXT Invalid message content
010 INVALID_TYPE Invalid Message Type
050 ACCESS_DENIED Either Web Access Not Allowed or
Account is Blocked
051 IOSTREAM_ERROR Input Stream Error
052 INVALID_BATCHID Invalid Batch Id (must be 15 digits)

Page | 20
ADVANCE MESSAGING SYSTEMS

053 NO_RECORDS Records are not available for

provided Batch Id

Page | 21