Web2sms API Guide
& Frequent Questions
JAN 2017
Web2sms - API User
Guide
JAN 2017/ Version 1.0.0
Web2sms API - User Guide
Table of Contents:
1. Document Purpose
2. Introduction
3. Technical Scope
3.1.Scenario Overview
3.2.Service Activation
3.3.SMS API Request
3.3.1.SMS API Request Structure
3.3.2.Generating Secure Hash
3.4.SMS API Response
3
Web2sms API - User Guide
1. Document Purpose
This document describes how to use SMS API to send SMSs.
2. Introduction
SMS API is part of the Web2SMS solution. SMS API provides a restful web service
interface over HTTPS that allows third party applications to send individual SMSs
directly without using Web2SMS UI portal.
4
Web2sms API - User Guide
• 3. Technical Scope
This document describes how to use SMS API to send SMSs.
3.1. Scenario Overview
-SMS API provides a post restful web service interface over HTTPS. Customers can send up to
1000 SMSs1 per request, the activation process go through Customer Care agent. After
activation customer will retrieve Secure Hash Secret Key to generate required parameter “Secure
Hash” using the SHA-256 algorithm (one-way hashing algorithm).
- SMS API customers' profile will contain the fixed IP(s) “trusted IP(s)” of each customer.
The Web2SMS service will assure the request is coming from one of trusted IPs and then extract the
request parameters and compare the user included as a parameter in the request with the user
corresponding to this IP. Web2SMS then will calculate the Secure Hash using the proper key
assigned to that customer and compare it with the secure hash sent in request. If the two hashes
are similar then the request will be processed and the SMS will be sent to the receiver.
-SMS API supports SSLv3, TLSv1 and TLSv1.1 so customers should acquire a certificate first to use
an HTTPs requests.
5
Web2sms API - User Guide
Note: Secure Hash Secret Key by the application, those hashing keys will be kept encrypted in the Web2SMS-DB.
3.2. Service Activation
• Customer can activate SMS API service via Customer care agent, after providing the agent with
service password and list of trusted IPs.
• In response Customer care agent will provide customer the Secure Hash Secret Key that used to
generate secure hash parameter.
• Also Customer can change SMS API password, regenerate Secure Hash Secret Key or edit list of
trusted IPs.
6
Web2sms API - User Guide
3.3. SMS API Request
3.3.1. SMS API Request Structure
Submit SMS API Request is an XML based request using following URL:
https://e3len.vodafone.com.eg/web2sms/sms/submit/
With following parameter:
No. Parameter Type Description
1 AccountId String ID of the account
2 Password String Password of the account
3 SecureHash Hexadecimal SHA-256 HMAC generated from hashed parameters
4 SMSList Complex SMS details element contain SenderName, RecevierMSISDN and SMSText
4.1 SenderName Alphanumeric Must be one of pre-assigned senders
4.2 ReceiverMSISDN Numeric The receiver MSISDN of SMS
4.3 SMSText String The body of SMS
7
Web2sms API - User Guide
Sample Submit SMS request:
<?xml version="1.0" encoding="UTF-8"?>
<SubmitSMSRequest xmlns:="http://www.edafa.com/web2sms/sms/model/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xsi:schemaLocation="http://www.edafa.com/web2sms/sms/model/ SMSAPI.xsd " xsi:type="SubmitSMSRequest">
<AccountId>1</AccountId>
<Password>password</Password>
<SecureHash>3916459ABA74BEC42E3E6E76E7387D8658DC01C5096C6C2743F1FE4F04962DB9</SecureHash>
<SMSList>
<SenderName>test</SenderName>
<ReceiverMSISDN>010123456789</ReceiverMSISDN>
<SMSText>Test SMS.</SMSText>
</SMSList>
</SubmitSMSRequest>
8
Web2sms API - User Guide
3.3.2. Generating Secure Hash
The Secure Hash is a hexadecimal encoded SHA-256 HMAC of a concatenation of user
defined parameters. The concatenation of parameters takes the form of a list of name-
value pairs, similar to the parameter string for an HTTP GET call.
The SHA-256 HMAC is calculated as follows:
1. The SHA-256 HMAC calculation includes all request fields parameters. The field names
are listed in same order of previous table.
2. Complex element isn't included only its attributes
9
Web2sms API - User Guide
3. Construct a string by concatenating the string form of the field name - value pairs.
The string form of a name-value pair is the name followed by the value.
– The field name and the value in each field name-value pair are joined using "=" as the separator.
– The resulting joined field name-value pairs are themselves joined using "&" as the separator.
4. Create a SHA-256 HMAC of the resultant string using the hex decoded value of your
client secret as the key. The SHA-256 HMAC algorithm is defined in Federal Information Processing
Standard 180-2. We strongly recommend that you use one of the numerous implementations
available in most programming languages.
Note: It is critical that you use the hex decoded value of the secret as the key. For example, in PHP you can use the pack
('H*',SecureSecret) function. In C# you will need to create and parse a byte array as demonstrated in the example code.
10
Web2sms API - User Guide
5. Encode the HMAC in hexadecimal, and include it in the request as the value for the
SecureHash field.
For example, if your client secret is: FD92A200F4A9EBCB4896177CA2760DD3
and the Hashing input parameters are:
No. Parameter Value Type Description
1 AccountId 10100111 String ID of the account
2 Password password String Password of the account
3 SenderName Sender1 Alphanumeric Must be one of preassigned senders
4 ReceiverMSISDN 010123456789 Numeric The receiver MSISDN of SMS
6 SMSText Test SMS From SMS API. String The body of SMS
11
Web2sms API - User Guide
Then the concatenated value that should be used as an input to the hash function should be as
follows:
AccountId=10100111&Password=password&SenderName=Sender1&ReceiverMSISDN=010123456789&SMSText=Test SMS From SMS
API.
Note: The last character of each field value (except the last) is followed directly by "&". The concatenated value must be
represented in the UTF-8 character encoding format.
The following Secure Hash is a valid SHA256 result to use for the provided parameters above,
using the above client shared secret
3916459ABA74BEC42E3E6E76E7387D8658DC01C5096C6C2743F1FE4F04962DB9
12
Web2sms API - User Guide
if more than one SMSList sent, the input to the hash function should reserve the should be as follows:
AccountId=10100111&Password=password&SenderName=Sender1&ReceiverMSISDN=010123456789&SMSText=Test1&SenderNam
e=Sender2&ReceiverMSISDN=010xxxxxxxxx&SMSText=Test 2
Note: first object in SMSList must must represent first in input string
here are some XML requests and their input string to hash function:
<?xml version="1.0" encoding="UTF-8"?> <SubmitSMSRequest xmlns:="http://www.edafa.com/web2sms/sms/model/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.edafa.com/web2sms/sms/model/
SMSAPI.xsd " xsi:type="SubmitSMSRequest">
13
Web2sms API - User Guide
<AccountId>1</AccountId>
<Password>password</Password>
<SecureHash>E3FE1AE213A76D74F99FA7854799161E15FAA3F1310ED7947874932FE05EC801</SecureHash>
<SMSList>
<SenderName>test1</SenderName>
<ReceiverMSISDN>010123456789</ReceiverMSISDN>
<SMSText>SMS1</SMSText>
</SMSList>
<SMSList>
<SenderName>test2</SenderName>
<ReceiverMSISDN>010123456789</ReceiverMSISDN>
<SMSText>SMS2</SMSText>
</SMSList>
<SMSList>
<SenderName>test3</SenderName>
<ReceiverMSISDN>010123456789</ReceiverMSISDN>
<SMSText>SMS3</SMSText>
</SMSList>
</SubmitSMSRequest>
14
Web2sms API - User Guide
AccountId=1&Password=password&SenderName=test1&ReceiverMSISDN=010123456789&SMSText=SMS1&SenderName=test2
&ReceiverMSISDN=010123456789&SMSText=SMS2&SenderName=test3&ReceiverMSISDN=010123456789&SMSText=SMS3
<?xml version="1.0" encoding="UTF-8"?> <SubmitSMSRequest xmlns:="http://www.edafa.com/web2sms/sms/model/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.edafa.com/web2sms/sms/model/
SMSAPI.xsd " xsi:type="SubmitSMSRequest"> <AccountId>1</AccountId> <Password>password</Password>
<SecureHash>3A29A0F611FCD47F86ACE1091690EEA403F4AEB51F87EE287D0326893B1ABA92</SecureHash> <SMSList>
<SenderName>Sender2</SenderName> <ReceiverMSISDN>010123456789</ReceiverMSISDN> <SMSText>SMS2</SMSText>
</SMSList> <SMSList> <SenderName>Sender</SenderName> <ReceiverMSISDN>010123456789</ReceiverMSISDN>
<SMSText>SMS</SMSText> </SMSList> </SubmitSMSRequest>
15
Web2sms API - User Guide
AccountId=1&Password=password&SenderName=Sender2&ReceiverMSISDN=010123456789&SMSText=SMS2&SenderName=S
ender&ReceiverMSISDN=010123456789&SMSText=SMS
3.4. SMS API Response
Submit SMS API Response is an XML based request with following parameter:
No. Parameter Value Description
SUBMITTED SMS Submitted to SMSC
1 SMSStatus FAILED_TO_SUBMIT SMS Failed to Submit to SMSC
TIMMED_OUT SMS Time-out during submit to SMSC
SUCCESS Request Success
INVALID_REQUEST Request has invalid parameter check description for more details
2 ResultStatus
INTERNAL_SERVER_ERROR System failed to handle request
GENERIC_ERROR General errors happens to the system
3 Description String Details description for errors
16
Frequent Questions
17
Hashing Section
18
Web2sms API - Points should be considered
• Hash Key Should be as capital characters not in a lower case.
• Hash key can be validated through website http://www.freeformatter.com/hmac-
generator.html#ad-output
• Hashing samples & Guidelines are attached as we can’t provide customer with hash
keys.
19
XML Section
20
Web2sms API - Points Should be considered
• All XML values shouldn’t include any Space before or after the value.
• Whole XML body should be sent as one single string.
• Sender name should not be created with space before or after the word.
• The content-type filed in the header should be “application/xml” instead of
“text/xml”.
• Timestamp for the trial should be provided while Asking the customer to send XML
request/response.
21
Web2sms API - XML Points should be considered
• UTF-8 should be used for Encoding the Arabic characters.
• Special characters adding (such as ‘>’, ‘&’, …etc) , then you should use the equivalent
representation in XML syntax , please refer to link
http://www.w3schools.com/xml/xml_syntax.asp
http://xml.silmaril.ie/specials.html
http://stackoverflow.com/questions/10917555/adding-a-new-line-break-tag-in-xml
• International recipients format should start with 00 or + followed by the country code.
• API response samples is attached.
22
Security Section
23
Web2sms API - Points should be considered
• Using Client certificate is not mandatory to be used. it depending on customer’s
sending.
• Client certificate is attached Note: please change file extension from .txt to .cer
• Security measures while sending SMS.
HTTPS
User name and password authentication
SSO with cloud portal
Source IPs whitelisting
Generating random hashed value for each SMS request; the hashing should be done using the SHA-256
algorithm (one-way hashing algorithm).
24
Supported Languages Section
25
Web2sms API - Supported Languages Points should be
considered
• Java or PHP, Ruby languages are supported to be used on web2sms API.
• Java version is not affecting sending requests ,The integration with API is through
HTTPs requests.
• SOAP-UI details check site https://www.soapui.org/
26
Mechanism
27
Web2sms API - Mechanism- Points should be considered
• SMS flow for the bulk messages “Customer > Web2SMS API > VF SMS-C > Recipient”.
• The average time to send the bulk SMS “The overall system throughput is 100
SMS/sec distributed equally among active accounts who are sending
messages/campaigns at the same time”.
• In regards of Delivery report “ SMS delivery reports are asynchronous so the API
response cannot show if the SMS was delivered or not, but in case of a successful API
request the client will get a success response indicating that the messages was
SUBMITTED successfully to the network and is being delivered to the recipient(s), then
the customer can track each SMS delivery status through the reports page on portal.
28
Others
29
Web2sms API - Others
• HTTP Port 443 is the default port used for HTTP.
• To know IP address for his outgoing request use http://whatismyipaddress.com/ to
make sure that IP is the same IP’s we have whitelisted.
• Regarding WSDL we are using restful XML over HTTPS API that has no WSDL.
30
