SMS HTTP(S) API - v4.0.2
1. Introduction
HTTP Bulk Service enables customers to send SMS over HTTP/HTTPS and to receive Delivery Reports (DLRs) over the same protocol.
1.1 Integration
PHP: https://github.com/horisen/smsgate-smshttpclient-php
JavaScript: https://github.com/horisen/smsgate-smshttpclient-node
Go: https://github.com/horisen/smsgate-smshttpclient-golang
1.2 Help with formatting special types of messages
HORISEN BULK System helps customer to format special types of messages, like concatenated messages and WSI (WAP Service Indication) messages. HORISEN BULK System may split submitted message into several physical SMS messages (concatenated messages) or reject message because it is too long. Customer balance is charged per physical SMS, as in details described in following text.
2. Protocol description
2.1 Types of bulk messages
Customer can send different types of messages:
- GSM Text messages
- Unicode Text Messages
- WAP Service Indicators (WSI)
2.2 Data flow of message and delivery reports
Message is submitted over HTTP/HTTPS from customer to HORISEN BULK System. When HORISEN BULK System has information what happened with delivery of message (see here) it will send (also over HTTP/HTTPS) event to customer provided Callback DLR URL.
There are four cases:
- Delivered message (DELIVERED)
- Undelivered message (UNDELIVERED)
- Rejected message (REJECTED)
- Buffered (temporary undelivered) message (BUFFERED) followed by final DLR event, delivered (DELIVERED), undelivered (UNDELIVERED) or rejected (REJECTED)
When message cannot be delivered as fast as possible due to temporary problems, if DLR mask allows sending buffered events to customers for each delivery attempt DLR event buffered will be sent to Callback DLR URL, as described in here. If DLR mask do not allow sending DLR event buffered to customers no notification will be provided to customer until final event, delivered or undelivered. When message is delivered (at first attempt or at any latter attempt) DLR event delivered will be sent, as described in here. When HORISEN BULK System decides that message cannot be delivered (at first attempt or at any latter attempt or when message validity expires) DLR event undelivered will be sent, as described in here. When message is rejected immediately on submission, customer will be informed using HTTP response about the reason, as described in here. Rejection may also happen later, and customer will be informed using DLR event rejected.
2.3 Delivered message
When customer submits SMS to HORISEN BULK System message will be delivered to mobile phone as fast as possible. When HORISEN BULK System receives from mobile phone confirmation that message is delivered it will send DLR Event 1 to Callback DLR URL.
Figure : Data flow for delivered message
2.4 Undelivered message
This case is similar to "Delivered message", but describes failure in delivery. Callback DLR URL will be invoked with DLR event 2 and reason. No further attempt of delivery will be made. Messages are undelivered in cases when:
- Destination number do not represent existing mobile phone
- There is no route to required destination
- If HORISEN BULK System was not able to deliver message to phone during validity period (which is by default 24 hours).
- In case of some other permanent error that makes delivery to mobile phone impossible
Figure : Data flow for undelivered message
2.5 Rejected message
Messages can be rejected by HORISEN BULK System in several cases:
- When username/password submitted with request do not match the one configured for account
- When account is disabled
- When there is no money on account balance
- When destination is not allowed for customer
- When sender field contains not allowed characters
- When parameter format is not correct
- When contents of some parameters (for example parameter text for text message submission) contain characters not supported with selected DCS.
- Rejection can happen immediately on submission, in which case error will be returned to customer with HTTP/HTTP response on submission request or it can happen later, in which case callback DLR URL will be invoked with DLR event rejected.
Figure : Data flow for rejected message
Figure : Data flow for message that is rejected later, after successful submission.
2.6 Buffered (temporary undelivered) message
HORISEN BULK System cannot deliver message at first attempt, and DLR mask allows sending of buffered messages to customer, DLR will be sent to customer for each attempt with reason of temporary failed delivery.
Reasons for temporary failures can be:
- Absent subscriber (subscriber is not within reach of destination network or his phone is offline)
- Mobile phone buffer for SMS is full
- Any other temporary failures of mobile device or destination mobile network when there is a chance to be resolved within message validity period
HORISEN BULK System will stop trying to deliver message in following situations:
- Message is successfully delivered, in which case DLR event delivered is sent
- Permanent error happened which makes delivery impossible (e.g. destination number do not exist). DLR event undelivered is sent.
- Message validity period expired – within 24 hours HORISEN BULK System was not able to deliver message to mobile phone. DLR event undelivered is sent.
Figure : Data flow for buffered (temporary undelivered) message
3. Sending SMS
3.1 Text messages in GSM Encoding
SMS to be sent is encoded in JSON document:
{
"type":"text",
"auth": {"username":"testuser", "password":"testpassword"},
"sender":"BulkTest",
"receiver":"4179123456",
"dcs":"GSM",
"text":"This is test message",
"dlrMask":19,
"dlrUrl":"http://my-server.com/dlrjson.php"
}
and it have to be submitted to URL:
- For HTTP:
http://sms.horisen.info:12020/bulk/sendsms
- For HTTPS:
https://sms.horisen.info:12021/bulk/sendsms
3.2 Examples (from bash shell)
For HTTP:
CONTENT='{
"type":"text",
"auth": {"username":"testuser", "password":"testpassword"},
"sender":"BulkTest",
"receiver":"41787078880",
"dcs":"GSM",
"text":"This is test message",
"dlrMask":19,
"dlrUrl":"http://my-server.com/dlrjson.php"
}'
curl -L "http://sms.horisen.info:12020/bulk/sendsms" -XPOST -d "$CONTENT"
For HTTPS:
CONTENT='{
"type":"text",
"auth": {"username":"testuser", "password":"testpassword"},
"sender":"BulkTest",
"receiver":"41787078880",
"dcs":"GSM",
"text":"This is test message",
"dlrMask":19,
"dlrUrl":"http://my-server.com/dlrjson.php"
}'
curl -L "https://sms.horisen.info:12021/bulk/sendsms" -XPOST -d "$CONTENT"
3.3 Unicode Messages
{
"type":"text",
"auth": {"username":"testuser", "password":"testpassword"},
"sender":"BulkTest",
"receiver":"4179123456",
"dcs":"UCS",
"text":"This is test message with some UTF-8 characters üöä€ ",
"dlrMask":19,
"dlrUrl":"http://my-server.com/dlrjson.php"
}
3.4 WAP Server Indication (WSI) messages
{
"type":"wsi",
"auth": {"username":"6666_TESTHTTP", "password":"TerWAvAs"},
"sender":"BulkTest",
"receiver":"41787078880",
"url":"https://www.horisen.com/en/",
"title":"HORISEN",
"dlrMask":19,
"dlrUrl":"http://my-server.com/dlrjson.php"
}
3.5 HTTP Response when sending SMS
If message is accepted to be sent, HTTP status code is 202 and JSON response is:
{
"msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
"numParts": 2
}
If message is rejected, HTTP status code is 420 and response is:
{
"error": {
"code": "107",
"message": "Invalid sender"
}
}
System may also return other error codes from 5xx range. In this case there is no JSON response and error codes conform to standard HTTP error codes.
3.6 Error codes
Error codes are listed in following table
Error code | Value | Description |
---|---|---|
RC_APPLICATION_ERROR | 101 | Internal application error |
RC_ENCODING_ERROR | 102 | Encoding not supported or message not encoded with given encoding |
RC_NO_ACCOUNT | 103 | No account with given username/password |
RC_IP_NOT_ALLOWED | 104 | Sending from clients IP address not allowed |
RC_THROTTLING_ERROR | 105 | Too many messages submitted withing short period of time. Resend later. |
RC_BLACKLISTED_SENDER | 106 | Sender contains words blacklisted on destination |
RC_INVALID_SENDER | 107 | Sender contains illegal characters |
RC_MESSAGE_TOO_LONG | 108 | Message (not split automatically by HORISEN BULK Service, but by customer) is too long. |
RC_BAD_CONTENT_FORMAT | 109 | Format of text/content parameter is wrong. |
RC_MISSING_MANDATORY_PARAMETER | 110 | Mandatory parameter is missing |
RC_UNKNOWN_MESSAGE_TYPE | 111 | Unknown message type |
RC_BAD_PARAMETER_VALUE | 112 | Format of some parameter is wrong. |
RC_NO_CREDIT | 113 | No credit on account balance |
RC_NO_ROUTE | 114 | No route for given destination |
RC_CONCAT_ERROR | 115 | Message cannot be split into concatenated messages (e.g. too many parts will be needed) |
3.7 How to handle errors
When customer receives HTTP status code 420 (METHOD_INVOCATION_FAILURE), he should not retry submission of message, except in case of RC_THROTTLING_ERROR, see here). When multiple receivers are submitted, and there needs to be resubmission, customer needs to resubmit only to receivers beginning with the one for which error is reported.
3.8 Throttling error
In case that submission failed with RC_THROTTLING_ERROR, customer should wait one second and then retry submission.
3.9 Internal server error
In case that submission failed with HTTP status code 500, INTERNAL_SERVER_ERROR, customer should wait at least one minute and then retry submission.
3.10 Receiving DLR
Delivery reports are sent to customer to URL (dlrUrl) provided in JSON with SMS. It is JSON encoded, with following form:
{
"msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
"event": "DELIVERED",
// other values are "UNDELIVERED", "REJECTED", "BUFFERED", "SENT_TO_SMSC"
"errorCode": 0,
"errorMessage": "if exists",
"partNum": 1, // range [0..numParts-1]
"numParts": 2,
"accountName": "testuser"
}
3.11 DLR Error codes
DLR error codes are given in following table:
Value (dec) | Description |
---|---|
0 | No error |
1 | Unknown subscriber |
9 | Illegal subscriber |
11 | Teleservice not provisioned |
13 | Call barred |
15 | CUG reject |
19 | No SMS support in MS |
20 | Error in MS |
21 | Facility not supported |
22 | Memory capacity exceeded |
29 | Absent subscriber |
30 | MS busy for MT SMS |
36 | Network/Protocol failure |
44 | Illegal equipment |
60 | No paging response |
61 | GMSC congestion |
63 | HLR timeout |
64 | MSC/SGSN_timeout |
70 | SMRSE/TCP error |
72 | MT congestion |
75 | GPRS suspended |
80 | No paging response via MSC |
81 | IMSI detached |
82 | Roaming restriction |
83 | Deregistered in HLR for GSM |
84 | Purged for GSM |
85 | No paging response via SGSN |
86 | GPRS detached |
87 | Deregistered in HLR for GPRS |
88 | The MS purged for GPRS |
89 | Unidentified subscriber via MSC |
90 | Unidentified subscriber via SGSN |
112 | Originator missing credit on prepaid account |
113 | Destination missing credit on prepaid account |
114 | Error in prepaid system |
500 | Other error |
988 | MNP Error |
989 | Supplier rejected SMS |
990 | HLR failure |
991 | Rejected by message text filter |
992 | Ported numbers not supported on destination |
993 | Blacklisted sender |
994 | No credit |
995 | Undeliverable |
996 | Validity expired |
997 | Blacklisted receiver |
998 | No route |
999 | Repeated submission (possible looping) |
3.12 Delivery report events
Delivery events that HORISEN BULK System sends are:
- DELIVERED (dlr mask 1): Delivered to phone, final status
- UNDELIVERED (dlr mask 2): Non-Delivered to Phone, final status
- BUFFERED (dlr mask 4): Queued on SMSC, temporary status
- SENT_TO_SMSC (dlr mask 8): Delivered to SMSC, temporary status
- REJECTED (dlr mask 16): Non-Delivered to SMSC, final status
Statuses marked with ‘final status’ are final delivery reports – no further delivery reports will be sent for message. Statuses with ‘temporary status’ are of two kinds:
- Queued on SMSC usually means that there was some problem delivering message to mobile phone, and further DLRs will follow
- Queued on SMSC means that HORISEN BULK System sent message to destination network.
DLR Mask set for each sent message can be combination of these values. For example, 1+2+16=19 means that all the final statuses will be reported (DELIVERED, UNDELIVERED, REJECTED). DLR Mask 19 is recommended.
3. Additional tables
3.1 GSM character set
Dec | 0 | 16 | 32 | 48 | 64 | 80 | 96 | 112 | |
---|---|---|---|---|---|---|---|---|---|
Hex | 0 | 10 | 20 | 30 | 40 | 50 | 60 | 70 | |
0 | 0 | @ | Δ | SP | 0 | ¡ | P | p | |
1 | 1 | £ | _ | ! | 1 | A | Q | a | q |
2 | 2 | $ | Φ | “ | 2 | B | R | b | r |
3 | 3 | ¥ | Γ | # | 3 | C | S | c | s |
4 | 4 | è | Λ | ¤ | 4 | D | T | d | t |
5 | 5 | é | Ω | % | 5 | E | U | e | u |
6 | 6 | ù | Π | & | 6 | F | V | f | v |
7 | 7 | ì | Ψ | ‘ | 7 | G | W | g | w |
8 | 8 | ò | Σ | ( | 8 | H | X | h | x |
9 | 9 | Ç | Θ | ) | 9 | I | Y | i | y |
10 | A | LF | Ξ | * | : | J | Z | j | z |
11 | B | Ø | <ESC> | + | ; | K | Ä | k | ä |
12 | C | ø | Æ | , | < | L | Ö | l | ö |
13 | D | CR | æ | - | = | M | Ñ | m | ñ |
14 | E | Å | . | > | N | Ü | n | ü | |
15 | F | å | É | / | ? | O | § | o | à |
Additional characters on GSM phones (in conversion to GSM character set counted as two characters):
You want to send ASCII | Send the following | ||||
---|---|---|---|---|---|
Character | Decimal | Hex | Characters | Hex | Decimal |
€ | <ESC> e | 1B 65 | 27 101 | ||
<FF> | 10 | 0C | <ESC> <LF> | 1B 0A | 27 10 |
[ | 91 | 5B | <ESC> < | 1B 3C | 27 60 |
\ | 92 | 5C | <ESC> / | 1B 2F | 27 47 |
] | 93 | 5D | <ESC> > | 1B 3E | 27 62 |
^ | 94 | 5E | <ESC> ^ | 1B 14 | 27 20 |
{ | 123 | 7B | <ESC> ( | 1B 28 | 27 40 |
| | 124 | 7C | <ESC> @ | 1B 40 | 27 64 |
} | 125 | 7A | <ESC> ) | 1B 29 | 27 41 |
~ | 126 | 7E | <ESC> = | 1B 3D | 27 61 |
3.2 Supported characters in alphanumeric sender
Special characters
Special Characters | |||
---|---|---|---|
Supported | Not Supported | ||
Character | ASCII Code | Character | ASCII Code |
SPACE | 0×20 | $ | 0×24 |
! | 0×21 | @ | 0×40 |
“ | 0×22 | [ | 0x5B |
# | 0×23 | \ | 0x5C |
% | 0×25 | ] | 0x5D |
& | 0×26 | ^ | 0x5E |
‘ | 0×27 | _ | 0x5F |
( | 0×28 | ` | 0×60 |
) | 0×29 | { | 0x7B |
* | 0x2A | | | 0x7C |
+ | 0x2B | } | 0x7D |
, | 0x2C | ~ | 0x7E |
- | 0x2D | € | |
. | 0x2E | ||
/ | 0x2F | ||
: | 0x3A | ||
; | 0x3B | ||
< | 0x3C | ||
= | 0x3D | ||
> | 0x3E | ||
? | 0x3F |
Supported letters and digits
- 0123456789
- abcdefghijklmnopqrstuvwxyz
- ABCDEFGHIJKLMNOPQRSTUVWXYZ