New API

Version

Date

Description

Author

0.1

2014-12-25

First version

Nate

0.2

2015-1-22

Added user_id in

Nate

send_sms request
0.3

2015-3-20

Added DELIVERED

Nate

status in Send Sms

Result
0.4

2015-4-24

1. Changed Send
Sms request
format, each
number could
include a user_id
2. Added an API for
query current
SMS in the
waiting queue.
3. Added a
parameter user_id
in Query SMS
result

Nate

Content
1 Introduction .................................................................................................................................... 6
1.1 Scenarios .............................................................................................................................. 6
1.2 Network Topology............................................................................................................. 6
1.3 Features................................................................................................................................. 6
1.4 Basic Description ............................................................................................................... 7
1.5 Enable API ............................................................................................................................ 7
2. Send SMS ........................................................................................................................................ 8
2.1 Request ................................................................................................................................. 8
2.2Request Parameters ........................................................................................................... 8
2.3 Response Parameter ......................................................................................................... 9
2.4 Example................................................................................................................................. 9
3. Query Send SMS Result ............................................................................................................. 9
3.1 Request ................................................................................................................................. 9
3.2 Request Parameter .......................................................................................................... 10
3.3 Response Parameter ....................................................................................................... 10
3.4 Example............................................................................................................................... 11
4. Query SMS delivery status...................................................................................................... 12
4.1 Request ............................................................................................................................... 12
4.2 Request Parameter .......................................................................................................... 12
4.3 Response Parameter ....................................................................................................... 13
4.4 Example............................................................................................................................... 13

5. SMS in the queue ....................................................................................................................... 14

5.1 Request ............................................................................................................................... 14
5.2 Request Parameter None.............................................................................................. 14
5.3 Response Parameter ....................................................................................................... 14
5.4 Example............................................................................................................................... 14
6. Receive SMS ................................................................................................................................. 15
6.1 Request ............................................................................................................................... 15
6.2 Request Parameter .......................................................................................................... 15
6.3 Response Parameter ....................................................................................................... 15
6.4 Example............................................................................................................................... 16
7 Send USSD ..................................................................................................................................... 16
7.1 Request ............................................................................................................................... 16
7.2 Request Parameter .......................................................................................................... 16
7.3 Response Parameter ....................................................................................................... 17
7.6 Example............................................................................................................................... 18
8. Receive USSD reply.................................................................................................................... 18
8.1 Request ............................................................................................................................... 18
8.2 Request Parameter .......................................................................................................... 18
8.3 Response Parameter ....................................................................................................... 18
8.4 Example............................................................................................................................... 19
9. Stop SMS Task ............................................................................................................................. 19
9.1 Request ............................................................................................................................... 19

9.2 Request Parameter .......................................................................................................... 19

9.3 Response Parameter ....................................................................................................... 20
9.4 Example............................................................................................................................... 20
10. Get Information of Device .................................................................................................... 20
10.1 Request ............................................................................................................................. 20
10.2 Request Parameter ....................................................................................................... 20
10.3 Response Parameter .................................................................................................... 21
10.4 Example ............................................................................................................................ 22
11. Suggestion for sending SMS ........................................................................................ 22

1 Introduction
1.1 Scenarios
1. A SMS server manages a lot of gateway through API. People can send and
receive SMS through this Server.
2. A lightweight SMS Client communicates with gateway through API. People can
use this application to send and receive SMS.

1.2 Network Topology

1.3 Features

SMS and USSD

Batch SMS

SMS delivery status

Basic Information of Device

1.4 Basic Description

We try to make our API as simple as it could be. So we use HTTP for transport and
use json as data format. Both of them are widely used and easy to implement.

1.5 Enable API

Please enable API before your further test. Please select Basic Configuration from
the menu, and select New Version API. The gateway must use version 1102 or later
version.

2. Send SMS
2.1 Request
POST http://gateway_ip/api/send_sms

2.2Request Parameters
Parameter

Type

Description

Required Parameter
text

String

The content of SMS, support grammar like #param#

param

Array

Each element is an Object, which included :

number: a digit string no more than 24 bytes
text_param: an array of string, each element used to
replace #param# in the text
user_id: an integer greater than or equal 0. It is used to
match send sms result.

Optional Parameter
port

Array

Port array for sending.

Each port should be an integer range from 0 to 31.

encoding

String

Could be "unicode" or "gsm-7bit".

Default is "unicode".

2.3 Response Parameter

Parameter

Type

Description

error_code

Integer

Possible code,
202, Request has been accepted, will process later.
400, Request format is not valid.
413, number over 128 or text over 1500 bytes
500, other error

sms_in_queue

Integer

Count of SMS waiting for processed.

task_id

Integer

You can stop this sending task by this ID later.

2.4 Example
Request:
curl -d
'{"text":"#param#","port":[2,3],"param":[{"number":"10086","text_
param":["bj"],"user_id":1},{"number":"10086",
"text_param":["ye"],"user_id":2}]} H "Content-Type:
application/json" http://gateway_ip/api/send_sms
Please note that this example didnt include an username and password.
Please include them in your own code.
Response:
{"error_code":202,"sms_in_queue":2,"task_id":2}

