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



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



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



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 ID’s [ 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 ID’s and the User Reference if one was supplied in the request.

Message ID’s 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 ID’s for Successful Response Positive number e.g: 3500235

Successful message ID

-15 Invalid destination or destination not covered

-20 System error, please retry



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 ID’s 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



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.



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.



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



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.



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



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



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 developer’s 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.



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 ID’s 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



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 http://sms1.cardboardfish.com:9001/HTTPSMS?S=H&

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.



7.3 Nokia Ringtone Request URL http://sms1.cardboardfish.com:9001/HTTPSMS?S=H&

UN=username&P=password&DA=447000000000&SA=FreeTone&ST=5&M= 024A3A7D0995D995C9B195E521A5B1B1CD0DBC0400FD1CD496610624CB084125A242892D049B890A24B31251892CC20C511610824B4485125A0A251214511624CB125A2428A231214516890A24B4125224289290491890A24C31258840841892CC20C499610824B4485125A09371214496624A312598418A22C210496890A24B4144A2428A&UD=06050415810000&DC=2

Response OK 375054

Description Ringtone with originator address set to FreeTone. 7.4 Nokia Operator Logo Request URL http://sms1.cardboardfish.com:9001/HTTPSMS?S=H&

UN=username&P=password&DA=447000000000&SA=447000000001&ST=1&M= 32F43300480E010000000000000000000000000000000000000000000000000000000000000000000000003E0005F800004FA06060000D980000D8006060F7BD99CF7BD86F7C6036ADF3636ADFEC6C60F6AD9B6F6AD86F6C60B62D9B6B62D8616C3EF63DF1CF63D86F6C000000000000000000000000000000000000000000000000000000&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 http://sms1.cardboardfish.com:9001/HTTPSMS?S=H&

UN=username&P=password&DA=447000000000&SA=Download&ST=5&M= 01060403AE81EA0205040045C60B037777772E63617264626F617264666973682E636F6D00010343617264426F61726446697368202D20546865204E6578742047656E65726174696F6E206F66204D6F62696C65204D6573736167696E67000101&UD=0605040B8423F0&DC=2

Response OK 375056

Description WAP Push with originator set to Download. 7.6 VCard Request URL http://sms1.cardboardfish.com:9001/HTTPSMS?S=H&

UN=username&P=password&DA=447000000000&SA=Mike&ST=5&M=424547494E3A56434152440D0A56455253494F4E3A322E310D0A4E3A536D6974683B4D696B650D0A54454C3B505245463A2B34343731323334350D0A454E443A56434152440D0A&UD=06050423F423F4&DC=2

Response OK 375057

Description VCard with originator set to Mike.



7.7 Unicode Request URL http://sms1.cardboardfish.com:9001/HTTPSMS?S=H&

UN=username&P=password&DA=447000000000&SA=447111111111&M= 00430061007200640042006f00610072006400460069007300680020002d00200054006800650020004e006500780074002000470065006e00650072006100740069006f006e0020006f00660020004d006f00620069006c00650020004d006500730073006100670069006e0067&DC=4

Response OK 375058

Description Unicode message. 7.8 Concatenated SMS Request URL http://sms1.cardboardfish.com:9001/HTTPSMS?S=H&

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::00430061007200640042006f00610072006400460069007300680020002d00200054006800650020004e006500780074002000470065006e00650072006100740069006f006e0020006f00660020004d006f00620069006c00650020004d006500730073006100670069006e0067

Description A single Unicode incoming SMS.



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.



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.



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



~ 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



ä 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.



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 FAQ’s 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 [email protected] and make sure to include your HTTPSMS account username.

Documents

HTTP SMS Protocol Specification