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.
