BULK SMS HTTP API V3.0

Service Overview

HTTP Bulk Service enables customers to send SMS over HTTP/HTTPS and to receive Delivery Reports (DLRs) over same protocol. Also, customer is able to access web interface for managing his account.

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. Due to limits of technology which is used to deliver messages to mobile phones 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.

Customer Account creation

HIn order to have service enabled, Horisen will create following data for customer:

  1. Customer ID
  2. Username for Web Interface
  3. Password for Web Interface
  4. Username for Sending Account
  5. Password for Sending Account
  6. Address of web interface (www.horisen.info)
  7. IP Address from which Callback URL for delivery reports will be invoked, see here

Customer needs to provide following data

  1. Set of IP addresses from which messages will be sent.
  2. Callback DLR URL for delivering reports, see here

Multiple accounts and balance

Customer can have more than one account for message submissions, and each account has its own balance.

Sending Bulk Messages

Bulk messages need to be sent using HTTP/HTTPS 1.0 protocol to URL:

http://sms.horisen.info:12000/bulk/send

or

https://sms.horisen.info:12010/bulk/send

Parameters of SMS can be sent as GET or POST parameters.

Types of bulk messages

Customer can send different types of messages:

  1. Text messages
  2. WAP Service Indicators (WSI)
  3. User-formatted (binary) messages (for advanced users)

Data flow of message and delivery report

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 (DLR event 1)
  • Undelivered message (DLR event 2)
  • Rejected message (DLR event 16)
  • Buffered (temporary undelivered) message (DLR event 4) followed by final DLR event, delivered (1) or undelivered (2)

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.

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

Undelivered message

This case is similar to here, 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 24 hours).
  • In case of some other permanent error that makes delivery to mobile phone impossible

Figure : Data flow for undelivered message

Rejected message

Messages can be rejected by Horisen BULK System in several cases:

  1. When username/password submitted with request do not match the one configured for account
  2. When account is disabled
  3. When there is no money on account balance
  4. When destination is not allowed for customer
  5. When sender field contains not allowed characters
  6. When parameter format is not correct
  7. 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 (see §Figure ) or it can happen later, in which case Callback DLR URL will be invoked with DLR event rejected (see §Figure ). For detailed description of responses see here.

Figure : Data flow for rejected message

Figure : Data flow for message that is rejected later, after successful submission.

Buffered (temporary undelivered) message

If 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:

  1. Absent subscriber (subscriber is not within reach of destination network or his phone is offline)
  2. Mobile phone buffer for SMS is full
  3. 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:

  1. Message is successfully delivered, in which case DLR event delivered is sent
  2. Permanent error happened which makes delivery impossible (e.g. destination number do not exist). DLR event undelivered is sent.
  3. 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

Common parameters for sending messages

These parameters are common regardless of type of message being sent. Optional parameters are marked with *.

Table: Common HTTP parameters for all types of messages

NameDefault valueDescriptionExample
type - Type of message (text, wsi or binary) text
binary
wsi
sender - Sender. It may be text or numeric, see here 41712345678
+41712345678
Service
receiver - Receiver phone number (one or more). See here 4187654321
+4187654321
user - Account username testuser
password - Account password testpass
dlr-mask* 19 DLR mask, see here 23 (1 + 2 + 4 + 16)
dlr-url* - DLR URL, see here See here
flash* false Is flash message (true or false) true or false

Text Messages

Text messages should be submitted with text encoded using UTF-8 encoding. Messages will be split by Horisen BULK Service if needed into separate concatenated SMS, encoded with given DCS (Data Coding Scheme) and customer will be informed (using submission response, see here) how many parts are used for submitting message. Customer is charged per message part. Message can be split in maximum 6 parts. When using GSM Data Coding Scheme customer should be aware that some characters are encoded as two characters, as shown in Table . When using UCS Data Coding Scheme customer should be aware that these messages are submitted to mobile phone in Unicode format, two bytes per character, and therefore use more space then GSM messages. When messages are split:

  1. In case of GSM DCS messages when text length is more than 160 characters (after encoded with GSM DCS). Each part can be maximum 153 characters long (after encoding with GSM DCS).
  2. In case of UCS DCS messages when text length is more than 70 characters long. Each part can be maximum 67 characters long.

