User Manual interfaces

HTTP, XML , API and SMPP

Page 1 of 15
Document Version1.0
List of Contents
Part No. Contents Page
1 Overview 3
2 HTTP Interface Specifications 3
2.1 Basic Query 3
2.2 Query Parameter Description 4
2.3 HTTP Interface Response 5
2.4 Send single SMS to one Recipient Query 6
2.5 Send single SMS to multiple recipients Query 6
2.6 Send POST Request 7
2.7 SMS Sending Errors 8
2.8 Receive DLR from HTTP Interface 9
2.9 Credit Balance Query 9
2.10 Check Credit Balance Errors 9
3 XML Interface Specifications 10
4 SMPP Interface Specifications 11
5 API Interface 13

Page 2 of 15
Document Version1.0
 1. Overview
This document is for those clients who want to develop business applications to integrate with Deewan
AlRasaile and make use of its facilities in handling different types of sending SMS.
These Interfaces provide the client’s with the ability to integrate with Deewan AlRasaile to send SMS .
It was designed to help developers be more productive and to be able to add SMS functionality to any
project efficiently. Below are the main interfaces for this integration purposes:

 HTTP interface: using GET and POST method over SSL.

 XML interface: using HTTP POST method to pass an XML file over HTTP URL.
 SMPP 3.4 (Using SMPP standards)

2. HTTP Interface Specifications

The HTTP Interface offers a number of messaging queries and SMS features, which can be performed
by forming the designated URL. HTTP Interface also support connection via Secure Socket Layer (SSL).

2.1. Basic Query :

Query is made up of three segments:
a. Authentication: username and password
b. The Basic Message components: message content and recipients and the
c. Additional message parameters
In the examples below, we will include the authentication and basic message components. The
additional message parameters will be included only where they are relevant.

Basic Query Structure:

https://ht.deewan.sa:8443/Send.aspx?UserName=xxx&Password=xxx&MessageType=xxxx&R
ecipients=xxxx&SenderName=xxx&MessageText=xxx

Page 3 of 15
Document Version1.0
2.2. Query Parameter Description:

Parameter Type Short Description Restricted Values

UserName String Your account username
(Required)
Password String Your account password
(Required)
Recipients String SMS Recipients valid mobile numbers .In The number should be in required
(Required) case of multiple recipients, the numbers international number format.
passed in a comma-separated format. Recipient no. consists of:
country code + network prefix
+ mobile number
e.g.: 966501231234
MessageText String Content of the message ,Unicode/English
(Required)
SenderName String The message sender ID ,which will be in an 11 character alphanumeric string;
(Required) the message. e.g : DeewanSMS
The sender name can be text only Note: The characters such as spaces,
e.g .DeewanSMS punctuation, Unicode, and other special
characters are not recommended. (0) don’t
return
Acknowledgement Int This will return a delivery acknowledgement
(Optional) acknowledgement for any message, upon (1)return acknowledgement
delivery of the message to the mobile
stations.

Delivery Time Int Delays delivery of SMS to mobile device , The upper limit is 7 days ,or 10080
(Optional) here the SMS was received by our SMSC. minutes.
it's should be greater than 10 minutes
for best effect .Smaller time frames may
be delivered soon

ClientMessagelD Long Client message ID defined by the client Up to 32 Alphanumeric characters.

(Optional) for internal message tracking in his/her
business application.

MessageType String Either Text or Unicode: In case of Unicode: You should convert
(Required) Text: This is the default message type. To message text to UTF-16BE before sending it
send plain text messages. through URL
Unicode: Send UTF-16BE messages.
ValidityPeriod Int 1440 This format. Set value at X minutes to
(Optional) the period in minutes, minutes where the
SMS was (24 received by SMSC)The
message will not be delivered if it is still
queued in the SMSC after this period.
DlrUrl String If you want to receive DLR you have to
(Optional) setup your own http service on your own
servers.
And send service url to Deewan AlRasaile
interface in this parameter.

Page 4 of 15
Document Version1.0
2.3. HTTP Interface Response:
Interface will return JSON response .Response will be in below format:
{
"requestStatus": {
"RequestID":<number>,
"ClientMessageID": <text>,
"ResponseText": <text>
},
"invalidRecipients":<text>,
“notSentTryAgain”:<text>,
"errors": [
<number>,<text>
]
]
}
Where:

