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 support@fortytwotele.com 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 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


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.

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

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

username=USERNAME
&password=PASSWORD
&to=46123456789
&from=42 Telecom
&route=XX

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 Espaol


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

required.

Example German message HTTP request:

Text: Dies ist eine Testnachricht fr die deutschen Buchstaben
, , und

?username=USERNAME
&password=PASSWORD
&to=46123456789
&from=42%20Telecom
&route=XX
&message=Dies+ist+eine+Testnachricht+f%FCr+die+deutschen+Buchs
taben+%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


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 caractres
et

?username=USERNAME
&password=PASSWORD
&to=46123456789
&from=42%20Telecom
&route=XX
&message=Ceci+est+un+message+de+test+%E0+l'aide+des+caract%E8r
es+%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.

required.

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

?username=USERNAME
&password=PASSWORD


&to=46123456789
&from=42%20Telecom
&route=XX
&message=Questo+%E8+un+esempio+messaggio+di+prova+italiano+usa
ndo+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.

required.

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

?username=USERNAME
&password=PASSWORD
&to=46123456789
&from=42%20Telecom
&route=XX
&message=Este+%E9+um+exemplo+de+uma+mensagem+em+Portugues+usan
do+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.

required.

Example Swedish message HTTP request:

Text: Det hr r ett meddelande p svenska med tecknen

?username=USERNAME
&password=PASSWORD
&to=46123456789
&from=42%20Telecom
&route=XX
&message=Det+h%E4r+%E4r+ett+meddelande+p%E5+svenska+med+teckne
n+%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:

?username=USERNAME
&password=PASSWORD
&to=46123456789
&from=42%20Telecom
&route=XX
&udh=0605040B8423F0
&body=DC0601AE02056A0045C60C037777772E343269742E65752F34324954
5F6D646D2E6A
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 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:

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

?username=USERNAME
&password=PASSWORD
&to=46123456789
&from=42%20Telecom
&route=XX
&coding=unicode
&message=Hello &#x00
57;o&#x0
072;ld

Please note that when using HTML encoded characters you also need to URL
encode the message parameters content.

?username=USERNAME
&password=PASSWORD
&to=46123456789


&from=42%20Telecom
&route=XX
&coding=unicode
&message=Hello &#x00
57;o&#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:

username=USERNAME
&password=PASSWORD
&to=4123456789
&from=9876543210
&route=G1
&coding=unicode
&message=0022039303B903CE03C103B303BF002003B103BD002003C303C40
3B503AF03BB

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:

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 parameters content should be without the http://.
The maximum combined length of the url and text parameters is 115
characters.

Example WAP Push HTTP request:

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


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 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";

$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) {
} catch (IOException e) {
}


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

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SMS MT Api 1.94

Uploaded by

Copyright:

Available Formats

29 November 2013

SMS HTTP Interface 1.94

You might also like