Table: Additional parameters for text messages (in addition to common parameters)

NameDefault valueDescriptionExample
text - Message text, see here This is test message
udh* - UDH information, see here
dcs* GSM Message text encoding, see here. Allowed are GSM and UCS. GSM, UCS

Optional UDH submission

When UDH is submitted by customer with message no splitting attempts will be made. If message cannot be submitted to mobile phone due to limits (140 bytes per message), it will be rejected with error: RC_MESSAGE_TOO_LONG (see here).

Text message Example

We want to send message with:

  • Sender ‘Bulk Test’
  • Receiver +4178123456
  • Text: This is test message
  • DCS is GSM
  • We want only final DLR events (see here)
  • We’re using account with username: testuser and password testpass

This message is submitted using following URL:

http://sms.horisen.info:12000/bulk/send?type=text&user=testuser&password=testpass&sender=Bulk+Test&receiver=%2B4178123456&dcs=GSM&text=This+is+test+message&dlr-mask=19

Example for same message, but with UCS (Unicode) DCS:

http://sms.horisen.info:12000/bulk/send?type=text&user=testuser&password=testpass&sender=Bulk+Test&receiver=%2B4178123456&dcs=UCS&text=This+is+test+message&dlr-mask=19

As seen from examples – submission to Horisen BULK System is same when GSM and UCS Data Coding Scheme is used.

WSI Messages

WSI (WAP Service Indication) messages are special types of binary messages. They are formatted by Horisen BULK Service, and customer needs to provide two parameters, url and title. If message cannot be submitted to mobile phone due to limits described above (140 bytes per message), it will be rejected with error: RC_MESSAGE_TOO_LONG (see here).

Table: Additional parameters for WSI message (in addition to common parameters)

NameDefault valueDescriptionExample
url - WSI URL, see here http://your.site.com/info
title - WSI Title, see here Your Site

WSI message example

We want to send message with:

  1. Sender ‘Bulk Test’
  2. Receiver +4178123456
  3. URL: http://www.yoursite.com/test
  4. Title: Test link
  5. We want only final DLR events (see here)
  6. We’re using account with username: testuser and password testpass

This message should be submitted using URL below:

http://sms.horisen.info:12000/bulk/send?type=wsi&sender=Bulk+Test&receiver=%2B4178123456&user=testuser&password=testpass&dlr-mask=19&url=http%3A%2F%2Fwww.yoursite.com%2Ftest&title=Test+link

User formatted (binary) messages

Binary messages are designated for use by advanced customers who want to send already formatted messages. Horisen BULK Service will not split message into concatenated parts, it will deliver message to mobile phone as submitted from customer.

Table: Additional parameters for Binary message (in addition to common parameters)

NameDefault valueDescriptionExample
dcs - Message text DCS, see here.
Allowed are GSM, UCS or BINARY
GSM, UCS, BINARY
body - Message text, hex encoded, see here %54%68%69%73%20%69%73%20%74%65%73%74%20%6d%65%73%73%61%67%65
udh* - UDH information, see here %06%05%04%0b%84%23%f0

Examples of binary messages

Sending text message with GSM dcs using binary format:

  1. Sender ‘Bulk Test’
  2. Receiver +4178123456
  3. Text: This is test message
  4. DCS is GSM
  5. We want only final DLR events (see here)
  6. We’re using account with username: testuser and password testpass

(in this example parameter body is text ‘This is test message’ encoded with GSM encoding)

http://sms.horisen.info:12000/bulk/send?type=binary&user=testuser&password=testpass&sender=Bulk+Test&receiver=%2B4178123456&dcs=GSM&body=%54%68%69%73%20%69%73%20%74%65%73%74%20%6d%65%73%73%61%67%65&dlr-mask=19

Sending same text message but with UCS DCS:
(in this example parameter body is text ‘This is test message’ encoded with UCS encoding, big endian, same as UTF-16BE)

http://sms.horisen.info:12000/bulk/send?type=binary&user=testuser&password=testpass&sender=Bulk+Test&receiver=%2B4178123456&dcs=UCS&body=%00%54%00%68%00%69%00%73%00%20%00%69%00%73%00%20%00%74%00%65%00%73%00%74%00%20%00%6d%00%65%00%73%00%73%00%61%00%67%00%65&dlr-mask=19