Property Description
RequestID Random generated ID for each request
ClientMessageID Id that customer send in the request, interface return it as is.
ResponseText Request status.
invalidRecipients CSV of all invalid mobile numbers in the request
notSentTryAgain CSV of all numbers that didn’t sent and you can try to send them again.
Errors List of errors that occur while handle request

Page 5 of 15
Document Version1.0
2.4. Send single SMS to one Recipient Query
Request Format:
https://ht.deewan.sa:8443/Send.aspx?UserName=uuuu&Password=ppp&MessageType=text&Recipie
nts=1111111111111&SenderName=sss&MessaqeText
Response Format :JSON
{
"requestStatus": { "RequestID": 854289307,
"ClientMessageID": 10,
"ResponseText": "Request Handled Successfully"
},`
"invalidRecipients": "", “notSentTryAgain”: "", "errors": []
}

2.5. Send single SMS to multiple recipients Query

Request Format:
https://ht.deewan.sa:8443/Send.aspx?UserName=uuu&Password=ppp&MessageType=text&Recipients=96650
0000000,966561111111&SenderName=ssss&MessageText=mmmm

Response Format :JSON

{
"requestStatus": { "RequestID": 854289307,
"ClientMessageID": 10,
"ResponseText": "Request Handled Successfully"
},`
"invalidRecipients": "", “notSentTryAgain”: "", "errors": [
[-4, "Invalid Recipient Number: 201006"]
]
}

Page 6 of 15
Document Version1.0
2.6. Send POST Request

To send HTTP POST request, send parameters as post data.

Host or url = https://ht.deewan.sa:8443/send.aspx
Post data =
“UserName=uuu&Password=ppp&MessageType=text&Recipients=966555555555&SenderName=sss
s&MessageText=example”

Example in C:#
var request = (HttpWebRequest)WebRequest.Create(" https://ht.deewan.sa:8443/send.aspx");
var postData=
"UserName=uuu&Password=ppp&MessageType=text&Recipients=966555555555&SenderName=sss
s&MessageText=example";
var data = Encoding.ASCII.GetBytes(postData); request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded"; request.ContentLength = data.Length;
using (var stream = request.GetRequestStream())
{
stream.Write(data, 0, data.Length);
}
var response = (HttpWebResponse)request.GetResponse();
var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();

Page 7 of 15
Document Version1.0
 2.7. SMS Sending Errors
In the aforementioned queries ,if invalid or empty parameters were passed in the HTTP request a list
of defined errors will be returned as explained below:

Error Code Error Text Comment

-1 Authentication Failed; Username missing.
-1 Authentication Failed; Password missing.
-1 Authentication Failed; Account Not found.
-1 Authentication Failed; Password does not
match.
-1 Authentication Failed; Account Expired.
-1 Authentication Failed; No Permission to send
from this interface.
-2 Invalid Validity Period
-3 No Recipients.
-4 Invalid Recipient Number :<number>
-5 Invalid Client message ID. If length more than 32 char
-6 Empty Message
-7 Invalid Message Type
-8 Invalid Delivery Time
-9 Invalid Sender Name
-10 Not sent for recipient :<number> try again
later!
-12 Not Enough Credits.
-15 Flashing should be 0 or 1
-16 Invalid Unicode data! If message text is Unicode
and invalid
-18 Acknowledgment should be 0 or1

Page 8 of 15
Document Version1.0
2.8. Receive DLR from HTTP Interface
To receive DLR from HTTP interface you should do the following:

 On your premises, develop http service to parse the parameters of GET request, let say it will
be:
o www.account.com/dlr.aspx.

 Add the URL of this service in http request parameters:

o https://ht.deewan.sa:8443/send.aspx?UserName=uuu&Password=ppp&MessageType=
text&dlrurl=www.account.com/dlr.aspx&Recipients=966555555555&SenderName=sss
s&MessageText=xxxxxx

Or, as alternative to previous step, predefine DLR URL in your account profile in portal under
"Delivery Address" field.
 When DLR is received from GSM network, HTTP interface will send it your service as GET
request in this format:
o www.account.com/dlr.aspx?msgid=guid&statusid=1&from=Sender&to=966555555555&
statusmsg=NACK&accountid=user&SubmitDate=2020-03-12+09%3A07%3A37

If you send ClientMessageID in HTTP request, you will received it in DLR like this:
o www.account.com/dlr.aspx?ClientMessageID=123&msgid=guid&statusid=1&from=Sen
der&to=0020100123w4567&statusmsg=NACK&accountid=user&SubmitDate=2020-03-
12+09%3A07%3A37
_______________________________________________________________________________________

