HTTP API V3.

0
Integrate our HTTP API tool to be used in your custom
designed system. HTTP API allows you to get a gateway for
bulk SMS messaging, or become a bulk SMS provider.

Copyright © - 2022 1S2U

 Abstract

This document is intended for users/developers who wish to develop applications using the HTTP SMS
Gateway for sending SMS messages. The gateway can be accessed by HTTP/HTTPS API through
submitting values using GET or POST method to the API Server.

ii
 Table of Contents

Abstract ............................................................................................................................. ii

Table of Contents ............................................................................................................... iii

List of Figures ..................................................................................................................... v

List of Tables ..................................................................................................................... vi

1. Introduction ................................................................................................................1

2. Authentication .............................................................................................................2

3. Single Messaging – Interface I ......................................................................................3

4. Message parameters in-detail .......................................................................................5

4.1 Username (username) ............................................................................................... 5

4.2 Password Parameter (password) ................................................................................. 5
4.3 Mobile Number Parameter (mno) ................................................................................ 5
4.4 Message Parameter (msg) .......................................................................................... 6
4.5 Sender Id (Sid) ......................................................................................................... 7
4.6 Flash Message (fl) ..................................................................................................... 7
4.7 Message Type (mt) .................................................................................................... 8
5. SMS Examples – Interface I ..........................................................................................8

5.1 Sending single text message....................................................................................... 8

5.2 Sending to multi numbers .......................................................................................... 9
5.3 Sending single text flash message ............................................................................. 10
5.4 Sending single Arabic/Unicode text message .............................................................. 11
6. Get Credits API .......................................................................................................... 12

7. Conclusion ................................................................................................................ 12

iii
APPENDIX A ..................................................................................................................... 13

iv
 List of Figures

Figure 1: Single Messaging using HTTP API............................................................................ 9

Figure 2: Multi-number messaging using HTTP API............................................................... 10
Figure 3: Single text flash message using HTTP API .............................................................. 11
Figure 4: Single Arabic/Unicode text message using HTTP API ............................................... 12

v
 List of Tables

Table 1: HTTP / HTTP SAPI Parameters................................................................................. 3

Table 2: Response messages from HTTP/ HTTPS API .............................................................. 4
Table 3: HTTP/HTTPS API encoding code format.................................................................... 6
Table 4: HTTP / HTTPS Flash message parameters................................................................. 7
Table 5: HTTP / HTTPS Message type parameters................................................................... 8
Table 6: Get Credits API Parameters ................................................................................... 13
Table 7: Response messages from Get Credits API ............................................................... 13
Table 8: HTTP/HTTPS Gateway error codes from invalid parameters. ..................................... 15
Table 9: API Rate Limit... ................................................................................................... 15

vi
 HTTPHTTP
API API
V3.0V2.0

1. Introduction

HTTP SMS Test Gateway can be used in various ways:

• Using HTTP/HTTPS API will give the ability to submit values by GET method using
COM component in the applications.
• Using Test Web Interface.

The test gateway with HTTP/HTTPS API can be used to send various types of SMS messages.
Including: simple text messages, Unicode messages, ring tones, and operator logos. This document
gives a detailed explanation of using the gateway through HTTP/HTTPS protocol.

NOTE: Accessing gateway through HTTP/HTTPS protocol is one of the best and fastest ways to
deliver SMS messages.

1
 HTTPHTTP
API API
V3.0V2.0

2. Authentication

In order to deliver a message, the gateway needs to authenticate whether the request is coming
from a valid source with valid login details.

This authentication is done using various parameters such as:

• Username: Username of the account.

• Password: Password of the account.

Username and password are provided to the client after registration is made for the HTTP/HTTPS
API option.

2
 HTTPHTTP
API API
V3.0V2.0

3. Single Messaging – Interface I

For sending any type of SMS messages, the gateway requires the message to be sent using
various parameters, including username and password for authentication purposes. All the
parameters need to be sent via HTTP/HTTPS API using the GET method. The number of
parameters required depends upon the type of SMS messages. Table 1 shows the HTTP/HTTPS
API parameters.

Table 1: HTTP / HTTPS API Parameters

Parameter name Parameter value Description

Username it1232 Username of the account

Password Abc9999 Password of the account

Mno 60188xxxxx Destination mobile no.

Msg Welcome to SMS technologies. Message to be sent

Sid Your sender Sender Id/From clause in the SMS message.

Fl 0 Flash message Indicator (0/1)

Message type: Text, Unicode

Mt 0

For sending non-batch SMS messages the following Test Gateway URL needs to be accessed with the
required parameters as shown in the weblink below:

