sms_mt_api_1.94

29 November 2013

SMS HTTP Interface 1.94 Technical Guide

SMS HTTP Interface – Technical Guide Page 1 of 19

Table of Contents 1. System Introduction ........................................................................................... 2

2. Authentication ................................................................................................... 2

3. Communication Parameters ................................................................................ 2

4. Request Format ................................................................................................. 3

4.1 Message format ............................................................................................ 4

4.2 Spanish characters message ........................................................................... 5

4.3 German characters message ........................................................................... 6

4.4 French characters message ............................................................................ 6

4.5 Italian characters message ............................................................................. 7

4.6 Portuguese characters message ...................................................................... 8

4.7 Swedish characters message .......................................................................... 9

4.8 Binary message ............................................................................................ 9

4.9 Unicode message .........................................................................................10

4.10 Greek characters message ...........................................................................11

4.11 Chinese characters message ........................................................................12

4.12 WAP Push ..................................................................................................12

5. Response Format ..............................................................................................13

6. HTTP Callback ..................................................................................................14

7. Code Examples .................................................................................................16

7.1 PHP Example ...............................................................................................16

7.2 JAVA Example ..............................................................................................18

8. Version history .................................................................................................19


1. System Introduction

The SMS HTTP interface is an application hosted on a server that listens for HTTP requests containing SMS message data. It processes the HTTP requests and their associated SMS message data and sends the required SMS messages for onward delivery. The SMS HTTP interface sends back an HTTP response containing information about the submitted SMS messages such as the message identifiers of the sent SMS messages. The SMS HTTP interface also includes a callback application which sends back delivery reports. The callback application achieves this by sending HTTP callback requests to your HTTP server (which must return an appropriate response) in order for delivery reports to be received. The figure below illustrates the architectural setup.

2. Authentication The SMS HTTP interface authenticates each HTTP request that it receives based on the username and password supplied in the HTTP request message. This authentication is performed on each HTTP message request.

3. Communication Parameters In order to successfully connect to and send HTTP requests to the SMS HTTP interface the following connection parameters must be used:

• The hostname of the SMS HTTP interface where the HTTP requests are to be sent is serverX.msgtoolbox.com. See your registration mail or contact [email protected] to get information on which server to use, for example server2.msgtoolbox.com.


• The ports on which the SMS HTTP interface listens for HTTP requests are port 80 for standard HTTP and port 443 for HTTPS.

• The HTTP version to use for HTTP requests is version 1.1

4. Request Format An HTTP request can be sent to the SMS HTTP Interface either as a GET or POST request. In order to send a message, both types of requests must contain the following message parameters and these parameters must be in URL encoded form: Parameter Description Mandatory

username Your username X

password Your password X

to Number to send to X

from Sender, numerical (max 15 digits) or alphanumerical (max 11 characters)

X

route Route to use, contact [email protected] for alternatives

X

message Message when sending text message, see language notes (section 5) regarding use of urlencode.

udh User data header when sending binary SMS

body Binary data when sending binary SMS

coding Set to unicode to send unicode message

destport Destination port for sending message to a port

origport Originator port for sending message to a port

url Url when sending wappush

text Text when sending wappush

callback URL to use for callback

encoding The encoding used for the parameter data. Used if you send parameter data in UTF-8 instead of the default Latin-1. Can also be used if coding is set to “unicode” so as not to encode the message in hex

type If set to ‘flash’ a flash message will be sent

customid The custom identifier to be set for the message and which will be sent in the message’s callback


validityrelative The validity period in seconds to be set for the message and which is relative to the current time. E.g. validityrelative=3600 means that the message will expire in an hour’s time

validityabsolute The validity period as a UNIX timestamp to be set for the message and which is absolute. E.g. 1365134400 means that the message will expire at 2013-04-05 06:00

class The message class identifier in which 0=flash, 1 = ME specific, 2 = SIM specific, 3 = TE specific

pid The protocol identifier of the message in hexdecimal format. E.g. pid=41 is Replace short message type 1, according to 3GPP 23.040 specification.