3. Query Send SMS Result

3.1 Request
POST http://gateway_ip/api/query_sms_result

3.2 Request Parameter

Parameter

Type

Description

Optional Parameter
number

Array

A number array, which should not be over 32 numbers.

Each number should not be over 24 bytes.

port

Array

Port array for sending.

Each port should be an integer range from 0 to 31.

time_after

String

String like "YYYY-MM-DD HH:MM:SS"query SMS

record after this time.

time_before

String

String like "YYYY-MM-DD HH:MM:SS"query SMS

record before this time.

user_id

Array

user_id array, which used to match user_id in Send Sms

Request

3.3 Response Parameter

Parameter

Type

Description

error_code

Integer

Possible code,
200, Request has been processed.
400, Request format is not valid.
413, size of number array over 32
500, other error

result

Array

Result ArrayEach element include information below

port: port for sending SMS
number: destination number
user_id: match with the send sms request
time: sending time
status: sending status, which could be,
FAILED
SENDING
SENT_OK
DELIVERED
count: count of sms segment. A long SMS would be
spitted to several segments to send.
succ_count: count of sms segment sent successfully
ref_id: the first reference id of this SMS, which is used
to match SMS delivery status. Reference id is range
from 0 to 255. So it is just a reference id, it is
recommended to match a SMS result and a delivery
status by a combination of port, number and
reference id, even take sending time into account.

3.4 Example
Request

curl -d '{"number":["12341234"], "port":[1,2,3],"user_id":[1,2]}' -H

"Content-Type: application/json"
http://gateway_ip/api/query_sms_result
Response
{"error_code":200"result":[{"port":0,"user_id":1,"number":"12351"
,"time":"2014-12-21 12:06:01","status":"SENT_OK","count":3,
"succ_count":3, "ref_id":12}]}

4. Query SMS delivery status

4.1 Request
POST http://gateway_ip/api/query_sms_deliver_status

4.2 Request Parameter

Parameter

Type

Description

Optional Parameter
number

Array

A number array, which should not be over 32 numbers.

Each number should not be over 24 bytes.

port

Array

Port array for sending.

Each port should be an integer range from 0 to 31.

time_after

String

String like "YYYY-MM-DD HH:MM:SS"query SMS

record after this time.

time_before

String

String like "YYYY-MM-DD HH:MM:SS"query SMS

record before this time.

4.3 Response Parameter

Parameter

Type

Description

error_code

Integer

Possible code,
200, Request has been processed.
400, Request format is not valid.
413, size of number array over 32
500, other error

result

Array

an Array of delivery statuseach element include,

port: port for sending SMS
number: destination number
time: time for sending SMS
ref_id: reference id, used to match SMS send record
status_code: status code is range from 0 to 255,
0, means received by peer,
32 ~ 63, temporary error
64~255, permanent error
For more information about this code, please
search "SMS Status Report"

4.4 Example
Request
curl -d '{"number":["12341234"], "port":[1,2,3],
"time_after":"2014-12-12 19:29:19", "time_before":"2014-12-12

19:29:19"}' -H "Content-Type: application/json"

http://gateway_ip/api/query_sms_deliver_status

Response
{"error_code":200"result":[{"port":0, "number":"12351",
"time":"2014-12-21 12:06:01","ref_id":12, "status_code":0},]}

5. SMS in the queue

5.1 Request
GET http://gateway_ip/api/query_sms_in_queue

5.2 Request Parameter

None
5.3 Response Parameter
Parameter

Type

Description

error_code

Integer

Possible code,
200, Request has been processed.
500: Other error

in_queue

Integer

count of SMS waiting to be sent

5.4 Example
Request
http://gateway_ip/api/query_incoming_sms
Response
{"error_code":200,"in_queue":0}

6. Receive SMS
6.1 Request
GET http://gateway_ip/api/query_incoming_sms

6.2 Request Parameter

Parameter

Type

Description

Optional Parameter
incoming_sms_id

Integer

gateway will return incoming SMS which ID is

greater than this value, default is 0.

flag

String

default is "unread", Optional value is,

"unread", unread SMS, which will change to read
after reading it by this API.
"read",
"all",

read SMS
both of unread and read.

6.3 Response Parameter

Parameter

Type

Description

error_code

Integer

Possible code,
200, Request has been processed.
500: Other error

sms

Array

SMS array, each of them include,

incoming_sms_id: ID in gateways

database

port: port received the SMS

number: number of sender
smsc: number of SMS center
timestamp: receiving time
text: content of the SMS
read

Integer

count of SMS have been read

unread

Integer

count of SMS unread.

6.4 Example
Request
http://gateway_ip/api/query_incoming_sms?flag=all