https://api.1s2u.io/bulksms?username=yourusername&password=yourpassword&mno=123456
78900&sid=sender&msg=testdlr&mt=0&fl=0

3
 HTTPHTTP
API API
V3.0V2.0

The customer would get the following response values for sending messages as per described in Table 2.

Table 2: Response messages from HTTP/ HTTPS API

Inputs Return values

Messages sent successfully.

OK: b1a42c47-1a66-4358-bd26-cddf1930e321

Value returned It can be retained for generating CDR reports.

Error Code (See more details about this response in the appendix)
Message not sent.

Note: The response does not have any correlation with specific gateways. The timestamp response
code can be used to compare the CDR reports that are supported by the gateway. More details about
HTTP/HTTPS parameters can be found in the following section.

4
 HTTPHTTP
API API
V3.0V2.0

4. Message parameters in-detail

4.1 Username (username)

The username parameter value is passed for authentication purposes. The username is provided
to the client when registration is made via HTTP/HTTPS API option for sending SMS messages
through our gateway. The username (user) parameter cannot be more than 20 characters long
and can only contain alphabets and numbers with no spaces.

4.2 Password Parameter (password)

The password parameter value is also passed in combination with the username for authentication
purposes. The password is provided to the client along with the username when registration is done
with our website for sending SMS messages through our gateway. The password (pass) parameter
cannot have more than 20 characters, and only can contain alphabets and numbers with no spaces.

4.3 Mobile Number Parameter (mno)

The mobile number parameter refers to the destination mobile number in which the message is
to be sent. However, the mobile number is required to be in a specific format. Any error in this
parameters’ values would lead to non-delivery of the message. The phone number must contain
only digits together with the country code. It should not contain any other symbols such as (+)
sign. Instead of plus sign, please put (00). In addition, the phone number must be valid, and
supported by the Test Gateway (Coverage Area), as shown in this link.

5
 HTTPHTTP
API API
V3.0V2.0

4.4 Message Parameter (msg)

The message parameter refers to the actual message that is to be sent to the destination mobile
number (mno). The behavior of the message parameter differs depending on the type of message
being sent. The message parameter may consist of up to 160 characters belonging to the following set: A…Z,
a…z, 0…9, blank spaces, and Meta characters \ (line feed).

Due to restrictions in the HTTP/HTTPS protocol format, the following special Characters must be
encoded in order not to collide with reserved HTTP/HTTPS characters. Character must be encoded
as described in table 3.

Table 3: HTTP/HTTPS API encoding code format

Character Hexa-decimal Encoded String

& %26

+ %2B

% %25

# %23

= %3D

Enter %0A

For simple text messages, the message can contain numbers, alphabets, spaces and certain
special characters. However, the message can contain a maximum of 160 characters, including
spaces.

• In case of Unicode messaging, the message can contain only numbers in the form
of Unicode digits. Further, it can be a maximum of 69 characters i.e. 69 x 4 Unicode
digits for each character = 276 digits.
• In case of binary messaging, the message can contain only a valid 8-bit data string.
The binary message can be a maximum of 140 characters only (i.e. one SMS).
However, Ring tones, operator logos and Pictures that exceed one SMS can also
be sent in form of concatenated SMS messages.

6
 HTTPHTTP
API API
V3.0V2.0

4.5 Sender Id (Sid)

The sender Id parameter refers to the message dispatcher or from clause (THE SENDER), from
whom the message is sent. The sender ID can either be a valid international number up to sixteen
characters long, or an eleven characters alphanumeric string. The sender ID is an optional clause.

• In case the sender ID is not specified, the SMSC number is sent as the sender ID to
the destination number.
• In case of binary messages, the sender ID is encoded in the 8-bit binary data string,
and hence not required to be sent.
• Sender ID, in case of text messaging, can only be made up to alphabets and digits. It
cannot contain any special characters such as (-, +) etc.

4.6 Flash Message (fl)

Flash message parameter (as shown in Table 4) indicates whether the message will be flashed on
the destination mobile number (mno). It can contain only the values (0 or 1). Default value for this
parameter is 0. When the flash parameter is sent as 1 (fl=1), the SMS message is flashed on the
destination mobile.

Table 4: HTTP/HTTPS Flash message parameters

Value Description

0 Don’t flash message.

1 Flash message on destination mobile screen.

7
 HTTPHTTP
API API
V3.0V2.0

4.7 Message Type (mt)

Message Type is a flag sent to the Test Gateway to identify the type of messages being sent. The
default value of message type is 0, which refers to text message. It is based on this parameter
that the Test Gateway classifies the type of messages being sent and forwarded it accordingly.
The message type parameter can contain any of the following values as shown in Table 5.