2.9. Credit Balance Query

Request Example:

https://ht.deewan.sa:8443/BalanceQuery.aspx?UserName=xxxx&Password=xxxx

Response Example:

Credit=xxxxxxxx

___________________________________________________________________________________________

2.10. Check Credit Balance Errors

Error Number Error Parameter Returned Error Message
-1 If passing invalid username and password Authentication Failed.
-3 If passing empty value in a required parameter Invalid or Missing Parameter
-9 If there is no credit No credit lift

Page 9 of 15
Document Version1.0
3. XML Interface Specifications
In the XML interface the client can post XML file with certain schema to pass the required parameters.
XML File Sample:

<?xml version=‘1.0’ ?>

<root>
<File_Description>
<File_Type>Classic</File_Type>
<MessagesCount>1</MessagesCount>
<UserName>1234</UserName>
<Password>1234</Password>
<DlrUrl></DlrUrl>
<DateStamp></DateStamp>
</File_Description>
<Messages>
<Message>
<MessageText>sample</MessageText>
<MessageContent></MessageContent>
<ClientMessageID>101</ClientMessageID>
<Flashing></Flashing>
<SenderName></SenderName>
<Acknowledgement>True</Acknowledgement>
<EnableCallback>2</EnableCallback>
<DeliveryTime>1440</DeliveryTime>
<MaximumCredits></MaximumCredits>
<MessageType>text</MessageType>
<ValidityPeriod>1440</ValidityPeriod>
<Recipients>
<Recipient>201006930543</Recipient>
</Recipients>
</Message>
</Messages>
</root>

Page 10 of 15
Document Version1.0
4. SMPP Interface Specifications
Deewan AlRasaile offers SMPP version 3.4 interface. Accordingly, when using the SMPP interface the
connection between your application and Deewan AlRasaile will be through SMPP version 3.4.

 The default data coding data_coding = 0 for GSM 03.38 data coding
 data_coding = 8 for UCS-2 data coding
 maximum number of characters per message for data_coding = 0 is 160 character
 maximum number of characters per message for data_coding = 8 is 70 character
Send Long Messages:
Client can use one of the following options:

 Client send message partitioning with UDH included for each part, UDHI should be set in
esm_class
 Client send message partitioning with sar_msg_ref_num, sar_total_segments,
sar_segment_seqnum TLV parameters set for each part
Client send message without partitioning using message_payload TLV parameter and Deewan AlRasaile will
handle message partitioning for you (used with Deewan AlRasaile managed)

Parameter Description
Username Provided for each client
Password Provided for each client
IP address SMSC SMPP interface IP (smpp.kh.deewan.sa) or (smpp.ruh.deewan.sa)
Port A port from the set of available ports will be provided to the client
Session Type Transmitter, Receiver, or Transceiver

Number of Sessions:
Deewan AlRasaile provide each SMPP client account with a number or a maximum of sessions in which the
client could connect to simultaneously to ease the messages transmission process.

Session Binding Types:

Client could bind to Deewan AlRasaile interface through Transmitter, Receiver, or Transceiver. In order to
receive delivery reports you must bind Receiver or Transceiver.

PDUs Supported:
bind_transmitter, bind_reciever, bind_transciever, unbind, submit_sm, enquire_link

Page 11 of 15
Document Version1.0
 Commend Response Description
ENQUIRE_LINK ENQUIRE_LINK_RESP To keep session alive
SUBMIT_SM SUBMIT_SM_RESP Submit response
BIND_TRANSCEIVER BIND_TRANSCEIVER_RESP Binding transceiver response
BIND_TRANSMITTER BIND_TRANSMITTER_RESP Binding transmitter response
BIND_RECEIVER BIND_RECEIVER_RESP Binding receiver response
UNBIND UNBIND_RESP Unbinding response

Submit Response:
As to confirm receiving ,the messages from our clients our gateway sends submit response confirmation
message for the client application once message is received.
DLR Support:
Client will receive delivery report only if your route provider supports delivery reports .If provider supports
delivery report ,reports will be sent to you equal the sent messages .In order to be able to receive the reports
you should set registered_delivery value to 1 for each SUBMET_SM PDU and either bind with Receiver or
Transceiver session.
DLR Format:
Deewan AlRasaile provide the delivery report to the client with the below format:
id:{message_id} sub:001 dlvrd:001 submit date:{date} done date:{date}
err:{error_code} text:{msg}
DLR TLV parameters:
Deewan AlRasaile provides the delivery report to the client with TLV

 parameters receipted_message_id
 message_state

