SMS HTTP API

Request format:

GET request to HTTP port: http://1.1.1.1:8001/api?username=<username>&password=<password>&ani=<ani>&dnis=<dnis>&message=<message>&command=submit&serviceType=<serviceType>&longMessageMode=<longMessageMode>

GET request to HTTPs port: https://domainname:8002/api?username= <username>&password=<password>&ani=<ani>&dnis=<dnis>&message=<message>&command=submit&serviceType=<serviceType>&longMessageMode=<longMessageMode>

POST request (credentials are part of the link) to HTTP port: curl -H 'Content-Type: application/json' -X POST -d '{"ani":"ani","dnis":"dnis","message":"test"}'

'http://1.1.1.1:8001/api?command=submit&username=username&password=password'

POST request (credentials are a part of the JSON body) to HTTP port: curl -H 'Content-Type: application/json' -X POST -d '{"username":"username","password":"password","command":"submit","ani":"ani","dnis":"dnis","message":"test"}' 'http://1.1.1.1:8001/api?'

NOTE: To send multiple SMS messages, add several comma-separated DNIS to the <dnis> field.

Parameter Value Required
command: Request type. Possible values: “submit”, "query", "mo". To send a message over HTTP, specify command=submit Yes
dnis: Destination number. Must be sent in international E.164 format (up to 15 digits allowed). If the field length exceeds 2048 symbols or 100 numbers, the incoming message will be rejected with the following code: 400 Bad Request (Destination number is too long). Multiple DNIS's cannot be used for longMessageMode=split_or_payload Yes
message: Message text Yes
password: Password Yes
serviceType: Service type, provided by the System owner for the registered interconnection. Can be blank. The maximum length is 9 bytes. Yes
username: login Yes
ani: Caller ID. Technical limitation - alpha-numeric up to 32 symbols. Additional limitations can be caused by destination route peculiarities No
dataCoding

data coding scheme for sending the SMPP to the vendor. Format: integer. Optional. Allowed values are: 0, 1, 3, 6, 7, 8, 10, 14, where:

0: SMSC Default Alphabet (SMPP 3.4)/MC Specific (SMPP 5.0)

1: IA5 (CCITT T.50)/ASCII (ANSI X3.4)

3: Latin 1 (ISO-8859-1)

7: Latin/Hebrew (ISO-8859-8)

6: Cyrillic (ISO-8859-5)<

8: UCS2 (ISO/IEC-10646)<

10: ISO-2022-JP (Music Codes)

14: KS C 5601

 No
esmClass corresponds to the same name parameter in SMPP. Format: integer. Optional. Allowed values are: 0-255 No
flash Flag that indicates a flash message. Possible values are: 0 (regular message) and 1 (flash message that is shown on the screen and is not stored in the device memory). Please note that the flag is merely written to the EDR (Technical details field) and does not change the message data coding. The flag value can be transmitted for MT message sending. The flag can also be changed with the help of translation rules. No
longMessageMode:

Type of long message processing. The following values allowed:

cut (trim message text to 140 bytes) - shortens the message leaving only first 140 bytes to be sent.

split and split_sar - split the message according to the logics described below. The difference between them is in the header to be used, for split it is UDH header, for split_sar it is sar accordingly.

single_id_split - split the message but return the message ID common for all segments

payload - message_payload field is used for sending the message text

The splitting (options 2/3) depends on the coding:

"- dataCoding = 0, 1 or 3: one message can contain up to 160 bytes. If more: segment count = 'message length in symbols / 153 symbols' (or: 'message length in bytes / 153 bytes')

- dataCoding 2, 4 - 7: one message can contain up to 140 bytes, if more – segment count = 'message length in symbols / 134 symbols' (or: 'message length in bytes / 134 bytes')

dataCoding 8: one message can contain up to 140 bytes, if more – segment count = 'message length in symbols / 67 symbols' (as 1 symbol occupies 2 bytes, that is: 'message length in bytes / 134 bytes')

plit_or_payload: serves for sending long messages received over HTTP to SMPP vendors. The mode is not supported if several numbers have been received in the dnis parameter within a single request from the client. When the Send text in payload option is enabled in the vendor channel, the message will be sent in the payload field as a single submit_sm packet. Also, a single delivery report is expected for it, whereas the client will be sent as many reports as the number of received parts. Besides, a single EDR will be written, therefore, the bill by segments option must be set in the client product for correct billing of the client.

The default value is "cut".

 No
incMsgId (inc_msg_id)

The client message ID (64 symbols maximum) that can be used for incoming HTTP requests with longMessageMode=cut, longMessageMode=split, longMessageMode=split_sar or no longMessageMode (which equals to longMessageMode=cut). When the SMS switch receives this parameter it will use its value as a client ID. This will allow clients to use their ID to request information on the message if, for example, no routes are available.