Response
{"error_code":200, "sms":[{"incoming_sms_id":1, "port":2, "number":
"123456789","smsc":"+8613800123456","timestamp":"2014-12-09
17:11:18","text":"This is a test"},],"read":1, "unread":0}

7 Send USSD
7.1 Request
POST http://gateway_ip/api/send_ussd

7.2 Request Parameter

Parameter

Type

Description

Required Parameter
text

String

content to send, should not be over 60 bytes.

if command is "send", text should not be empty
if command is "cancel", text may be empty.

port

Array

Port array for sending.

Each port should be an integer range from 0 to 31.

Optional Parameter
command

String

could be "send" or "cancel", default is "send"

7.3 Response Parameter

Parameter

Type

Description

error_code

Integer

Possible code,
202, Request has been accepted.
400, lack of text while command is "send" .
500, other error

result

Array

result array, each element include

port, port to send USSD
status, a number could be
200, sent ok
486, busy, for example, sending SMS
503, not available for sending USSD

7.6 Example
Request
curl -d '{"port":[1,2,3],"command":"send","text":"*125#"}' -H
"Content-Type: application/json" http://gateway_ip/api/send_ussd
Response
{"request_id":1, "error_code":202, "result":[{"port":0,
"status":503},{"port":1, "status":503},{"port":2, "status":200}]}

8. Receive USSD reply

8.1 Request
GET http://gateway_ip/api/query_ussd_reply

8.2 Request Parameter

Parameter

Type

Description

Required Parameter
port

Array

Port array for querying USSD reply.

Each port should be an integer range from 0 to 31.

8.3 Response Parameter

Parameter

Type

Description

error_code

Integer

Possible code,
200, Request has been processed.
400, Request format is not valid.

500, other error

reply

Array

reply array, each element include

port: port for receiving USSD reply
text: USSD reply

8.4 Example
Request
http://gateway_ip/api/query_ussd_reply?port=1,2,3

Response
{"error_code":200, "reply":[{"port":1, "text":" "},{"port":2, "text":
"Test"},{"port":3, "text": ""}]}

9. Stop SMS Task

9.1 Request
GET http://gateway_ip/api/stop_sms

9.2 Request Parameter

Parameter

Type

Description

Required Parameter
task_id

Integer

task id, correspond with task_id in the response of send

SMS request.

9.3 Response Parameter

Parameter

Type

Description

error_code

Integer

Possible code,
200, task has bee stop.
404, task not found
500, other error

9.4 Example
Request
http://gateway_ip/api/stop_sms?task_id=1

Response
{"error_code":200}

10. Get Information of Device

10.1 Request
GET http://gateway_ip/api/get_port_info

10.2 Request Parameter

Parameter

Type

Required Parameter

Description

info_type

Array

An array of string, each element cloud be a string as

below,
type, imei, imsi, iccid, number,reg

Optional Parameter
port

Array

Port array for query.

Each port should be an integer range from 0 to 31.

10.3 Response Parameter

Parameter

Type

Description

error_code

Integer

Possible code,
200, Request has been processed.
400, Request format is not valid.
500, other error

info

Array

info array according to the query.

port:
type:

could be GSM, CDMA, WCDMA, or

UNKNOWN when type is not recognized.

imei: IMEI of this port
imsi:

IMSI of the SIM card on this port

iccid: ICCID of the SIM card on this port

number: the mobile number of this SIM card
reg: register state of this port, could be

POWER_OFF
NO_SIM
PIN_REQUIRE
PUK_REQUIRE
UNREGISTER
SEARCHING_NETWORK
REGISTER_OK
UNKNOWN

10.4 Example
Request
http://gateway_ip/api/get_port_info?port=1,2,3&info_type=imei,ims
i,iccid,smsc,type,number,reg

Response
{"error_code":200, "info":[{"port":1,
"type":"WCDMA","imei":"863070017005173","imsi":"","iccid":"","sms
c":"","number":"","reg":"NO_SIM",},{"port":2,
"type":"GSM","imei":"358967042917201","imsi":"460016529802215","i
ccid":"89860114840400428150","smsc":"+8613010868500","number":"",
"reg":"REGISTER_OK",},{"port":3,
"type":"GSM","imei":"358967042917201","imsi":"","iccid":"","smsc"
:"","number":"","reg":"NO_SIM",}]}

11. Suggestion for sending SMS

1.

port parameter is optional in sending SMS request. If you dont need to send

SMS through specific port, this parameter is not necessary.

2.

user_id in sending SMS request is recommened. Its used to match result

with request.
3.

It takes about 5 to 8 seconds to send a SMS. So it is suggest querying result 8

seconds after sending.

4.

If user_id is in the send SMS request, user_id will be included in the SMS result.

5.

SMS delivery status will be received by gateway in unspecific time. It is better

to query delivery status after SENT_OK is returned. For a long SMS, for example,
with a number 123456, ref_id 0, totally sent by 3 parts, the ref_id of each part
will be 0, 1, 2. And at least 3 delivery status will be received, each with ref_id 0, 1 or
6.

curl is an open source software. Please visit http://curl.haxx.se/ for more

information.