HTTP API

WIS Telecom

Contents
Introduction: ................................................................................................................................................ 2
1. Sending SMS: ....................................................................................................................................... 3
1.1. HTTP(s) Get request: .................................................................................................................... 3
1.2. HTTP(s) Post request: ................................................................................................................... 4

1
 1.3. GET/POST Send SMS Validate API ............................................................................................... 4
1.4. Send SMS Dynamic DLR API: ........................................................................................................ 5
1.5. Send SMS Response: .................................................................................................................... 6
2. Client Global DLR API: ......................................................................................................................... 8
2.1. URL Http API POST: ...................................................................................................................... 8
2.2. Example of Request JSON body : ................................................................................................. 9
2.3. URL GET DRL API example: .......................................................................................................... 9
3. Vendor: ................................................................................................................................................ 9
3.1. Global Get Submit SMS API Request: .......................................................................................... 9
3.2. Global Post Submit SMS API Request:....................................................................................... 10
3.3. DLR Listener API: ........................................................................................................................ 10
3.4. GetSMS API: ............................................................................................................................... 14
Appendix A ................................................................................................................................................. 17
Appendix B ................................................................................................................................................. 18

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.

The parameters used for sending the SMS messages are described in the following:

2
 • 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 WIS Telecom 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.
• Call Back URL: the DLR listener URL.

1. Sending SMS:

1.1. HTTP(s) Get request:

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

3
http://195.191.165.17:31107/MO/Client/SendSMS?username=XXXXX&password=XXXXX&destination=X
XXXXXXX&sour ce=XXXXX&text=HelloTestMEssage&dataCoding=0

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

http://195.191.165.17:31107/MO/Client/SendSMS?username=[username]&password=[password]&sou
rce=[sourcenu mber]&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://195.191.165.17:31107 /MO/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. GET/POST Send SMS Validate API

We provide our HTTP clients with GET and Post methods, the new feature is to check whether the
number used is available in our prefix list and return an error of Invalid Destination if not found.

URL Base: http://195.191.165.17:31107/MO/Client//SendSmsVal

4
For example:
http://195.191.165.17:31107/MO/Client/SendSmsVal?username=XXX&password=XXX&destination=999
99999222112&s ource=Facebook&text=HelloTestMEssage&dataCoding=0

As this Destination is invalid the below will be the response.

Response:

{
"ErrorCode": -12,
"ErrorDescription": "InvalidDestination",
"SMS": [],
"MessageCount": 0,
"MessageParts": 0
}

1.4. Send SMS Dynamic DLR API:

We provide our HTTP clients with Send SMS which supports Dynamic DLR Listeners where they use
multiple URLs sent in the request for us to use to return DLR to the client. It is also available for GET and
POST Methods

1.4.1. GET Send SMS Dynamic API:

The client should send us all below parameters including the needed DLR Listener in each submit.

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

http://195.191.165.17:31107/MO/Client/SendSMSDyn?username=XXXXX&password=XXXXX&destinatio
n=XXXXXXXX&s ource=XXXXX&text=HelloTestMEssage&dataCoding=0&cbkUrl=[URL]

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

http://195.191.165.17:31107/MO/Client/SendSMSDyn?username=[username]&password=[password]&
source=[sourcen umber]&destination=[destinationnumber,destinationnumber2]&text=[message
text]&datacoding=[Data coding number]&cbkURL=[URL]

1.4.2. POST Send SMS Dynamic API:

5
The messages are submitted by HTTP(s) post request via the following URI:
https://http://195.191.165.17:31107/MO/Client/SendSMSDyn

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
o cbkUrl (call back URL)

Example of HTTP(s) post request:

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

1.5. 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/Numeric/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 Check Appendix A*

N.B: In case you are sending multiple messages, you shall receive the below response.

6
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
}

7
 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 WIS Telecom Account.
• Password: password of WIS Telecom Account.
• MCCMNC: value of the MCC and MNC concatenated in one string such as “51002”.
• Rate: Rate of the SMS.

8
 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$",
"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$

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:

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

http://195.191.165.17:31107/api/HttpSimulator/SubmitSMS?username=[Username]&password=[Pas
sword]&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://195.191.165.17:31107/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. 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. GET DLR Listener API:

URL Example:

http://195.191.165.17:31107/MT/api/Vendor/DLRListener?username=XXXX&password=XXXX&sende
r=XXXX&desti nation=XXXXXXXXXX&messageId=14fce738-d50a-46b6-
9e8a4b83444bae6e&deliveryStatus=2&dateReceived=2/26/2019%2012:00:00%20AM&description=D
elivered

The messageid in the above URL sample is the Message ID of the provider.

The delivery status with their errors and description are listed in the below:
o 2 = Delivered
o 3 = Expired

10
 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

https://IP:Port/MT/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 WIS Telecom.

The JSON HTTP Body request contains the following parameters:

o Sender
o Destination
o messageId
o deliveryStatus

11
 o dateReceived
o description
o username
o password

The messageId in the above request is provided by the provider.

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

12
 3.3.3. Get DLRListenerBasic API:

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

DLR URL example:

https://IP:Port/MT/api/Vendor/DLRListenerBasic?ConnectionId=XXX&MessageId=XXX&Status=2

The connectionId is an integer constant that we provide to the providers.

The messageid in the above URL sample is the Message ID of the provider.

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.4. GET DLRListenerGet API:

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

DLR URL example:

https://IP:Port/MT/api/Vendor/DLRListenerGet?ConnectionId=XXX&Status=2&(et
c...)

The connectionId is an integer constant that we provide to the providers.

Providers are free to send us whatever parameters they want by replacing the (etc…) part in the URL
above.

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.4. GetSMS API:

We provide our HTTP Clients with a GetSMS API GET and POST so that they can extract the message
details.
3.4.1. GET SMS API:

14
In the get Method we have 2 ways that the Client can use to extract the message details.

Method 1: Get 1 message SMS only

http://[URL]/MO/Client/getsms?MessageId={MessageID}

Method 2: Get all the messages details having the same Destination Number

http://[URL]/MO/Client/getsms?clientid={ClientID}&Destination={DestinationNumber}&FromDate={Dat
e}

Noting that both Methods will extract the data for the last 3 days only and for method 2 will extract only
the latest 10 messages with same destination number.

***ClientID: Check with BPal team to provide the Bpal Client ID.

3.4.2. Post SMS API:

Same parameters as in GET in both methods. Examples are provided below:

POST URL : http://[URL]/MO/Client/getsms

Method 1 body request example:

{ "messageId": "7c3f3a16-f1b9-4024-b18d-c5433412ca96" }

Method 2 body request example:

{
"destination": "XXXXXXXXX",
"fromDate": "YYYY-MM-DD HH:MM:SS",
"clientId": "E2983EE3-836B-EB11-A253-BBBBBBBBB"
}
3.4.3. Responses:

In case of success the below are the responses:

{
"ErrorCode": 0,
"ErrorDescription": "Ok",
"SMSResponse": [
{
"OriginatingAddress": "XXXXXX",

15
 "DestinationAddress": "XXXXXXXXXXX",
"Country": "Lebanon",
"Operator": "MTC Touch",
"MessageId": "7c3f3a16-f1b9-4024-b18d-c5433412ca96",
"Message": "this is a test sample",
"DeliveryTime": "2/16/2021 10:04:01 AM",
"DeliveryStatus": "UNDELIV",
"CreatedDate": "2021-02-16T10:04:01"
}
]
}

In case of failure Check Appendix B* for Error codes.

Sample Response Below:

{
"ErrorCode": -13,
"ErrorDescription": "InvalidDate",
"SMSResponse": []
}

16
 Appendix A
In the below list you will find all possible error code that may be received upon Testing the API. Most
of the Error code as self-explanatory and the reflect the area that requires attention.
• Ok = 0
• NoMessage = -1
• NoSource = -2
• NoDestination = -3
• UnsupportedDestination = -4
• InvalidCredentials = -5
• NoCredit = -6
• InvalidDataCoding = -7
• IPNotWhiteListed = -8
• UnknownError = -10
• InvalidInstanceConnection = -11
• InvalidDestination = -12

17
 Appendix B
In the below list you will find all possible error code that may be received upon Testing the API. Most
of the Error code as self-explanatory and the reflect the area that requires attention.
• InvalidDate = -13
• InvalidMessageId = -14
• InvalidClientId = -15
• InvalidParameters = -16

18