In case of long messages (when longMessageMode=split or longMessageMode=split_sar), the incoming parameter inc_msg_id will be one and the same for the entire message, whereas the SMS switch will split the message into several parts and use the same ID for each part, adding the part number to each of them. For example, if a message contains two parts and has the incoming message ID is inc_msg_id=1gfc4dd56cbndcj741xs, the SMS switch will process the messages with IDs 1gfc4dd56cbndcj741xs-1 and 1gfc4dd56cbndcj741xs-2.

 No
srcTon, srcNpi, dstTon, dstNpi the respective parameters for Sender ID and Destination number. Format: integer. Optional No
priorityFlag corresponds to the same name parameter in SMPP. Format: integer. Optional. Allowed values are: 0 and 1 No
registeredDelivery corresponds to the same name parameter in SMPP. Format: integer. Optional. Allowed values are: 0 and 1 No
replaceIfPresentFlag corresponds to the same name parameter in SMPP. Format: integer. Optional. Allowed values are: 0 and 1 No
silent Allowed values are: 0 and 1, where 0 means NOT silent. Any value other than 0 which has been set explicitly is treated as true, for example, silent=false is interpreted as silent=1.

Flag that allows sending silent SMS (message that arrives with no sound and is not displayed on the screen)

Whether the silent SMS arrives as a silent one to the end user depends on the vendor and the other carriers that handle it. 		Yes

Response format

In case of successful processing, the status in the header of the HTTP response is 200 OK. Response body contains the message_id.

Sample of a response in JSON format:

HTTP/1.1 200 OK

Content-Type: application/json

{"message_id":"alss-a1b2c3d4-e5f67890"}

In case

1) the request contains more than one DNIS (comma-separated)

2) the longMessageMode=split/split_sar and the message is longer than 160/70 symbols (GSM/Unicode respectively),

the response will look as follows:

HTTP/1.1 200 OK

Content-Type: application/json

[{"dnis":"34511121","message_id":"5b4c46a8-8dc9-44b4-f55f-3bef56819305",

"segment_num":"1"},{"dnis":"34511121",

"message_id":"5b4c46a8-46bc-7ee6-4a16-7d4e5a0d14af","segment_num":"2"}]

In case of rejected SMS (for example, no compatible routes found), the HTTP response status is - reason for rejection, for exampleNO ROUTES

HTTP/1.1 400 Bad Request

Content-Type: text/html; charset=UTF-8

NO ROUTES

In case an incorrect username or password is provided, the HTTP status is 401 nauthorized The response body contains the string describing the reason for rejection.

HTTP/1.1 401 Unauthorized

Content-Type: text/html; charset=UTF-8

not authorized (check login and password)

If the service_type field exceeds 6 bytes, the response will look as follows:

HTTP/1.1 400 Bad request\n

Content-Type: text/html; charset=UTF-8\n

Service type is invalid\n

If a message is considered a loop in accordance with the Loop Detection functionality, the response will be as follows:

HTTP/1.1 508 Loop Detected

Content-Type: text/html; charset=UTF-8

loop detected

SMS status request

The links below are intended for request of delivery reports over HTTP from the client side.

Request format:

username=<username>&password=<password>&messageId=<messageId>&command=query

Parameters:

username: Login
password: Password
messageId: Message identifier received with the submission response
command: Request type. Must be set to “query” value

All parameters are obligatory.

Response format:

In case of successful processing, the status in the header of the HTTP response is 200 OK. The response body contains the one of the following possible values:

ENROUTE: Message is in routing stage. The status can be returned to the client if the message is in the SENT status
DELIVRD: Message is delivered to the Subscriber
EXPIRED: Message storage period expired
DELETED: Message was deleted
UNDELIV: Message cannot be delivered
ACCEPTD: Message is accepted by SMSC
UNKNOWN: Unknown message status. Information on statuses is stored in the in-memory database for 24 hours (by default). Therefore, this status may be returned if the client has requested a status quite late and it was already removed from the memory.
REJECTD: Message was rejected by SMSc. The status can also be returned for internal failed statuses, for example, for the NO ROUTES status.
IM_EXPD: Delivery report was not received from the IM provider within the im_ttl timeout

Response sample:

HTTP/1.1 200 OK

Content-Type: application/json

{"status": "DELIVRD", "delivery_time": "20210922093309", "mccmnc": "214099", "error_code": "000", "system_delivery_time": "210922093309"}

where delivery_time The response body contains the string describing the reason for rejection. mccmnc is the E212 code; error_code is the delivery error code; is the delivery report receipt time by the System (in the format YYMMDDHH24MISS, for example, 210325153842). system_delivery_time

HTTP/1.1 200 OK

Content-Type: application/json

{"status": "UNKNOWN", "delivery_time": "", "mccmnc": ""}

IIn case an incorrect user name or password is provided, the HTTP status is 401 Unauthorized The response body contains the string describing the reason for rejection.

HTTP/1.1 401 Unauthorized

Content-Type: text/html; charset=UTF-8

not authorized (check login and password)

If the service_type field exceeds 6 bytes, the response will look as follows:

HTTP/1.1 401 Unauthorized

Content-Type: text/html; charset=UTF-8

not authorized (check login and password)