Introduction:

This document provides the guidelines on how to use the HTTP(s) SMS API interface for sending a
single SMS or bulk SMS to valid Mobile phone numbers.

You submit all your requests over HTTP/HTTPs in the host: http://api.iconglobal.co.uk

The parameters used for sending the SMS messages are described in the following:
• Username: represents the username of the created account
• Password: represents the username of the created account
• Destination: is the valid mobile number where the SMS is to be sent.(Note the + sign is
not supported)
• Source: is the Sender ID of the sent message.
• Text/content: is the body of the message.
• Data coding: defines the encoding format:
o Default GSM 7 bit = 0
o ISO-88592 Eastern European Latin2= 1
o ISO-88591 Western European Latin1 = 3
o ISO-88594 North European Latin4 = 4
o ISO-2022 Japanese = 5
o ISO-88595 Cyrillic = 6
o ISO-88598 Hebrew = 7
o Unicode UCS2 = 8

In addition, this guideline covers the connection between Icon-Global Gateway and the HTTP vendor.
The parameters used for receiving DLRs are described in the following:
• Username: represents the username of the created account
• Password: represents the username of the created account
• Sender: is the Sender ID of the sent message
• Destination: is the Sender ID of the sent message
• MessageId: to be used in case if any enquiry about the message
• Delivery Status: the code of the delivery status
• Description: description of the delivery status
• Datereceived: the received date of the message
• Data coding: defines the encoding format of the message
 1. Sending SMS:

1.1. HTTP(s) Get request:

A single SMS is sent via the below URL by filling the correspondent parameters:

http://api.iconglobal.co.uk/HTTP/api/Client/SendSMS?username=XXXXX&password=XXXXX&destination
=XXXXXXXX&source=XXXXX&text=HelloTestMEssage&dataCoding=0

Multiple Messages are sent via the below URL by filling the correspondent parameters:

http://api.iconglobal.co.uk/HTTP/api/Client/SendSMS?username=[username]&password=[password]&s
ource=[sourcenumber]&destination=[destinationnumber,destinationnumber2] &text=[message
text]&datacoding=[Data coding number]
1.2. HTTP(s) Post request:

The messages are submitted by HTTP(s) post request via the following URI:
http://api.iconglobal.co.uk/HTTP/api/Client/SendSMS.

The HTTP request Headers contains the following parameters:

o Username
o Password
o Json Content-Types( As example: Content-Type: application/json)

The JSON HTTP Body request contains the following parameters:

o destination
o source
o text
o Data Coding

Example of HTTP(s) post request:

{
"destination":"XXXXXXXXXX",
"source":"XXXX",
"text":"XXXX",
"dataCoding":0
}

1.3. Send SMS Response:

After submitting the HTTP request using get or post method, you will get a response containing the
following parameters:
• ErrorCode : State of the message (Values are shown below)
• Error Description: Status of the message (Values are shown below)
• SMS entity contains the following parameters:
 o ErrorCode: State of the message (Values are shown below)
o Id: to be used in case if any enquiry about the message
o OriginatingAddress: Alpha/Numneric/AlphaNumeric source of the
Message(Sender ID)
o DestinationAddress: Mobile Destination Number
• Message Count: the number of sent messages
• Message Parts: the number of part for each message

The error codes and descriptions are:

0 = Ok
b. -1 = NoMessage
c. -2 = NoSource
d. -3 = NoDestination
e. -4 = UnsupportedDestination
f. -5 = InvalidCredentials
g. -6 = NoCredit
h. -7 = InvalidDataCoding
i. -8 = IPnotwhitelisted
j. -10 = UnknownError
k. -11 = InvalidInstanceConnection

N.B: In case you are sending multiple messages, you shall receive multiple ids separated by comma.

Here is an example of an HTTP(s) Response:

{
ErrorCode:0,
ErrorDescription:"Ok",
SMS:[
{
ErrorCode:0,
Id:"52be91a8-0a1e-4cfe-ab5c-68fc0f96b2f0",
OriginatingAddress:"XXXX",
DestinationAddress:"XXXXXXXXXX",

}
],
MessageCount:2,
MessageParts:2
}

2. Client Global DLR API:

After you have sent a couple of messages, you are able to check if they were successfully delivered by
providing an HTTP URL in order to push the DLR into it.

2.1. URL Http API POST:

The JSON request body can have multiple parameters (Name, value and description) based on the client
needs. The client can add and edit many parameters to the request
The below is an example of the parameters names with its Values & Description:
• MobileNumber: Mobile Phone Number
• SendDate: the date of sending message
• Receive Date: the date of receiving message.
• StatusId: The status id of the message
o 2
o 3
o 4
o 5
o 6
o 7
o 8

• Status: Message status

o 2 = Delivered
o 3 = Expired
o 4 = Deleted
o 5 = Undelivered
o 6 = Accepted
o 7= Invalid
o 8= Rejected
• Message Id: to be used in case if any enquiry about the message
• Username: username of Icon-Global Account
• Password: password of Icon-Global Account
• MCCMNC: value of the MCC and MNC concatenated in one string such as “51002”
• Rate: Rate of the sms

2.2. Example of Request JSON body :

{
"CallBackResponse":{
"MobileNo":"$NUMBER$",
"Senddate":"$SENDDATE$",
"ReceiveDate":"$RECEIVEDATE$",
"Status":"$STATUS$",
"MessageId":"$MessageId$",
"StatusId":"$StatusId$",
 "Username":"$Username$",
"Password":"$Password$",
"MCCMNC":"$MCCMNC$",
"Rate":"$Rate$",
"TotalRate":"$TotalRate$",
"VendorCode":"SMSVEN00001"

}
}

The most used DLR Request written in Json language is:

{
"messageId": "$MessageId$",
"statusId": "$StatusId$"
}

2.3 URL GET DRL API example:

http://[IP]/GetDLR?MobileNo=$NUMBER$&Senddate=$SENDDATE$&ReceiveDate=$RECEIVEDATE$&Sta
tus=$STATUS$&MessageId=$MessageId$&StatusId=$StatusId$&Username=$Username$&Password=$P
assword$&mccmnc=$MCCMNC$&rate=$Rate$&TotalRate=$TotalRate$

3. Vendor:

Vendors of type HTTP can now be created on our Gateway that can Submit SMS through HTTP API Get
or Post which are detailed below.
We provide a Global HTTP Vendor provider Submit SMS APIs for GET and POST and a global DLR Listener
GET or POST, in addition and most importantly, we can tailor easily a vendor HTTP API provider specific
for vendors that does not support our Global HTTP Vendor provider.

3.1. Global Get Submit SMS API Request:

The Global HTTP vendor will provide a URL such as below example:

http://[ip]/api/HttpSimulator/SubmitSMS?username=[Username]&password=[Password]&source=[S
ource]&destination=[Destination]&MessageText=[Content]
&dataCoding=[DataCoding]

3.2. Global Post Submit SMS API Request:

The Global HTTP vendor will provide a URL such as below example:
http://[ip]/api/HttpSimulator/SubmitSMSPost

The request could be written in Json language.

Request JSON Body example:

{
"destination":"$destination$",
"source":"$source$",
"content":"$content$",
"username":"$username$",
"password":"$password$",
"dataCoding":"$datacoding$"
}

3.3. Get DLR Listener API:

We provide our HTTP Vendors with a Global DLR Listener GET and POST API so that they can send us the
Delivery report.

3.3.1. DLR GET URL example:

http://api.iconglobal.co.uk/HTTP/api/Vendor/DLRListener?username=XXXX&password=XXXX&sende
r=XXXX&destination=XXXXXXXXXX&messageId=14fce738-d50a-46b6-9e8a-
4b83444bae6e&deliveryStatus=2&dateReceived=2/26/2019%2012:00:00%20AM&description=Deliver
ed