Example GET Request http://server2.msgtoolbox.com/api/current/send/message.php? username=USERNAME &password=PASSWORD &to=46123456789 &from=42 Telecom &route=XX &message=This+is+a+test+message Example POST Request POST /api/current/send/message.php HTTP/1.1 Host: server2.msgtoolbox.com username=USERNAME &password=PASSWORD &to=46123456789 &from=42 Telecom &route=XX &message=This+is+a+test+message

4.1 Message format

In order to a send an SMS whose message body contains normal text, use the message parameter. The encoding to use for the text data assigned to this parameter should be ISO-8859-1. If the text data contained in this parameters is longer than 160 characters the message will split into a number of concatenated messages, up to a maximum of 5 concatenated SMS messages each having 153 characters totalling 765 characters.


Please note that some GSM characters count as two characters. These characters are the following: ““, “” “[“ “]” “~” “|” “\” and “€” Although a single message is specified in an HTTP request, each concatenated message is debited as one SMS message. Example Text message HTTP request http://server2.msgtoolbox.com/api/current/send/message.php? username=USERNAME &password=PASSWORD &to=46123456789 &from=42 Telecom &route=XX &message=This+is+a+test+message

Character sets The gsm7 character set does not support all languages and in some cases only partial support, for example French. Included in our code samples (see section 7.1) is a function (gsm_unsupported_fix) which will convert many common unsupported characters to their plain ASCII equivalent.

When not using English or a unicode character set you should encode your text in ISO-8859-1 format. For example in php use mb_convert_encoding(“Your text”, “ISO-8859-1”, “auto”);

4.2 Spanish character set message

In order to send an SMS whose message body contains Spanish accented characters (for example ñ Ñ é) do not use the encoding parameter. The gsm7 character set is used which fully supports Spanish characters but they must be implicitly specified as ISO-8859-1 Latin1 encoding or by converting to their encoded hexadecimal value. For example ñ becomes %F1. To convert the characters either encode your message text using mb_convert_encoding (for php) or an equivalent depending on your development language, or modify your code to convert the characters as required. Example Spanish message HTTP request: Text: Este es un mensaje de prueba en Español


http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=42%20Telecom &route=XX &message=Este+es+un+mensaje+de+prueba+en+Espa%F1ol

4.3 German character set message

In order to send an SMS whose message body contains German accented characters (for example ü ß) do not use the encoding parameter. The gsm7 character set is used which fully supports German characters but they must be implicitly specified as ISO-8859-1 Latin1 encoding or by converting to their encoded hexadecimal value. For example ß becomes %DF. To convert the characters either encode your message text using mb_convert_encoding (for php) or an equivalent depending on your development language, or modify your code to convert the characters as required. Example German message HTTP request: Text: Dies ist eine Testnachricht für die deutschen Buchstaben ü, ö, ä und ß

http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=42%20Telecom &route=XX &message=Dies+ist+eine+Testnachricht+f%FCr+die+deutschen+Buchstaben+%FC,+%F6,+%E4+und+%DF

4.4 French character set message

The gsm7 character set does not support all French characters. If you require full support then you must send in unicode format or use the SMPP API. For partial support either encode your message text using mb_convert_encoding (for php) or an equivalent depending on your


development language, or modify your code to convert the characters as required. If using php you can use our function gsm_unsupported_fix (see section 7.1) to convert unsupported French characters to plain ASCII equivalents. Example French message HTTP request: Text: Ceci est un message de test à l'aide des caractères é Â ü Æ et ô http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=42%20Telecom &route=XX &message=Ceci+est+un+message+de+test+%E0+l'aide+des+caract%E8res+%E9+A+%FC+%C6+et+o

Note: The é, Æ and ü are converted to the ISO-8859-1 hex equivalent. Â and ô are converted to A and o respectively as they are not part of the gsm7 character set.

4.5 Italian character set message

The gsm7 character set does not support all Italian characters. If you require full support then you must send in Unicode format or use the SMPP API. For partial support either encode your message text using mb_convert_encoding (for php) or an equivalent depending on your development language, or modify your code to convert the characters as required. If using php you can use our function gsm_unsupported_fix (see section 7.1) to convert unsupported Italian characters to plain ASCII equivalents. Example Italian message HTTP request: Text: Questo è un esempio messaggio di prova italiano usando le lettere À Ò é e ó http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD


&to=46123456789 &from=42%20Telecom &route=XX &message=Questo+%E8+un+esempio+messaggio+di+prova+italiano+usando+le+lettere+A+O+%E9+e+o