Table 5: HTTP/HTTPS Message type parameters

Value Description

0 Simple text message

1 Unicode Message

5. SMS Examples – Interface I

5.1 Sending single text message

The following link shows an example of a message send using the HTTP API. You should see
something like figure 1 in your browser.

Formula:

https://api.1s2u.io/bulksms?username=yourusername&password=yourpassword&mno=123456
78900&sid=sender&msg=testdlr&mt=0&fl=0

Figure 1: Single Messaging using HTTP API

8
 HTTPHTTP
API API
V3.0V2.0

5.2 Sending to multi numbers

You can send to multi numbers with the API by using comma between the mobile numbers
(max 30 number per session). An example of sending multi numbers can be accessed in the
following link. And you should see something like figure 2.

https://api.1s2u.io/bulksms?username=yourusername&password=yourpassword&mno=123456
78900,11222338844,124367888&sid=sender&msg=testdlr&mt=0&fl=0

Note: To avoid spamming messages our system will ignore and remove the duplicates numbers
which sent in the same request per session.

Figure 2: Multi-number messaging using HTTP API

9
 HTTPHTTP
API API
V3.0V2.0

5.3 Sending single text flash message

An example of sending text flash messages can be accessed in the following link. And you
should see something like Figure 3.

Formula:

https://api.1s2u.io/bulksms?username=yourusername&password=yourpassword&mno=123456
78900&sid=sender&msg=testdlr&mt=0&fl=1

Figure 3: Single text flash message using HTTP API

10
 HTTPHTTP
API API
V3.0V2.0

5.4 Sending single Arabic/Unicode text message

An example of sending text flash messages can be accessed in the following link. And you
should see something like Figure 4.

https://api.1s2u.io/bulksms?username=yourusername&password=yourpassword&mno=12345678
900&sid=sender&msg=627062D00200641064A0020062E062F06450629002006310633062706260
64400200627064406%20470627062%20A06410020062706&mt=1&fl=0

Figure 4: Single Arabic/Unicode text message using HTTP API

11
 HTTPHTTP
API API
V3.0V2.0

6. Get Credits API

Check your credits balance through Get Credits API. Customize and integrate all your website's

monetary analysis into your system simply by forwarding your username and password parameter to

the API. For example:

https://api.1s2u.io/checkbalance?user=yourusername&pass=yourpassword

Parameters:

Table 6: Get Credits API Parameters

Parameters Value Description

USER User Your account username

PASS
Pass Your account password

Response Code:

Table 7: Response code from Get Credits API

Return values
00 Invalid username or password

0 or remaining balance

Note: You can check your balance 2 time in each 1 m , calling the API in higher speed
will block your request and server error will be rise.

7. Conclusion

Accessing gateway through HTTP/HTTPS protocol is one of the best and fastest ways to deliver SMS
messages. Using our services, you will guarantee the reach of bulk SMS messages to all around the
world as mentioned in the Coverage Area

12
 HTTPHTTP
API API
V3.0V2.0

Feel free to contact us at any time, we will be very happy to serve you

APPENDIX A

Error Codes

Table 6 shows the Possible values for status_code are:

Table 8: HTTP/HTTPS Gateway Status codes

Error Code Description
0000 Service Not Available or Down Temporary
OK: b1a42c47-1a66-4358-bd26-
cddf1930e321 Message sent successfully.
0005 Invalid server
0010 Username not provided.
0011 Password not provided.
00 Invalid username/password.
0020 / 0 Insufficient Credits
0030 Invalid Sender ID
0040 Mobile number not provided.
0041 Invalid mobile number.
0042 Network not supported.
0050 Invalid message.
0060 Invalid quantity specified.
0066 Network not supported

NOTE: Only the above-defined validations are performed at the server side. All other validations for
any parameter are required to be handled at the client side explicitly. For example: The mobile
number is not validated at the sever end for containing any characters other than numbers or for not
being in the international format. In case of Unicode messaging, if the value of message type
parameter (mt) is sent as 0 instead of 1, then the message would be sent as simple text message
and not Unicode, since no such validation is performed at the server end.

13
 HTTPHTTP
API API
V3.0V2.0

Table 9: API Rate Limit

To protect the platform from being overloaded 1s2u API applies rate limits for its SMS API. The default
request rate limit is 30 requests per second per username. ( can be adjusted upon request ) with a
special API endpoint, and can reach up to 150 requests ( Custom Plan ) per second per IP address The
API will reject all requests exceeding this rate limit with 429 Too Many Requests HTTP Status. You can
retry the request after 1 second.

14