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
SMS HTTP Interface Technical Guide Page 2 of 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 support@fortytwotele.com to get information on which server to use, for example server2.msgtoolbox.com.
SMS HTTP Interface Technical Guide Page 3 of 19
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 sales@fortytwotele.com 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 messages callback
SMS HTTP Interface Technical Guide Page 4 of 19
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 hours 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.
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.
SMS HTTP Interface Technical Guide Page 5 of 19
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.
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.
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 fr die deutschen Buchstaben , , und
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
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 Portugus usando os caracteres 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.
SMS HTTP Interface Technical Guide Page 9 of 19
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 hr r ett meddelande p svenska med tecknen
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.
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 messages 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:
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:
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:
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:
In order to send an SMS message which is a WAP Push use the url and text parameters. The url parameters content should be without the http://. The maximum combined length of the url and text parameters is 115 characters.
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.
SMS HTTP Interface Technical Guide Page 14 of 19
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 the message 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.
SMS HTTP Interface Technical Guide Page 15 of 19
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.
SMS HTTP Interface Technical Guide Page 16 of 19
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 vrlden", '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";
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"; ?>
// 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();
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
Influence of Freezing and Pasteurization of The Physical Condition of The Plastik (PE, PP and HDPE) As Selar Fish Packaging (Selaroides Leptolepis) in Sendang Biru, Malang, East Java. Indonesia