HTTP SMS Protocol Specification

HTTPSMS Protocol Specification V3.
2

2 of 24
Copyright ! 2007 CardBoardFish
1.0 Contents

1.0 Contents

2
2.0 Document Revision History

3
3.0 Overview

3
4.0 Protocol Definition

3
4.1 Submitting an SMS

3
4.1.1 Request URL

4
4.1.1.1 Server hostnames

4
4.1.1.2 HTTP Request URL

4
4.1.1.3 Secured HTTPS Request URL

4
4.1.2 Input Parameters

5
4.1.3 Server Response

7
4.2 Receiving Delivery receipts and Incoming SMS

8
4.2.1 Delivery receipt and Incoming SMS Data Format

8
4.2.2 HTTP Callback

9
4.2.3 Client Polled Retrieval

10
5.0 Sending an SMS

10
5.1 Making the HTTP Request

10
5.1.1 Example - Plain SMS HTTP GET Request

11
5.2 Message Types and Encoding

11
5.2.1 Sending the Euro Symbol

12
5.2.2 Special Long Characters

12
5.3 Concatenated Messages

12
5.4 Controlling the Originator Address

13
5.5 Flash Messages

14
5.6 Binary Messages

14
5.7 Unicode (UCS2) Messages

14
6.0 Delivery Receipts and Incoming SMS

15
6.1 Requesting Delivery Receipts

15
6.2 Matching Delivery Receipts to Sent SMS

15
6.3 Callback

15
6.4 Client Polled

16
7.0 Message Examples

16
7.1 Plain Text SMS

16
7.2 Flash SMS

16
7.3 Nokia Ringtone

17
7.4 Nokia Operator Logo

17
7.5 WAP Push

17
7.6 VCard

17
7.7 Unicode

18
7.8 Concatenated SMS

18
7.9 Receiving Delivery Receipts and Incoming SMS by Callback

18
7.10 Receiving Delivering Receipts and Incoming SMS Client Polled

18
8.0 Appendix A HTTPSMS Response Troubleshooting

19
9.0 Appendix B Delivery Receipt Status Codes

20
10.0 Appendix C URL Encoding

21
11.0 Support

24

HTTPSMS Protocol Specification V3.2

3 of 24
2.0 Document Revision History

Date Version Description
23/06/2008 3.2 Failover servers and secure socket connection information added
20/05/2007 3.1 Content examples added
05/04/2007 3.0 Document re-branded and short parameters introduced for reducing
bandwidth
01/03/2006 2.9 Incoming SMS section added

3.0 Overview

This document describes the CardBoardFish HTTP interface for the purpose of integrating SMS
into applications and web systems.

Sending SMS via this interface is simple and easy to integrate into applications written in almost
any programming language because most languages have built-in support for making HTTP
requests. The SMS is sent to our server in the same way as submitting a form on a website
(POST) or typing a URL into a web browser (GET).

The interface supports both HTTP GET and HTTP POST requests for submitting messages as
well as 2 methods for retrieving delivery receipts and incoming SMS. HTTP persistent
connections can be used to reduce connection overhead for increased message throughput. All
input should be fully URL encoded (see Appendix C).

Multiple failover servers are available to offer increased redundancy in case of Internet or
system problems. They are accessed by changing the hostname in the request URL, as
detailed in section 4.1.1 below. Additionally, secure HTTPS is available by changing the
protocol and port number in the request URL, also detailed in section 4.1.1.

You must have a CardBoardFish HTTPSMS account in order to use this interface. For more
information please visit http://www.cardboardfish.com.

4.0 Protocol Definition

4.1 Submitting an SMS

The following 3 sections describe the request URL, all of its associated input parameters and
their corresponding values, and the expected server response for the process of submitting an
SMS.


4 of 24
4.1.1 Request URL

4.1.1.1 Server Hostnames

Clients may choose to submit to any one of the below server hostnames by substituting the
hostname into the request URL as defined below.

Server Hostname Description
SMS1 sms1.cardboardfish.com Primary SMS Node 1
SMS2 sms2.cardboardfish.com Primary SMS Node 2 Recommended
SMS3 sms3.cardboardfish.com Failover SMS Node to be used in case both primary nodes
experience problems

For ease of reading, only sms1.cardboardfish.com will be present in request URLs for the
remainder of this document.

4.1.1.2 HTTP Request URL

This is the default URL that should be used for submitting messages. You may substitute the
hostname sms1.cardboardfish.com with one of the hostnames as listed above, for
failover reasons or to achieve higher throughputs in the case of one of the hostnames having a
lower network latency.