The delivery status with their errors and description are listed in the below:
o 2 = Delivered
o 3 = Expired
o 4 = Deleted
o 5 = Undelivered
o 6 = Accepted
o 7= Invalid
o 8= Rejected

Example of a DLR-Response:

{
"ErrorCode": 0,
"ErrorDescription": "Ok"
}

Error Codes and descriptions are:

• 0 = Ok
 • 1= Invalid Credentials
• 2= Credentials Required
• 3= Invalid Query String Parameters
• 10= Internal Server Error

3.3.2. Post DLR Listener API:

We provide our HTTP Vendors with a Global DLR Listener POST API so that they can send us the Delivery
report.

Example of DLR POST URL

http://api.iconglobal.co.uk/HTTP/api/Vendor/DLRListener

The HTTP request Headers contains the following parameters:

o username = “username”
o password = “password”
o Json Content-Types( As example: Content-Type: application/json)

Username and password will be provided by Vendor.

The JSON HTTP Body request contains the following parameters:

o
o Sender
o destination
o messageId
o deliveryStatus
o dateReceived
o description
o username
o password

Example of HTTP Request Body:

{
"sender":"XXXX",
"destination":"XXXXXXXXXX",
"messageId":"f09a7735-4939-4548-ae50-f035b75dcde4",
"deliveryStatus":"2",
"dateReceived":"2019-02-26T00:00:00",
"description":"Delivered",
"username":"XXXX",
"password":"XXXX"
}

Note: If username and password are not provided in the HTTP Header, they will be read from the HTTP
request body.
The delivery status with their errors and description are listed in the below:
o 2 = Delivered
o 3 = Expired
o 4 = Deleted
o 5 = Undelivered
o 6 = Accepted
o 7= Invalid
o 8= Rejected

Example of a DLR-Response:

{
"ErrorCode": 0,
"ErrorDescription": "Ok"
}

Error Code and descriptions are:

• 0 = Ok
• 1= Invalid Credentials
• 2= Credentials Required
• 3= Invalid Query String Parameters
• 10= Internal Server Error

3.3.3. DLR Listener Basic:

We provide our HTTP Vendors with a Basic DLR Listener so that they can send us the Delivery report.

DLR URL example:

DLRListenerBasic { ConnectionId = XXXX&MessageId = XXXXXXXXX&Status=XXXX}

The delivery status with their errors and description are listed as per the below:
o 2 = Delivered
o 3 = Expired
o 4 = Deleted
o 5 = Undelivered
o 6 = Accepted
o 7= Invalid
o 8= Rejected

Example of a DLR-Response:

{
"ErrorCode": 0,
 "ErrorDescription": "Ok"
}

Error Codes and descriptions are as follows:

• 0 = Ok
• 1= Invalid Credentials
• 2= Credentials Required
• 3= Invalid Query String Parameters
• 10= Internal Server Error

3.3.4. DLR Listener Get:

We provide our HTTP Vendors with a dynamic Get DLR Listener where we can add a query string as
requested by vendor so that they can send us the Delivery report.

DLR URL example:

DLRListenerGet { ConnectionId = XXXX&MessageId =

XXXXXXXXX&Status=XXXX&Reasoncode=XXX&Reference=XXXXXXX}

The delivery status with their errors and description are listed as per the below:
o 2 = Delivered
o 3 = Expired
o 4 = Deleted
o 5 = Undelivered
o 6 = Accepted
o 7= Invalid
o 8= Rejected

Example of a DLR-Response:

{
"ErrorCode": 0,
"ErrorDescription": "Ok"
}

Error Codes and descriptions are as follows:

• 0 = Ok
• 1= Invalid Credentials
• 2= Credentials Required
• 3= Invalid Query String Parameters
• 10= Internal Server Error