Page 12 of 15
Document Version1.0
5. API Interface:

Sign In:
To sign-in using the Sign-In API, first submit an HTTP Request with your username and API Key, then
receive a Response that includes your access-token, which you will then provide in the authorization
header of each Deewan AlRasaile API request you need to submit.
https://api.deewan.sa:8445/deewan/api/v1/signin

BODY PARAMS:

 apiKeystring
 userNamestring
 using your APIKEY, you can generate your access token.

Messaging:

 Launch your mobile marketing campaign using our Messaging API Services. Send
advertisements as SMS messages to your customers or send an SMS notification to one of
your customers for a certain purpose.
 First, use the Send Single or Bulk SMS API to send your message, or send an SMS to a
predefined group of recipients using the Send SMS to Groups API, then use the returned SMS
ID to track and view the sent message details by calling the Get Message Details by ID API.
 After sending a sum of messages, you can track the messages you sent during a certain period
by calling Get Messages Details Within Date Range API. You may also want to learn the count
of these messages through the Get Sent Messages Count API.

Send Messages:

 Through Deewan AlRasaile Send Single or Bulk SMS API, you can send a message to multiple
recipients or to a single recipient.
 When you send SMS messages using this API, the API will return to you the sent messages’
ID to track them later using Deewan AlRasaile Get Message Details by ID API.
 Using Deewan AlRasaile Send Single or Bulk SMS API is quite simple. First, submit an HTTP
Request with the message text and other important parameters, and then receive a Response
that includes the SMS ID.
https://api.deewan.sa:8445/deewan/api/v1/messaging

Page 13 of 15
Document Version1.0
BODY PARAMS:

Parameter Type Description

messageTexT string The message content that you want to send.
senderName string The name of the message sender.
messageType string Message type either text or Unicode Can be text or Unicode
recipients string The intended recipients’ phone numbers
clientMessageId int32 An integer used as an identifier for your request to track it.
acknowledgement int32 An integer to specify if you need an acknowledgement response or not.
Its possible values are 0 or 1
deliveryTime string A string that includes the desired delivery time of the SMS.
ityPeriod string A string that returns the desired validity period of the SMS.
ip string A string to define the ip address.
dlrUrl string A string to define the URL to which you would like to send the delivery
receipts (DLR).
dateStamp string A string to define the date stamp of the SMS.
udh string A string to define the UDH of the SMS.
dataCoding string A string to define the data coding scheme of the SMS.
flashing int32 An integer to state if you the SMS to be a flash SMS or not. Its possible
values are 0 or 1.
optimizeSMS int32 Values [0/1], To Enable/Disable optimizing your SMS If you are MES
Account.
mergeSMS int32 Values [0/1], To Enable/Disable merging campaigns to your SMS If you
are MES Account.

Get account balance :

Through Get Your Current Balance API, you can directly retrieve your current Deewan AlRasaile
account balance. You can also get the current balance of your sub-accounts, along with their details,
in case your account is a master account. Using Deewan AlRasaile Get Your Current Balance API is
quite simple. First, submit an HTTP Request to the API’s designated URL, and then receive a
Response that includes your account balance details.
https://api.deewan.sa:8445/deewan/api/v1/accounts/balance
Strengthen the security of your applications by integrating Deewan AlRasaile Verify Services. This
offers you the Two-Factor Authentication technology to be able to verify the phone numbers of your
apps’ users. You can send passcodes to your users’ phone numbers via SMS messages. Once your
users verify the passcode sent to them, you can check this code and validate that this is a trusted
user.

Page 14 of 15
Document Version1.0
Send Message
Send an SMS with a verification passcode of six digits to your user’s phone number, so as to
verify your user identity, and that the given phone number is valid.
https://api.deewan.sa:8445/deewan/api/v1/destinations/verification

Validate Message
Compares the received passcode from your user with the check code returned from the Verify
Phone Number API. If the codes match, then the passcode is validated, and the user’s phone
number is successfully verified.

Get Message Status

After your user’s phone number is verified, you can check on the passcode you have received
from the user to know its status, whether it is expired, validated, or invalid. Get Passcode
Status API takes the check code returned from the Verification: Send Message API, and
returns the status of the related passcode

Page 15 of 15
Document Version1.0