This URL should be used with the input parameters described in 4.1.2:
http://sms1.cardboardfish.com:9001/HTTPSMS?

4.1.1.3 Secured HTTPS Request URL

HTTPS is available on all server hostnames by changing both the protocol type to https, and
changing the port number to 9444. It is recommended that HTTPS is only used for messages
that specifically require encryption over the Internet.

This URL should be used with the input parameters described in 4.1.2:
https://sms1.cardboardfish.com:9444/HTTPSMS?

Note that the use of encrypted ports is only necessary for specific message types such as
banking one-time passwords. Encryption utilises more server resources and reduces message
throughput.


5 of 24
4.1.2 Input Parameters

This table lists each parameter that can be submitted to the URL given above. Note that the first
6 parameters are mandatory, all others are optional. Parameters are case sensitive.

Parameter Name Description Example Values
S System Type Must be set to value: H H
UN Username Account username (case sensitive) user01
P Password Account password (case sensitive) pass1
DA Destination Address Destination mobile number in
international format without + prefix.
Up to 10 different numbers can be
supplied separated by commas.
447973123456 or
447875622322,34610842235
SA Source Address Originator address (sender id). Up to
16 numeric or 11 alphanumeric
characters.
CBF or
447973123456 or
8040
M Message The SMS text for plain messages or
UCS2 hex for Unicode. For binary,
hex encoded 8-bit data.
Please call me at the
office.

ST Source Address Type
of Number (TON)
Controls the type of originator where:
1 = International numeric
0 = National numeric
5 = Alphanumeric
See section 5.4
DC Data Coding Scheme Controls the type of message content
where:
0 = Flash
1 = Normal (default)
2 = Binary
4 = UCS2
5 = Flash UCS2
6 = Normal GSM encoded
7 = Flash Normal GSM encoded
See sections 5.1 and 5.2
DR Delivery Receipt
Request
Controls whether a delivery receipt is
requested for this message where:
0 = No (default)
1 = Yes
2 = Record Only
See section 6.0
UR User Reference Unique reference supplied by user to
aid with matching delivery receipts.
Maximum 16 alphanumeric characters
including _ and -.
4636363654 or
MY_user_ref-1
V Validity Period The number of minutes to attempt
delivery before the message expires.
Maximum 10080.
1440 (default)
UD User Data Header Hex encoded UDH to be used with
binary messages.
06051234566262

Key for above table
Mandatory parameter
Optional parameter


6 of 24
4.1.3 Server Response

The server forms a HTTP response based on the outcome of the following processes:
Request syntax check Ensures all mandatory parameters are present
Input parameter validation Ensures parameter values do not contain invalid characters and that
they are of the correct length
Authentication check Username and password validation
Destination address coverage check Confirms the destination mobile number(s) are valid and
can be reached using your account routing configuration
Credit balance check Ensures there is sufficient credit on your account to send the message
Message sent check Confirms the message was successfully accepted and assigned a unique
message ID

A response consists of 2 parts:
HTTP header status code
HTTP content containing a plain text string

It is only necessary to check the HTTP content. The HTTP header status code can be useful for
integrating with systems that are only capable of determining success based on a 200 OK
header status.

The syntax of the possible responses is described below where:
Italics Represents variable content such as message IDs
[ optional] Anything within a square bracket is optional. The brackets are not printed.

If all of the above checks are successful for at least 1 of the destination numbers and there is
enough credit to send to all of the destination numbers, a response will be returned with a HTTP
header status code of 200 OK. The response content will contain the word OK followed by one
or more numeric message IDs and the User Reference if one was supplied in the request.

Message IDs are displayed in the order that destination numbers are provided in, in the
request. If a message is successfully sent to a destination number, a positive numeric message
ID will be returned. It is possible that some destination numbers are successful and some are
unsuccessful. In the later case, a negative numeric value of -15 (Invalid destination or
destination not covered) or -20 (System error, please retry) will be returned as the message ID.

4.1.3.1 Successful Response
HTTP Header
200 OK
Content
OK messageid1[ messageidn][ UR:userreference]
4.1.3.1.1 Possible Message IDs for Successful Response
Positive number
e.g: 3500235
Successful message ID
-15 Invalid destination or destination not covered
-20 System error, please retry


7 of 24
If a User Reference was supplied in the request, it will be appended to the end of the response,
prefixed with UR:
A single white space separates all message IDs and the User Reference. There will never be a
white space at the end of the content.

4.1.3,1.2 Example: Successful message to a single destination with no User Reference:
HTTP Header: 200 OK
Content: OK 3583910