Note: The è and é are converted to the ISO-8859-1 hex equivalent. À, Ò and ó are converted to A, O and o respectively as they are not part of the gsm7 character set.

4.6 Portuguese character set message

The gsm7 character set does not support all Portuguese characters. If you require full support then you must send in Unicode format or use the SMPP API. For partial support either encode your message text using mb_convert_encoding (for php) or an equivalent depending on your development language, or modify your code to convert the characters as required. If using php you can use our function gsm_unsupported_fix (see section 7.1) to convert unsupported Portuguese characters to plain ASCII equivalents. Example Portuguese message HTTP request: Text: Este é um exemplo de uma mensagem em Português usando os caracteres Ç é ç õ Ú e ê http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=42%20Telecom &route=XX &message=Este+%E9+um+exemplo+de+uma+mensagem+em+Portugues+usando+os+caracteres+%C7+%E9+c+o+U+e+e

Note: The Ç and é are converted to the ISO-8859-1 hex equivalent. Ú, ç, õ and ê are converted to U, c, o and e respectively as they are not part of the gsm7 character set.


4.7 Swedish character set message

In order to send an SMS whose message body contains Swedish accented characters (for example Ä ö) do not use the encoding parameter. The gsm7 character set is used which fully supports Swedish characters but they must be implicitly specified as ISO-8859-1 Latin1 encoding or by converting to their encoded hexadecimal value. For example Ä becomes %C4. To convert the characters either encode your message text using mb_convert_encoding (for php) or an equivalent depending on your development language, or modify your code to convert the characters as required. Example Swedish message HTTP request: Text: Det här är ett meddelande på svenska med tecknen ÅÄÖ åäö

http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=42%20Telecom &route=XX &message=Det+h%E4r+%E4r+ett+meddelande+p%E5+svenska+med+tecknen+%C5%C4%D6+%E4%E4%F6

4.8 Binary message

In order to send an SMS whose message body contains binary data, use the udh and body parameter. Binary data is to be encoded as hexadecimal pairs. Binary messages have a maximum length of 140 bytes equalling 280 hexadecimal characters and will not be automatically concatenated. Example Binary message HTTP request: http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=42%20Telecom &route=XX &udh=0605040B8423F0 &body=DC0601AE02056A0045C60C037777772E343269742E65752F343249545F6D646D2E6A 706700010334324954204C6F676F000101


4.9 Unicode message

In order to send an SMS whose message body contains unicode text, set the coding parameter to ”unicode” and use the message parameter for the message. There are two main ways to encode the message:

1. Hexencoded with 4 characters per hex digit. 2. HTML encoded as either hexdecimal or decimal.

Please note that all characters must be encoded, even numbers and spaces. A unicode message’s maximum length is 70 characters long and if the unicode text specified is longer, then the message is split into a number of concatenated messages each having a maximum of 67 character. The encoding to use for the unicode text is UCS-2. Example Unicode message HTTP request sending ”Hello World” as hexencoded with 4 characters per hex digit: http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=42%20Telecom &route=XX &coding=unicode &message=00480065006C006C006F00200057006F0072006C0064 Example Unicode message HTTP request sending ”Hello World” as HTML encoded characters: http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=42%20Telecom &route=XX &coding=unicode &message=Hello Wo&#x0 072;ld Please note that when using HTML encoded characters you also need to URL encode the message parameter’s content. http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789


&from=42%20Telecom &route=XX &coding=unicode &message=Hello Wo&#x0 072;ld &encoding=utf8

4.10 Greek characters message In order to send an SMS whose message body contains Greek lower case letter characters do not use the encoding parameter and set the coding parameter to unicode. Example Unicode message HTTP request sending Greek lower case letter characters: http://server4.msgtoolbox.com/api/current/send/message.php? username=USERNAME &password=PASSWORD &to=4123456789 &from=9876543210 &route=G1 &coding=unicode &message=0022039303B903CE03C103B303BF002003B103BD002003C303C403B503AF03BB

