SMS Gateway HTTP API
Request Format
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@fortytwo.com | X |
| message | Message when sending text message, encoded in UTF-8. For an example in Java, see Code Examples » JAVA Example. | |
| 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, | |
| pid | The protocol identifier of the message in hexdecimal format. E.g. pid=41 is Replace short message type 1, according to 3GPP |
Example GET Request
http://imghttp.fortytwotele.com/api/current/send/message.php? username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &route=XX &message=This+is+a+test+message
Example POST Request
POST /api/current/send/message.php HTTP/1.1 Host: imghttp.fortytwotele.com username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &route=XX &message=This+is+a+test+message
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://imghttp.fortytwotele.com/api/current/send/message.php? username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &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 Code Examples » PHP Example 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”);
Spanish characters 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:
http://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &route=XX &message=Este+es+un+mensaje+de+prueba+en+Espa%F1ol
German characters 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://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &route=XX &message=Dies+ist+eine+Testnachricht+f%FCr+die+deutschen+Buchs taben+%FC,+%F6,+%E4+und+%DF
French characters 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 development language, or modify your code to convert the characters as required.
If using php you can use our function gsm_unsupported_fix (see Code Examples » PHP Example) 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://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &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.
Italian characters 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 Code Examples » PHP Example) 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://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &to=46123456789 &from=Fortytwo &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.
Portuguese characters 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 Code Examples » PHP Example) 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://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &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.
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://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &route=XX &udh=0605040B8423F0 &body=DC0601AE02056A0045C60C037777772E343269742E65752F34324954 5F6D646D2E6A 706700010334324954204C6F676F000101
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:
- Hexencoded with 4 characters per hex
- 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://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &route=XX &coding=unicode
Example Unicode message HTTP request sending ”Hello World” as HTML encoded characters:
http://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &route=XX &coding=unicode &message=Hello � 57;o� 072;ld
Please note that when using HTML encoded characters you also need to URL encode the message parameter’s content.
http://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &route=XX &coding=unicode &message=Hello � 57;o� 072;ld &encoding=utf8
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://imghttp.fortytwotele.com/api/current/send/message.php? username=USERNAME &password=PASSWORD &to=4123456789 &from=9876543210 &route=G1 &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://imghttp.fortytwotele.com/api/current/send/message.php ?username=USERNAME &password=PASSWORD &to=4123456789 &from=TEST &message=Φ Γ Λ Ω Π Ψ Σ Θ Ξ ç € &route=G1 &encoding=utf8 &coding=gsm7
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://imghttp.fortytwotele.com/api/current/send/message.php? username=USERNAME &password=PASSWORD &to=4123456789 &from=TEST &message=x.i::/漢語 &route=G1 &encoding=utf8 &coding=unicode
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.
http://imghttp.fortytwotele.com/api/current/send/message.php? ?username=USERNAME &password=PASSWORD &to=46123456789 &from=Fortytwo &route=XX &url=www.fortytwo.com &text=Fortytwo%20website
Get Started