4.1.3.1.3 Example: Successful message to a single destination with a User Reference:
HTTP Header: 200 OK
Content: OK 3583911 UR:JBD829SSA

4.1.3.1.4 Example: Message to 2 successful destinations and 1 unsuccessful with a User
Reference:
HTTP Header: 200 OK
Content: OK 3583912 -20 3583913 UR:batch-9

Refer to Appendix A for troubleshooting server response errors.

4.1.3.2 Error Response: Invalid Username or Password
HTTP Header
401 Unauthorized
Content
ERR -10
4.1.3.3 Error Response: Invalid Destination or Destination Not Covered
HTTP Header
503 Service Unavailable
Content
ERR -15
4.1.3.4 Error Response: Not Enough Credit
HTTP Header
402 Payment Required
Content
ERR -5
4.1.3.5 Error Response: System Error, Please Retry
HTTP Header
500 Internal Server Error
Content
ERR -20
4.1.3.6 Error Response: Request Error, Do Not Retry
HTTP Header
400 Bad Request
Content
ERR -25


8 of 24
4.2 Receiving Delivery receipts and Incoming SMS

Delivery receipts and incoming SMS can be received in one of 2 ways and which one you prefer
can be configured on your account. See section 6.0 for more information.

Both methods provide the delivery receipt and incoming SMS data in the same format. The
syntax is described below where:
Italics Represents variable content
[ optional] Anything within a square bracket is optional. The brackets are not printed.

The number of message parts is limited to 100 at a time. A message part will be either a
delivery receipt or an incoming SMS. The format for both is described below.

A delivery receipt will always have the first field (MSGID) > 0.