In order to send an SMS whose message body contains Greek capital letter characters set the coding parameter to gsm7 and set the encoding parameter to utf8. Example GSM7 message HTTP request sending Greek upper case letter characters: http://server4.msgtoolbox.com/api/current/send/message.php ?username=USERNAME &password=PASSWORD &to=4123456789 &from=TEST &message=Φ Γ Λ Ω Π Ψ Σ Θ Ξ ç € &route=G1 &encoding=utf8 &coding=gsm7


4.11 Chinese characters message In order to send an SMS whose message body contains Chinese characters set the coding parameter to unicode and set the encoding parameter to utf8. Example Unicode message HTTP request sending Greek characters is the following: http://server4.msgtoolbox.com/api/current/send/message.php? username=USERNAME &password=PASSWORD &to=4123456789 &from=TEST

&message=汉语/漢語

&route=G1 &encoding=utf8 &coding=unicode

4.12 WAP Push

In order to send an SMS message which is a WAP Push use the url and text parameters. The url parameter’s content should be without the “http://”. The maximum combined length of the url and text parameters is 115 characters. Example WAP Push HTTP request: http://server2.msgtoolbox.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=42%20Telecom &route=XX &url=www.fortytwotele.com/42 Telecom_mdm.jpg &text=42 Telecom logo


5. Response Format The SMS HTTP Interface will return an HTTP response with status 200 (OK) containing the message identifiers of the sent SMS messages. Each message identifier has the associated destination MSISDN and gateway status written on the same line in the following format: gatewaystatus, messageid, destination

Successful SMS messages Successfully sent SMS messages will always have their gatewaystatus set to 1, their messageid and destination MSISDN, each in a separate line in the HTTP response. Example:

1,11737143241234560101,46123456789

Failed SMS messages SMS messages which have been failed to be sent by the SMS HTTP Interface will always have their gateway status set to 0 and an error code will be present instead of a the messageid. Example:

0,4,46123456789

0,1

The following errorcodes are used to identify the cause of why the message was not sent:

1: Bad login details

2: Problem with the message

3: Bad to number

4: Not enough credits to send message.


6. HTTP Callback Delivery reports are returned by the SMS HTTP Interface using HTTP callback requests sent by our callback application to your HTTP server. Each HTTP callback request contains the following parameters: Parameter Description

smsid The message identifier of the message associated with this callback request. This parameter has the same value as themessage identifier received in the HTTP response obtained when sending your message.

status The status parameter specifies the delivery status of the SMS message which you sent. The table below contains the status codes used for the status parameter.

timestamp UNIX timestamp when the delivery report was received

to The number the message was sent to

from The sender id of the message

customid The customid sent in request, if present

Status Description

10 Delivered to gateway

11 Delivery delayed. Possible reasons include receiving network congestion or phone not in contact with network

21 Delivered to network

22 Delivered to phone

30 No credit coverage

41 Malformed message

42 Internal error. Contact support

44 Message expired without delivery.

50 General delivery problem All HTTP callback requests are sent by our callback application as an HTTP GET request. Your HTTP server found at your preset URL must return an unformatted “OK” in its HTTP response when it receives an HTTP callback request. If an “OK” is not returned by your HTTP server, our callback application will try again according to a retry schedule.


The URL that should be requested is set in the controlpanel or set at the request. Login to http://www.fortytwotele.com/ and go to ”Account settings” and ”SMS-MT”.


7. Code Examples The following code examples illustrate how HTTP requests can be programmatically sent to the SMS HTTP Interface and the associated HTTP response read.

7.1 PHP Example PHP Example Send SMS <? $myaccount=urlencode("USERNAME"); $mypasswd=urlencode("PASSWORD"); // For default alphabet $mymsg=urlencode("Hello world"); // For unicode: // $unimsg = mb_convert_encoding("Hello world", 'UTF-16BE', 'auto'); // $mymsg=urlencode($unimsg); // For iso-8859-1: // $isomsg = mb_convert_encoding("Hej världen", 'ISO-8859-1', 'auto'); // $mymsg = urlencode($isomsg); $myto="46731111111"; $myfrom=urlencode("4673222222"); $route="G1"; //Contact your Account-manager to check settings for your account $sendsms = "http://serverX.msgtoolbox.com/api/current/send/message.php" . "?username=$myaccount" . "&password=$mypasswd" . "&to=$myto" . "&from=$myfrom" . "&message=$mymsg" . "&route=$route"; // For unicode: // "&encoding=utf8&coding=unicode"; $getsmsstatus=file($sendsms); $splitstatus = explode(",",$getsmsstatus[0]); if ($splitstatus[0] == "1") $msgid = trim($splitstatus[1]); echo "Message sent to gateway. smsid:" . $msgid; else $msgerror=trim($splitstatus[1]); echo "Couldn't send message. Errorcode:" . $msgerror; ?>