Sending binary message (in this example binary message is WSI):

http://sms.horisen.info:12000/bulk/send?type=binary&user=testuser&password=testpass&sender=Bulk+Test&receiver=%2B4178123456&dcs=BINARY&body=%fa%06%01%ae%02%05%04%00%45%c6%0d%03%79%6f%75%72%73%69%74%65%00%85%03%74%65%73%74%00%11%03%39%32%65%62%38%40%68%2e%63%00%0a%c3%04%07%da%0a%1c%08%01%03%54%65%73%74%20%6c%69%6e%6b%00%01%01&udh=%06%05%04%0b%84%23%f0&dlr-mask=19

Detailed parameter description

Message Sender

There are two kinds of senders:

  1. Numeric sender (max 16 digits or 15 digits in case when leading ‘+’ is submitted),
    example ’41712345678′ or ‘+41712345678′
  2. Alphanumeric sender (max 11 characters), example ‘Service’. Not all the characters are supported in sender, see here.

Message Receiver

Receiver of the message should be sent in international format, with or without leading +. It can be 16 digits long, or 15 in case when there is leading ‘+’. Examples: ’41712345678′ or ‘+41712345678′.
There may be multiple receivers (separated by ‘,’ or ‘;’).

Example:
’41712345678,+41712345679,41712345680′.

Message Data Coding Scheme (DCS)

Data coding scheme describes encoding used in formatting message which will be delivered from Horisen BULK service to mobile phone. There are three types of data coding schemes.
Supported encodings are:

  • GSM
  • UCS
  • Binary

Messages encoded with GSM DCS can be 160 characters long (which is 140 bytes of packed 7-bit data). Messages encoded with UCS DCS can be 70 characters long, because each character occupies two bytes. Messages encoded with BINARY DCS can be 140 bytes long. These limits per sms are decreased by size of UDH in bytes.

Message text

Message text should always be submitted encoded with UTF-8 encoding. Using one HTTP invocation client can send messages that cannot be sent as one SMS because they are longer then limit imposed by encoding. In this case concatenated messages will be sent.

WSI Title

WSI message title.

Example:
‘News Link’

WSI URL

WSI message URL.

Example:
http://www.your-site.com/news.

DLR Mask

DLR mask selects Delivery Reports customer wants to receive for sent message. It can be combination of events described in here.

Example:
1+2+16=19 means that all the final statuses will be reported.

DLR URL

DLR URL is URL provided by customer where Horisen Bulk System will submit DLRs over HTTP or HTTPS. It can be defined per account or it can be defined for each individual message. If both are defined, the one defined for message takes precedence. See here.

Binary content

Binary content should be sent as array of HEX digits, two digits prefixed by ‘%’ per byte.

Example:
%54%68%69%73%20%69%73%20%74%65%73%74%20%6d%65%73%73%61%67%65.

UDH information

Binary content should be sent as array of HEX digits, two digits prefixed by ‘%’ per byte.

Example:%06%05%04%0b%84%23%f0.

Return value

Response can have these status codes:

  1. 202 (HTTP status ACCEPTED) Request successfully processed, see below
  2. 420 (HTTP status METHOD_FAILURE) Error happened
  3. 500 (HTTP status INTERNAL_SERVER_ERROR) Internal error happened when processing customer request.

Response content is of MIME type ‘text/plain’ and it consists of:

  1. Status line (first line of response content) – machine readable status
    1. OK <message-id> <num-sms> – message accepted for sending with given ID and separatedinto num-sms SMS parts, where message ID is string containing characters, digits and ‘-‘; num-sms is decimal number.
    2. ERR <err-code> – message not accepted for sending where err-code is decimal number. For error codes see here.
  2. Additional info (rest of lines of response content) – human readable description

When multiple receivers are submitted there will be one line per receiver, until an error, if any.Messages are submitted to receivers in same order how receivers are submitted and OK/ERROR messages in response are returned in same order.

Example of HTTP responses

In case of success (message accepted by Horisen BULK Service):

OK c1257a00-060d-48c3-b20f-8c11511b8a1e 1
Message accepted

In case of failure (message not accepted by Horisen BULK Service):

ERR 113
No credit on account balance

In case of throttling error (message not accepted by Horisen BULK Service):