4.2.1 Delivery receipt and Incoming SMS Data Format
N#[MessagePart1][#MessagePartX]
N
Number of delivery receipts and incoming SMS. Range: 0-100.
#
Message separator. Always present.
[MessagePart1]
First delivery receipt or incoming SMS. See 4.2.1.1 and 4.2.1.2 for message part
format.
[#MessagePartX]
Message separator followed by another delivery receipt or incoming SMS.
4.2.1.1 Message Part Format Delivery receipt
MSGID:[SOURCE]:DESTINATION:STATUS:[ERRORCODE]:DATETIME:[USERREF]:
: Field separator. There will always be exactly 7 colons per message part.
MSGID
Positive numeric message ID matching the one returned in the SMS request
response (See 4.1.3.1).
[SOURCE]
Optional source address (originator).
DESTINATION
A single destination number.
STATUS
Positive numeric delivery receipt status code. See Appendix B for status codes.
[ERRORCODE]
Optional GSM error code consisting of up to 6 hexadecimal characters. Most
routes do not return the GSM error code.
DATETIME
A 10 digit UTC timestamp representing the date and time that the delivery receipt
was received. Always in UK time (GMT or BST).
[USERREF]
If a User Reference was supplied with the SMS request, it will be displayed here.


9 of 24

An incoming SMS will always have the first field equal to -1.

4.2.2 HTTP Callback

One method of receiving delivery receipts and incoming SMS is for our server to make a HTTP
POST request to your web server. A Callback URL must be configured on your HTTPSMS
account first.

As soon as we receive a delivery receipt or incoming SMS, a HTTP request will be made to
your Callback URL with a single input parameter and with a value as described above in section
4.2.1.

For more information about using HTTP Callback for receiving delivery receipts and incoming
SMS, see section 6.3.
4.2.1.2 Message Part Format Incoming SMS
-1:[SOURCE]:DESTINATION:DCS::DATETIME:[UDH]:[MESSAGE]
: Field separator. There will always be exactly 7 colons per message part.
-1
If this field is -1 then the message part is an incoming SMS.
[SOURCE]
Optional source address (originator).
DESTINATION
A single destination number.
DCS
The Data Coding Scheme. Default 1. See sections 5.1 and 5.2.
DATETIME
A 10 digit UTC timestamp representing the date and time that the incoming SMS
was received. Always in UK time (GMT or BST).
[UDH]
If the message is a binary message, its hex User Data Header will be displayed
here.
[MESSAGE]
The message text will be displayed here in hex encoded form. Binary will also be
hex encoded, and Unicode will be represented in UCS2 hex.
4.2.2.1 HTTP Callback Input Parameter
INCOMING
4.2.2.2 HTTP Callback Response Header Status Code
200 OK
If your server responds with this status code, it means that your server accepts
the delivery receipts and incoming SMS so our server will not try and send them
again. The HTTP body that your server returns is ignored.
Any other status code This is considered to be an error and therefore the HTTP Callback will be
attempted again every 30 minutes for a period of 6 hours before giving up.


10 of 24
4.2.3 Client Polled Retrieval

Another method of retrieving delivery receipts and incoming SMS is to make a HTTP request to
the following URL:

USER Should be replaced with your HTTPSMS account username.
PASS Should be replaced with your HTTPSMS account password.

Failover servers and secured HTTPS may also be used for client polled retrieval, as described
in section 4.1.1.

Note that you must retrieve delivery reports from the same server that the original SMS
was submitted to. For example, if you submit messages to sms2.cardboardfish.com,
delivery reports for these messages are only available from sms2.cardboardfish.com.

Incoming SMS can only be retrieved from sms1.cardboardfish.com.

For more information about client polled delivery receipt and incoming SMS retrieval, see
section 6.4.

5.0 Sending an SMS

This section describes the process of sending an SMS, elaborating on the protocol definition
defined above. For ease of understanding HTTP GET will be used in all examples for the rest of
this document.

5.1 Making the HTTP Request

To send an SMS, the HTTP request as described in section 4.1 should be performed using
either HTTP POST or HTTP GET. HTTP POST is recommended, especially for larger
concatenated messages due to URL length limits imposed on HTTP GET.

The HTTPSMS server supports HTTP/1.1 allowing for faster SMS submission as described
next. If you are planning on sending more than 20 messages per minute, it is advisable to
make use of HTTP persistent connections to avoid TCP connection overhead for every
submission. For achieving even higher throughputs such as above 10 per second, HTTP
4.2.3.1 Client Polled Retrieval URL:
http://sms1.cardboardfish.com:9001/ClientDR/ClientDR?UN=USER&P=PASS
4.2.3.2 Client Polled Server Responses
Successful Returns data in the format described above in section 4.2.1
Authentication Error See 4.1.3.2
System Error See 4.1.3.5
Request Error See 4.1.3.6


11 of 24
pipelining provides support for asynchronous requests and responses. This means the HTTP
client does not have to wait for a response before sending the next request, and all responses
are returned in the order that the requests are received.

For further information about the HTTP/1.1 protocol, please see:
http://www.w3.org/Protocols/rfc2616/rfc2616.html

A HTTP GET request is formed by appending parameter=value pairs, each separated by an
ampersand (&) to the request URL. All parameter values must be URL encoded. See Appendix
C for rules on URL encoding.

The server response will be as described in section 4.1.3.

5.2 Message Types and Encoding

The table below lists the several types of SMS that you can send via the HTTPSMS gateway,
along with the appropriate Data Coding Scheme value (DC parameter).

5.1.1. Example - Plain SMS HTTP GET Request
http://sms1.cardboardfish.com:9001/HTTPSMS?S=H&UN=username&
P=password&DA=447000000000&SA=447111111111&M=Hello
username
Your HTTPSMS username (case sensitive)
password
Your HTTPSMS password (case sensitive)
447000000000
The destination mobile number
447111111111
The originator
Hello
The message body
Type of SMS DC Value Description and Example
Plain (7-bit) 1 (default) Plain SMS text such as English encoded as ISO-8859-1 (latin1)
Flash Plain (7-bit) 0 Same as above but pops up on screen without the user having to select read
message.
Binary (8-bit) 2 Hex encoded binary data, accompanied with a User Data Header is used for
transmission of WAP Push alerts, monophonic ringtones, operator logos,
VCards and other smart message formats.
Unicode (UCS2) 4 UCS2 hex used for representing characters not in the GSM alphabet such as
Arabic.

Flash Unicode
(UCS2)
5 Same as above but pops up on screen without the user having to select read
message.
Plain (7-bit) GSM
Encoded
6 Plain SMS text such as English but encoded using the GSM alphabet.
Flash Plain (7-bit)
GSM Encoded
7 Same as above but pops up on screen without the user having to select read
message.


12 of 24
When a DC value is not specified in a request, it is assumed to be a plain 7-bit latin1 text
message.
The HTTPSMS server will automatically convert plain latin1 text to the GSM alphabet so you do
not have to do this yourself. If a character is supplied that is outside of the GSM alphabet, it will
be converted into a white space.
If the message body you wish to send is already GSM encoded then you must set the DC
parameter to a value of 6, or 7 if it is a flash message. A separate document is available
outlining the GSM alphabet and its mapping to ISO-8859-1.

Note that all characters regardless of the message encoding type should conform to the URL
encoding guidelines listed in Appendix C. For example, a latin1 space character is URL
encoded to %20, and a latin1 @ symbol is URL encoded to %40. A GSM space character is
also %20, where as a GSM @ symbol is URL encoded to %00.

5.2.1 Sending the Euro Symbol

The ! (Euro) symbol is outside of the standard ISO-8859-1 (latin1) character set, however the
HTTPSMS system supports both the Windows-1252 (winlatin1), and ISO-8859-15 (latin9)
representations as hex 80, and A4 respectively. If using the GSM alphabet, the Euro symbol is
represented as 2 characters; hex 1B65 (see section 5.2.2 below). These hex values are URL
encoded by preceding them with a % as %80, %A4, and %1B%65 respectively.

5.2.2 Special Long Characters

There are 9 special characters that are counted as 2 individual characters when GSM encoded.
This could result in a message becoming longer and therefore being concatenated (see section
5.3 below). The following table identifies these characters.

5.3 Concatenated Messages

Also referred to as a long message, multipart message or extended message, a concatenated
message is formed from several standard SMS containing a 7 byte concatenation header at the
beginning of each one. Since this 7 byte header is within the message, it reduces the total size
of each SMS to 153 characters each. The table below shows the maximum message length
per number of SMS used for plain 7-bit messages.
Symbol Name
[ Open square
\ Backslash
] Close square
^ Caret
{ Left brace
| Vertical bar
} Right brace
~ Tilde
! Euro symbol


13 of 24

In theory it is possible to utilise 255 messages (39,015 characters) for a concatenated SMS.
However, 3 SMS (or 459 characters), is generally considered to be the longest length message
that will be displayed on the majority of mobile handsets. CardBoardFish limit concatenated
SMS to 459 characters to ensure maximum compatibility.

The HTTPSMS server will automatically concatenate long messages so you are not required to
construct the concatenation header yourself.

Note: Concatenated SMS are billed by the number of individual SMS messages used. If you send
a 459 character message, you will be charged for 3 SMS.

Note: Sending a special character that is listed in section 5.2.2 could result in the message length
exceeding the maximum per SMS and therefore using an extra SMS which you will be charged
for.

Binary and Unicode SMS are concatenated in the same way but in terms of hex encoded bytes.
The below table shows the maximum hex encoded lengths per number of SMS.

Both a User Data Header and concatenation header are required for multipart binary data. The
table above takes this into account and uses the hex encoded lengths as this data should be
submitted to the HTTPSMS system in hex encoded format.

5.4 Controlling the Originator Address

Number of SMS Maximum Message Length
1 160
2 306
3 459
Number of SMS Binary Data Including UDH
Maximum Length Hex
UCS2 Maximum Length Hex
1 266 280
2 512 536
3 768 804
Source TON (ST
Parameter)
Originator Type Description Examples
1 International numeric Adds a + to the beginning of a
number to produce international
formatting. Up to 16 digits.
+447000000000
0 Local numeric and
shortcode
Allows for national numeric format
or shortcode. Up to 16 digits.
07000000000
80050
5 Alphanumeric Supports up to 11 alphanumeric
characters.
Alert
CallNow


14 of 24
Use one of the values listed above for the ST parameter to give more control over the originator
address type. Please note that not all routes support all originator types.

5.5 Flash Messages

A flash message is an SMS that automatically pops up on the handset screen without the user
having to manually open the message. Note that it is not possible to save a flash message on
some handsets.

It is possible to send both plain text flash messages, and Unicode flash messages, by setting
the DC parameter to 0 (7 for GSM encoded), or 5 respectively.

An example request is available in section 7.2.

5.6 Binary Messages

In order to send special messages and content including:
Ringtones
Operator Logos
WAP Push
VCards,
you must construct a binary message, and its corresponding User Data Header.

Details on how to construct the above messages are available in the Nokia Smart Messaging
Specification, available from the Nokia developers forum at:
http://www.forum.nokia.com/

All binary content must be submitted in hex encoded form via the M parameter. The User Data
Header (usually 14 hex characters in length) must also be supplied via the UD parameter.
Finally, the DC parameter must be set to 2 to indicate a binary content message.

Examples of binary SMS requests can be found in sections 7.3, 7.4, 7.5 and 7.6.

5.7 Unicode (UCS2) Messages

In order to send characters that are outside of the GSM 7-bit alphabet (see Appendix C),
Unicode must be used. This is an alphabet using up to 16 bits to represent each character and
allows languages including the following:
Afrikaans, Arabic, Croatian, Czech, Danish, Dutch, Esperanto, Finnish, French, Georgian,
German, Greek, Hebrew, Hindi, Icelandic, Interlingua, Italian, Japanese, Korean, Lithuanian,
Macedonian, Maltese, Persian, Polish, Portuguese, Romanian, Russian, Slovenian, Spanish,
Swedish, Thai, Tigrigna, Turkish, Uyghur, Vietnamese and Welsh.

Due to the fact that 2 bytes are used per character, the maximum size of a single SMS is
reduced to 70 Unicode characters. The Unicode standard that must be used is UCS2 hex, and
should be submitted via the M parameter. The DC parameter must also be set to 4, or 5 in the
case of a flash Unicode SMS.


15 of 24
6.0 Delivery Receipts and Incoming SMS

A delivery receipt (also known as a delivery report or delivery confirmation) is a special type of
message that is used to indicate the status of a sent SMS. Generally, only basic information
such as whether an SMS delivered or failed is available, but some SMS routes provide
additional GSM error codes in the case of failure. Note that the availability of delivery receipts is
SMS route dependent, and they are not available to all destinations.

The status codes returned in a delivery receipt can be found in Appendix B.

6.1 Requesting Delivery Receipts

A delivery receipt is not requested by default for every SMS submitted. The DR parameter must
be set to one of the values in the below table.

If the DR parameter is set to 1, then the delivery receipt will be returned to you by one of the two
methods described in sections 6.3 and 6.4, and the status will also be recorded to your
HTTPSMS account log. If the DR parameter is set to 2, then the delivery receipt will still be
requested but its status will simply be recorded on your account log instead of being returned to
you.

6.2 Matching Delivery Receipts with Sent SMS

A delivery receipt can be matched to a sent SMS by either the server-supplied message ID, or
the User Reference if one was supplied at the time of submission. A message ID is always
returned in response to a successful SMS submission regardless of whether a User Reference
is supplied. Similarly, a message ID is always part of a delivery receipt, and the User Reference
is included if one was supplied.

If your submission contains multiple destination numbers, the server response will contain
multiple message IDs referring to each destination number in the order that they were supplied
in. If you wish to match delivery receipts using a User Reference with multiple destination
submissions, you must also match the destination number, and possibly source address. See
section 4.1.3.1.4 for an example server response.

6.3 Callback

This method involves our server sending your delivery receipts and incoming SMS by a HTTP
POST request to your web server. You must have a Callback URL configured on your account
for this to work. The data can be accessed via the INCOMING parameter whose value is
described in section 4.2.1.
DR Parameter Value Description
0
Do not request delivery receipt (default)
1
Request delivery receipt and send them to client
2
Request delivery receipt and record the status on your account only


16 of 24
In order to accept the delivery receipts and incoming SMS, your server must respond with HTTP
status code 200. If you cannot process the data at this time, for example, due to a database
problem, you can return any other error such as status code 500. If a status code other than
200 is received, the HTTP POST will be retried every 30 minutes for a period of 6 hours.

6.4 Client Polled

The second method is to make a HTTP request to our server, in which the delivery receipts and
incoming SMS are returned in the response. This could be set up to run every minute by your
server in order to automate the process. We advise you not to poll for delivery receipts and
incoming SMS more frequently than every 10 seconds because it is more efficient to allow them
to accumulate as up to 100 can be returned per request. See section 4.2.3 for more
information.

7.0 Message Examples

The following sections show an example HTTP GET request and an example successful
response for the most common message types.

7.1 Plain Text SMS
Request URL
http://sms1.cardboardfish.com:9001/HTTPSMS?S=H&
UN=username&P=password&DA=447000000000&SA=447111111111&M=Hello&
UR=AF31C0D&DR=1

Response
OK 375052 UR:AF31C0D
Description Plain SMS with User Reference and delivery receipt request.

7.2 Flash SMS
Request URL
UN=username&P=password&DA=447000000000&SA=447111111111&M=Hello&
UR=MSG_1&DR=1&DC=0

Response
OK 375053 UR:MSG_1
Description Plain flash SMS with User Reference and delivery receipt request.


17 of 24
7.3 Nokia Ringtone
Request URL
UN=username&P=password&DA=447000000000&SA=FreeTone&ST=5&M=
024A3A7D0995D995C9B195E521A5B1B1CD0DBC0400FD1CD496610624CB08412
5A242892D049B890A24B31251892CC20C511610824B4485125A0A2512145116
24CB125A2428A231214516890A24B4125224289290491890A24C31258840841
892CC20C499610824B4485125A09371214496624A312598418A22C210496890
A24B4144A2428A&UD=06050415810000&DC=2

Response
OK 375054
Description Ringtone with originator address set to FreeTone.

7.4 Nokia Operator Logo
Request URL
UN=username&P=password&DA=447000000000&SA=447000000001&ST=1&M=
32F43300480E010000000000000000000000000000000000000000000000000
000000000000000000000003E0005F800004FA06060000D980000D8006060F7
BD99CF7BD86F7C6036ADF3636ADFEC6C60F6AD9B6F6AD86F6C60B62D9B6B62D
8616C3EF63DF1CF63D86F6C0000000000000000000000000000000000000000
00000000000000&UD=06050415820000&DC=2&UR=LO_5&DR=2

Response
OK 375055 UR:LO_5
Description Operator Logo with numeric originator address, User Reference and delivery receipt
recorded on account only.

7.5 WAP Push
Request URL
UN=username&P=password&DA=447000000000&SA=Download&ST=5&M=
01060403AE81EA0205040045C60B037777772E63617264626F6172646669736
82E636F6D00010343617264426F61726446697368202D20546865204E657874
2047656E65726174696F6E206F66204D6F62696C65204D6573736167696E670
00101&UD=0605040B8423F0&DC=2

Response
OK 375056
Description WAP Push with originator set to Download.

7.6 VCard
Request URL
UN=username&P=password&DA=447000000000&SA=Mike&ST=5&M=424547494
E3A56434152440D0A56455253494F4E3A322E310D0A4E3A536D6974683B4D69
6B650D0A54454C3B505245463A2B34343731323334350D0A454E443A5643415
2440D0A&UD=06050423F423F4&DC=2
Response
OK 375057
Description VCard with originator set to Mike.


18 of 24
7.7 Unicode
Request URL
UN=username&P=password&DA=447000000000&SA=447111111111&M=
00430061007200640042006f00610072006400460069007300680020002d002
00054006800650020004e006500780074002000470065006e00650072006100
740069006f006e0020006f00660020004d006f00620069006c00650020004d0
06500730073006100670069006e0067&DC=4

Response
OK 375058
Description Unicode message.

7.8 Concatenated SMS
Request URL
UN=username&P=password&DA=447000000000&SA=447111111111&M=
Hi!+The+train+is+delayed+so+please+pick+me+up+from+London+road+
train+station.+Let+me+know+if+you+can+make+it+because+if+not+I+
will+catch+a+taxi.+Speak+to+you+soon.
&UR=MSG_1&DR=1

Response
OK 375059 UR:MSG_1
Description Long plain message with User Reference and delivery receipt. This message is 163
characters long so it would require 2 SMS.

7.9 Receiving Delivery Receipts and Incoming SMS by Callback
Request URL N/A. URL on your web server.
Data
INCOMING=2#1128173:447111111111:447000000000:1:0:1180019698:AF3
1C0D:#-1:447111111112:447000000003:1::1180019700::48656C6C6F
Description A delivery receipt followed by an incoming SMS with message Hello (hex encoded).

7.10 Receiving Delivery Receipts and Incoming SMS Client Polled
Request URL
http://sms1.cardboardfish.com:9001/ClientDR/ClientDR?UN=usernam
e&P=password
Response
1#-
1:447111111112:447000000003:4::1180019702::00430061007200640042
006f00610072006400460069007300680020002d00200054006800650020004
e006500780074002000470065006e00650072006100740069006f006e002000
6f00660020004d006f00620069006c00650020004d006500730073006100670
069006e0067
Description A single Unicode incoming SMS.


19 of 24
8.0 Appendix A HTTPSMS Response Troubleshooting

The below table describes all the possible error codes that the HTTPSMS system can return,
what causes them and any possible solutions.

Error Code Description Causes Solutions
-10 Invalid
Username or
Password
The username or
password you have
provided is not
available on the
HTTPSMS system or
is incorrect.
1. Check the username and password is correct.
They are both case sensitive.
-15 Invalid
Destination or
Destination not
Covered
The destination
mobile number
cannot be identified
as belonging to any
country, or routing for
this destination is not
set up on your
account.
1. Check that the destination number is in
international format. For example, a UK number
starting 07xxx, should be provided as 447xxx.

2. Confirm that the destination you are sending to is
configured on your account.
-5 Not Enough
Credit
The SMS you are
trying to send costs
more than the
balance of your
account.
1. Remember that concatenated messages result in
several messages being charged for (see section
5.3).

2. Increase the balance of your account by making
a payment.
-20 System Error,
Please Retry
Internal error related
to routing or
database interaction.
1. The SMS should be re-submitted after 1 minute.
Bear in mind that if the request included multiple
destination numbers, it is highly unlikely but
possible that some destinations may have been
successful and therefore charged for.
-25 Request Error,
Do not Retry
This is caused when
a required input
parameter is missing,
or the input data is
invalid.

Do not retry this
request until the
syntax or input is
corrected.
1. Refer to section 4.1 and confirm the following
parameters are included in the request:
S=H
UN
P
DA
SA
M

2. First try submitting a request with just the above
parameters set to appropriate values, and add
additional parameters one at a time to help identify
which one is not passing the input validation.

3. Bear in mind that if using a DC value of 2, 4 or 5,
the M value must be hex encoded and the hex
length should be divisible by 2. A DC value of 2
also requires a UD value of hex length 14.

4. Try example values as given in table 4.1.2.


20 of 24
9.0 Appendix B Delivery Receipt Status Codes

A delivery receipt will contain a status code with one of the following values.

Status Code Name Description
1
DELIVERED Message delivered to handset.
2
BUFFERED Message buffered, usually because it failed first time and is now
being retried.
3
FAILED The message failed to deliver. The GSM error code may give more
information.
5
EXPIRED Message expired, could not be delivered within the validity period.
6
REJECTED Message rejected by SMSC.
7
ERROR SMSC error, message could not be processed this time.
11
UNKNOWN Unknown status, usually generated after 24 hours if no status has
been returned from the SMSC.
12
UNKNOWN Unknown status, SMSC returned a non standard status code.


21 of 24
10.0 Appendix C URL Encoding

The below tables list all of the characters supported by the GSM character set, and how they
should be URL encoded in ISO-8859-1 representation. Characters that are not listed here will
automatically be converted to a single white space.

Allowed without URL encoding:

Character Name Hex
0-9 Numbers 30-39
A-Z Upper case letters 41-5A
a-z Lower case letters 61-7A
Apostrophe 27
( Left parenthesis 28
) Right parenthesis 29
_ Underscore 5F
. Full stop 2E
! Exclamation 21
* Asterisk 2A

Requires URL encoding:

Character Name Hex
LF Line Feed 0A
CR Carriage Return 0D
SP Normal space
20
" Double quote
22
# Hash
23
$ Dollar
24
% Percent
25
& Ampersand
26
+ Plus sign
2B
, Comma
2C
- Minus sign
2D
/ Forward slash
2F
: Colon
3A
; Semicolon
3B
< Less than
3C
= Equals
3D
> Greater than
3E
? Question mark
3F
@ At sign
40
[ Open square bracket
5B
\ Backslash
5C
] Close square bracket
5D
^ Caret
5E
{ Left brace
7B
| Vertical bar
7C
} Right brace
7D


22 of 24
~ Tilde
7E
! Euro symbol
80
-- Sector Sign 8E
-- u grave 95
-- u 96
-- u 97
-- u umlaut 98
Inverted exclamation
A1
Pound sign
A3
Currency sign
A4
Yen sign
A5
Section sign
A7
Inverted question mark
BF
A grave
C0
A acute
C1
A circumflex
C2
A tilde
C3
A umlaut
C4
A ring
C5
AE ligature
C6
C cedilla
C7
E grave
C8
E acute
C9
E circumflex
CA
E umlaut
CB
I grave
CC
I acute
CD
I circumflex
CE
I umlaut
CF
" ETH
D0
N tilde
D1
O grave
D2
O acute
D3
O circumflex
D4
O tilde
D5
O umlaut
D6
O slash
D8
U grave
D9
U acute
DA
U circumflex
DB
U umlaut
DC
# Y acute
DD
sharp s
DF
a grave
E0
a acute
E1
a circumflex
E2
a tilde
E3


23 of 24
a umlaut
E4
a ring
E5
ae ligature
E6
c cedilla
E7
e grave
E8
e acute
E9
e circumflex
EA
e umlaut
EB
i grave
EC
i acute
ED
i circumflex
EE
i umlaut
EF
$ eth
F0
n tilde
F1
o grave
F2
o acute
F3
o circumflex
F4
o tilde
F5
o umlaut
F6
o slash
F8
u grave
F9
u acute
FA
u circumflex
FB
u umlaut
FC
% y acute
FD

Note: -- represents an unprintable character.


24 of 24
11.0 Support

Please ensure to read through this document fully as well as any related messaging
specifications before contacting support.

Further documentation, guides and FAQs are available from the Support section when logged
into your customer account at http://www.cardboardfish.com/login/. From here, you can submit
a request to our support ticketing system that will provide us with information about your
account configuration to allow for a quicker response.

Alternatively, please email support@support.cardboardfish.com and make sure to include your
HTTPSMS account username.

HTTP SMS Protocol Specification

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

HTTP SMS Protocol Specification

Hochgeladen von

Copyright:

Verfügbare Formate

HTTPSMS Protocol Specification V3.

Das könnte Ihnen auch gefallen