PHP Example Convert accented characters which are not part of the gsm7 character set to plain characters which are supported. For example, convert Ï to I function gsm_unsupported_fix($msgIn) // Replace accented characters in $msgIn (contains message) with standard // alphabetic character equivalent as these characters are not included in // the GSM7 character set $gsmChar=array('ç','ï','Ï','ÿ','Ÿ','â','Â','ê','î','ô','Ô','û','È','À','Ù','Œ','œ','Î','Ë','ë','Ê','ê','Ò','ó','Ì','Ó','«','»','º','ª','Á','Ã','Í','Õ','Ú','á','ã','í','õ','ú'); $gsmHttp=array('c','i','I','y','Y','a','A','e','i','o','O','u','E','A','U','OE','oe','I','E','e','E','e','O','o','I','O','"','"','','','A','A','I','O','U','a','a','i','o','u'); $msgOut = $msgIn; for($i=0;$i<count($gsmChar);$i++) $msgOut=str_replace($gsmChar[$i],$gsmHttp[$i],$msgOut); return $msgOut; PHP Example

Receive callback and handle callbacks for message statuschanges, <? $mysmsid = $_GET["smsid"]; // to get sms id $mystatus = $_GET["status"]; // to get status $mydate = $_GET["date"]; // to get date $myfrom = $_GET["from"]; // to get from $myto = $_GET["to"]; // to get to $timestamp = $_GET['timestamp']; $date = date("Y-m-d H:i:s", $timestamp); //Use to update database etc. echo "OK"; ?>


7.2 JAVA Example try // Generate the HTTP POST request parameters String params = URLEncoder.encode("username", "UTF-8") + "=" + URLEncoder.encode("USERNAME", "UTF-8"); params += "&" + URLEncoder.encode("password", "UTF-8") + "=" + URLEncoder.encode("PASSWORD", "UTF-8"); params += "&" + URLEncoder.encode("to", "UTF-8")+ "=" + URLEncoder.encode("46731111111", "UTF-8"); params += "&" + URLEncoder.encode("from", "UTF-8")+ "=" + URLEncoder.encode("4673222222", "UTF-8"); params += "&" + URLEncoder.encode("route", "UTF-8")+ "=" + URLEncoder.encode("G1", "UTF-8"); params += "&" + URLEncoder.encode("message", "UTF-8")+ "=" + URLEncoder.encode("Hello World", "UTF-8"); // Open a connection to the HTTP interface URL url = new URL("http://serverX.msgtoolbox.com/api/current/send/message.php"); URLConnection conn = url.openConnection(); conn.setDoOutput(true); // Send the HTTP POST Request OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream()); wr.write(params); wr.flush(); // Read the HTTP Response BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream())); String response = rd.readLine(); System.out.println(response); catch (UnsupportedEncodingException e) e.printStackTrace(); catch (MalformedURLException e) e.printStackTrace(); catch (IOException e) e.printStackTrace();


8. Version history Version Date Comment

1.0 2005-12-12 First version 1.5 2007-03-12 New format and merge of appendixes to

main documentation 1.6 2007-08-07 Added documentation for wappush 1.7 2008-02-04 Added status 44 1.8 2010-06-08 42IT is now 42 Telecom 1.9 2013-05-14 New format including introduction,

authentication, connectivity parameters and well defined examples

1.91 2013-09-13 Updated example code due to deprecated messages and fixed comments format due to page width.

1.92 2013-10-16 Updated example code to (a) extend support for accented

characters (b) convert unsupported characters to

plain ASCII equivalents (c) Provide language specific

examples in Spanish, French, Italian, Portuguese

1.94 2013-11-29 Added language specific example in Swedish

sms_mt_api_1.94

Documents

message format

spanish characters message

german characters message

french characters message

italian characters message

portuguese characters

swedish characters message

greek characters message