ERR 105
Too many messages within short period of time. Please resend later

Example of HTTP responses when multiple receivers are submitted

In case when three receivers are submitted all are successfully accepted:

OK 94e5494d-93c4-4798-9648-8845a5831487 1
OK c928d164-ede3-4dfc-a0a8-87372a881638 1
OK 5b33e60c-3b3a-4da2-946d-9d728bcd533c 1
Message accepted

In case of failure when four receivers are submitted and second message not accepted by Horisen BULK Service:

OK 94e5494d-93c4-4798-9648-8845a5831487 1
ERR 113
No credit on account balance

Error codes

Error codeValueDescription
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)

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.

Throttling error

In case that submission failed with RC_THROTTLING_ERROR, customer should wait one second and then retry submission.

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.

Delivery reports

Delivery reports are sent to customer on callback URL he set up during account creation or when submitting message. Callback URL can be implemented in any programming language (e.g. as PHP page on public web server accessible via HTTP or Java Servlet. Horisen BULK Service will invoke this URL whenever it has some delivery report for customer, and it will replace parameters given in table below with actual DLR data.

ParameterDescriptionExample
%U Message ID Message ID as returned when message is sent, see here
%d DLR Event, see here 1
%s Sender
%r Receiver
%e Error code 26
%E Error description Unknown subscriber
%A Account name used for submission. YOUR_USERNAME
%p Part number [0 to total_parts-1] 1
%P Total number of parts 3

DLR Error Codes

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
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)

Delivery report events

Delivery events that Horisen BULK System sends are:

  • 1: Delivered to phone, final status
  • 2: Non-Delivered to Phone, final status
  • 4: Queued on SMSC, temporary status
  • 8: Delivered to SMSC, temporary status
  • 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.

Example:
1+2+16=19 means that all the final statuses will be reported.

Callback DLR URL Examples

Here is typical Callback DLR URL example which requires all the parameters from table above.

http://your.site.com/dlr.php?msgid=%U&dlr-event=%d&sender=%s&receiver=%r&error_code=%e&error_msg=%E&part_num=%p&total_parts=%P

This URL which is provided as dlr-url parameter will be invoked by Horisen BULK Service for updating customer about delivery progress.
Example of message submission with DLR URL:

http://sms.horisen.info:12000/bulk/send?type=text&user=testuser&password=testpass&sender=Bulk+Test&receiver=%2B4178123456&dcs=GSM&text=This+is+test+message&dlr-mask=19&dlr-url=http%3A%2F%2Fyour.site.com%2Fdlr.php%3Fmsgid%3D%25U%26dlr-event%3D%25d%26sender%3D%25s%26receiver%3D%25r%26error_code%3D%25e%26error_msg%3D%25E%26part_num%3D%25p%26total_parts%3D%25P

Delivery report for concatenated messages

In case of concatenated messages separate DLR will be invoked for each message part. They will share same Message ID (returned as response when message is submitted, see here) and will differ only in part_num (%p) parameter.

Cookbook

Message submission

How to pass custom parameters between message submission and DLR

Sometimes customer needs to pass some parameter with message which he needs again in Callback URL. Typical case is when customer, for any reason, don’t want to use message ID received in response of message submission to match DLR with submitted message.

This usually makes sense only if Callback DLR URL (dlr-url parameter) is submitted with message. There can be more then on custom parameter, each with its own name and value.

This parameter should be then added to Callback DLR URL, Example:

http://your.site.com/dlr.php?msgid=%U&dlr-event=%d&sender=%s&receiver=%r&error_code=%e&error_msg=%E&part_num=%p&total_parts=%P&myParameter=myValue

Additional tables

GSM Character set

Table 1: Characters supported with basic (7-bit) GSM

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 à

Table 2: Additional characters on GSM phones (in conversion to GSM character set counted as two characters)

You want to send ASCIISend the following
CharacterDecimalHexCharactersHexDecimal
<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

Supported characters in alphanumeric sender

Table: Supported characters for alphanumeric sender

Special Characters
SupportedNot Supported
CharacterASCII CodeCharacterASCII 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 EURO
. 0x2E
/ 0x2F
: 0x3A
; 0x3B
< 0x3C
= 0x3D
> 0x3E
? 0x3F
Supported Letters and Digits
0123456789
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