SMS API Technical Document V1.3
SMS API Technical Document V1.3
1
Table of Contents
I. Revision History..................................................................................................................... 3
II. Purpose of this document ...................................................................................................... 4
III. Glossary of Terms & Abbreviations......................................................................................... 4
IV. Methods provided by “Community” :...................................................................................... 5
1. SendSMS: .......................................................................................................................... 5
2. SendSMSWithDLR: ............................................................................................................ 8
3. SendSMSWithValidity: ..................................................................................................... 11
4. SendToMany: (API only) .................................................................................................. 14
5. SendOfflineSMS: ............................................................................................................. 16
6. SendSMSWithTemplate: (Web service only) .................................................................... 19
7. CheckCredit: .................................................................................................................... 21
8. CheckDLRStatus: (API only) .............................................................................................. 23
V. Methods to be provided by Client: ....................................................................................... 25
1. ReceiveDLR: (API) ........................................................................................................... 25
VI. All Code Values: ................................................................................................................... 27
pg. 2
I. Revision History
pg. 3
II. Purpose of this document
• This document demonstrates how to use web services and APIs that provided by
“Community” to send SMSs by client from his purchased quota and check his
credit.
• “Community” provides the following list of web services:
o SendSMS
o SendSMSWithDLR
o SendSMSWithValidity
o SendOfflineSMS
o SendSMSWithTemplate
o CheckCredit
• “Community” provides the following list of APIs:
o SendSMS
o SendSMSWithDLR
o CheckDLRStatus
o SendSMSWithValidity
o SendToMany
o SendOfflineSMS
o CheckCredit
o GetDLRResponseStatus
• The provided web services use SOAP protocol, and the client can request and respond
the data through it using XML format.
• Provided APIs use REST protocol, and client can request and respond data through it
using JSON format.
• The URLs of the Web services accepts POST and GET methods, but the URLs of the APIs
use POST method only.
• Client can define list of IPs as White Listed IPs for their account, and SMSs will be sent
by that account through the defined White List IPs only.
• Client can define list of dials as Black Listed Dials for their account, and that account
will be eligible to send SMSs to any dial except the defined Black List Dials.
III. Glossary of Terms & Abbreviations
Term Definition
Client Refers to The entity which has account at “Community” SMS platform
SMS Quota The SMS count which available for the client to send using his account
DLR Delivery reporting is a feature that reports back SMS message delivery status
pg. 4
IV. Methods provided by “Community” :
1. SendSMS:
This method used to send SMSs only (without DLR – Without validity).
Request Parameters:
Parameter Description Data Type
• User name provided by “Community”
UserName* String
for the sender account
• Password provided by “Community”
Password* String
for the sender account
SMSText* • The text of the message String
• SMS language
o “E” for English
SMSLang* String
o “A” for Arabic
SMSSender* • The SMS fake sender String
pg. 5
• Web service complete URL
https://app.community-ads.com/SendSMSService/SMSSender.asmx?op=SendSMS
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<SendSMSxmlns="http://tempuri.org/">
<UserName>username</UserName>
<Password>123456</Password>
<SMSText>Test</SMSText>
<SMSLang>e</SMSLang>
<SMSSender>SMS Sender</SMSSender>
<SMSReceiver>01142220154</SMSReceiver>
<SMSID>0f6103e8-fd9a-4b53-00a3-f8fda400aa3a</SMSID>
</SendSMS>
</soap12:Body>
</soap12:Envelope>
pg. 6
• Request Values Sample (JSON)
{
"UserName": "username",
"Password": "123456",
"SMSText": "Test",
"SMSLang": "e",
"SMSSender": "SMS Sender",
"SMSReceiver": "201542220154",
"SMSID": "b0a3a0de-3748-4308-1f93-b6ce1a3a8108"
}
pg. 7
2. SendSMSWithDLR:
This method used to send SMSs with the DLR report.
Request Parameters:
pg. 8
• Request Values Sample (XML
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<SendSMSWithDLR xmlns="http://tempuri.org/">
<UserName>username</UserName>
<Password>123456</Password>
<SMSText>Test</SMSText>
<SMSLang>e</SMSLang>
<SMSSender>SMS Sender</SMSSender>
<SMSReceiver>01142220154</SMSReceiver>
<SMSID>0f6103e8-fd9a-4b53-00a3-f8fda400aa3a</SMSID>
<DLRURL>http://hostname/applicationname/receiveDLR/DLRStatus</DLRURL>
</SendSMSWithDLR>
</soap12:Body>
</soap12:Envelope>
pg. 9
Return Values Sample (XML)
{
"UserName":"username",
"Password":"123456",
"SMSText":"Test",
"SMSLang":"a",
"SMSSender":"SMS Sender",
"SMSReceiver":"201542220154",
"SMSID":"b0a3a0de-3748-4308-1f93-b6ce1a3a8108",
"DLRURL":"http://hostname/applicationname/receiveDLR/DLRStatus"
}
pg. 10
3. SendSMSWithValidity:
This method used to send SMS with the feature of sending schedule/on spot, and
retrying to send the failed messages.
Request Parameters:
pg. 11
• In case of the defined time ended
without sending the message, the
message sending status will be “Failed”.
• If the client didn’t enter the validity value,
the system will use the value that set
before in his account information on
“Community” SMS platform
o If the system didn’t find it, it will use
the default value which is 3 minutes
In while StartTime • Time to start sending SMS (Optional) String
• If the client didn’t enter it, the system will
send the SMS on spot
• Web service complete URL:
https://app.community-ads.com/SendSMSService/SMSSender.asmx?op=SendSMSWithValidity
• Request Values Sample (XML)
pg. 12
• Return Values Sample (XML)
{
"UserName":"username",
"Password":"123456",
"SMSText":"Test",
"SMSLang" :"e",
"SMSSender":"SMS Sender",
"SMSReceiver":"201542220154",
"SMSID":"b0a3a0de-3748-4308-1f93-b6ce1a3a8108",
"Validity":"4",
"StartTime": "15/09/2019 16:48:00"
}
• Return Values Sample(JSON)
0
pg. 13
4. SendToMany: (API only)
This method used to send SMSs to several dials.
Request Parameters:
pg. 14
Validity • The period in minutes which the system String
keeps retrying to send the failed messages
(Optional)
• In case of the defined time ended without
sending the message, the message sending
status will be “Failed”.
• If the client didn’t enter the validity value,
the system will use the value that set
before in his account information on
“Community” SMS platform
o If the system didn’t find it, it will use the
default value which is 3 minutes
• API complete URL
https://app.community-ads.com/SendSMSAPI/api/SMSSender/SendToMany
• Request Values Sample (JSON)
{
"UserName":"username",
"Password":"123456789",
"SMSText":"Test",
"SMSLang" :"e",
"SMSSender":"SMS Sender",
"Anis": ["01024875436,5f50f470-3295-4e35-9005-
2f54a0fd7449","01024875437,5f50f470-3295-4e35-9005-
2f54a0fd7459","01024875438,5f50f470-3295-4e35-9005-2f54a0fd7849"],
"Validity":"4",
"WithDLR":"true"
}
0
Status code Integer represents the service response code
pg. 15
5. SendOfflineSMS:
This method used to receive SMS from the client and send it offline by “Community”
for better sending performance.
Request Parameters:
pg. 16
Validity • The period in minutes which the system keeps
retrying to send the failed messages (Optional)
• In case of the defined time ended without
sending the message, the message sending
status will be “Failed”.
String
• If the client didn’t enter the validity value, the
system will use the value that set before in his
account information on “COMMUNITY” SMS
platform
o If the system didn’t find it, it will use the
default value which is 3 minutes
• Web service complete URL:
https://app.community-ads.com/SendSMSService/SMSSender.asmx?op=SendOfflineSMS
• Request Values Sample (XML)
pg. 17
• Return Values Sample (XML)
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<SendOfflineSMSResponse xmlns="http://tempuri.org/">
<SendOfflineSMSResult>0</SendOfflineSMSResult>
</SendOfflineSMSResponse>
</soap12:Body>
{
"UserName":"username",
"Password":"123456",
"SMSText":"Test",
"SMSLang":"e",
"SMSSender":"SMS Sender",
"SMSReceiver":"01234626128",
"SMSId":"0f6103e8-fd9a-4b53-00a3-f8fda400aa3a",
"CampaignID": "1213af",
"WithDLR": "True",
"Validity":"4"
}
Request Parameters:
pg. 19
• In case of the client enters a key not
included in the “Items” parameter, the
SMS will be rejected
Items* • The place holder’s value aligned with its String
key which used in the text of the
parameter “template”
• It could be one place holder or more
• Web service complete URL :
https://app.community-ads.com/SendSMSService/SMSSender.asmx?op=SendSMSWithTemplate
Request Values Sample (XML)
pg. 20
• Return Values Sample (XML)
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<SendSMSWithTemplateResponse xmlns="http://tempuri.org/">
<SendSMSWithTemplateResult>0</SendSMSResult>
</SendSMSWithTemplateResponse>
</soap12:Body>
7. CheckCredit:
This method used to check client’s SMS quota on the system.
Request Parameters:
pg. 21
• Web service complete URL
https://app.community-ads.com/CheckCreditService/CheckCreditService.asmx
• Request Values Sample (XML)
pg. 22
• API complete URL:
https://app.community-ads.com/CheckCreditApi/api/CheckCredit
• Request Values Sample (JSON)
{
"UserName":"username",
"Password":"123456"
}
-1
pg. 23
{
"UserName":"username",
"Password":"123456",
"UserSMSId":"00000000-0000-0000-0000-000000000000"
}
pg. 24
V. Methods to be provided by Client:
1. ReceiveDLR: (API)
• This method must be created by the client to receive the DLR status in case
of using the SendSMSWithDLR method and the account has the privilege to
receive DLR.
• The client provides “Community” with URL to receive the DLR status
parameters values (This URL may be the URL that added when the client’s
account created on “Community” SMS platform, or the system will use the
URL which added by client while using SendSMSWithDLR method)
pg. 25
• The RecieveDLR will be called with the following format with Get verb over
HTTP(s): [Client Receive DLR Status
URL]?userSMSId={0}&dlrResponseStatus={1}
• In case of the client needs to add more parameters to the mentioned
parameters of this API, he shall provide “Community” with it.
• Client can get the DLR full report through his account on the reseller
reporting tool.
Request Parameters:
pg. 26
• Request Values Sample
{
"userSMSId"= "5f50f470-3295-4e35-9005-2f54a0fd7459",
"dlrResponseStatus" = "1"
}
-3 Invalid ANI Black List Common SMS sent to black listed dial
of the sender’s account
-14 SMS Sending Failed Try Common While sending SMS an error
Again occurs and SMS not sent
-16 User Can Not Send With DLR SendSMSWithDLR, This account doesn’t have the
SendOfflineSMS send with DLR option.
pg. 28
-32 InvalidSMSTemplateOrItems SendSMSWithTemplate In case of the client enters a
key not included in the
“Items” parameter
pg. 29
1 DeliveredToPhone GetDLRResponseStatus, • In case
CheckCredit “GetDLRResponseStatus”
methods, it means SMS
delivered successfully
• In case of “CheckCredit”
method, it means client
quota is 1 SMS
pg. 30
N Client Quota CheckCredit Positive number describe
number of available SMS
credit for client to send
pg. 31