AMD Telecom SMS GATEWAY HTTP API INTERFACE. Technical Specifications

(1)

AMD Telecom

SMS GATEWAY

HTTP API INTERFACE

Technical Specifications

(2)

Contents 1. Introduction ...3 1.1 Scope of Document...3 1.1.1 Introduction to HTTP2SMS……….3 1.1.2 Requirements………..……….3 2. Technical description………..……….…..3 2.1 Functionality………..………3 2.2 Parameter………..……….3-4e 2.2.1 Alphanumeric Originator Address Code………...4

2.2.2 Account blocking due to multiple invalid HTTP requests………5

2.3 Transport of text messages………5-6 2.3.1 Transport of text-messages in the form of flash SMS………6

2.4 Transport of UTF-8 encoded text messages………6

2.5 Dispatching the delivery report……….……6

2.5.1. By requesting the delivery report from our API……….6-7 2.5.2. By setting up a callback URL………7

2.5.3 Description of the Code retrieved by the delivery report API……….8-9 2.5.4. Delivery receipts via the web-interface………..9

2.5.5 Description of the Error Code (errorcode, errortext)……….9

2.6 Throughput limitation………..9

2.7 Character Support………..9-11 2.8 Retrieving Balance through API………..12

2.9 HTTP API Responses……….12

2.10 Transport of National sender id message ……….14

2.11 Sending Multiple SMS via XML call……….14

Document Information Prepared By: [ADEA] Project Id: [n/a] Document Ref: [n/a] Date: [2013.03.12]

(3)

1. Introduction

1.1 Scope of Document

1.1.1 Introduction to HTTP2SMS

SMS Messages can be transmitted using HTTP protocol. Information about our services can be found on: http://www.amdtelecom.net.

1.1.2 Requirements

The following requirements must be met to enable the sending of short messages (SMS) via AMD Telecom’s Messaging Application.

Access to the AMD Telecom’s Messaging Application HTTP2SMS service is subject to our general terms and conditions of business.

For more information, please address to: For contracts & prices: [email protected] For technical questions: [email protected] For technical hotline: +30 239.40.20.336

2. Technical description 2.1 Functionality

Data is transferred using HTTP-GET requests. AMD Telecom’s messaging system accepts requests at the following URLs:

http://api2.amdtelecom.net:8208

or for additional security enhancement for the interconnection HTTPS is also possible:

https://api2.amdtelecom.net

2.2 Parameters Username: alphanumeric

ie: demo (Username provided by AMD Telecom) Password:

alphanumeric

ie: demo (Password provided by AMD Telecom) From:

(4)

ie: AMD Telecom (Numeric of alphanumeric Originator for the SMS) To:

Numeric: International format. Country code included. You can also use comma separated MSISDN 44123456789,44234567788,44543453454543 for multiple receivers. (Destination MSISDN of the SMS)

Text:

Text, plain or URL Encoded to ensure character validity

(max. 160 characters/SMS. If parameter “coding=2” then, max. 70 characters/SMS) ie: This is my first test SMS (Text of the SMS)

Flash:

Optional value

ie: 1(Generate the SMS as flash (delivery direct to display)). Coding:

Optional value

ie: 2 (To support UNICODE Characters (70 chars/SMS))

2.2.1 Alphanumeric Originator Address Code

The originating address can either be a complete mobile telephone number or alphanumeric character string. The length of the alphanumeric character string may not exceed 11 characters.

2.2.2 Account blocking due to multiple invalid HTTP requests

Your system is configured to block a username if it will not receive the correct password, on more HTTP requests than the account manager has setup.

Example:

Your account is configured with a maximum of 3 incorrect password retry per SMS request. Your account will be blocked completely for 20 minutes.

2.3 Transport of text messages Sending SMS

The text parameter must be included in the text you need to send. Example:

http://api2.amdtelecom.net:8208/?username=demo&password=demo&from=AMDTe lecom&to=44201112345674&text=This%20is%20a%20test%20SMS

The above example sends the message: “This is a test SMS” to the following number +44201112345674 with the originating alpha sender id AMD Telecom, using username demo and password demo, an account active at AMD Telecom’s messaging platform.

(5)

The response for the previous request will be:

SUCCESS Message Id: 5093c47680aa7-5267-87898;Recipient:44201112345674 Sending Multiple SMS via one POST/GET function

Example :

http://api2.amdtelecom.net:8208/?username=demo&password=demo&from=AMDTe lecom&to=44201112345674,44201112345675,44201112345676,44201112345677&tex t=This%20is%20a%20test%20SMS

The previous example sends the message: “This is a test SMS” to the following numbers +44201112345674 +44201112345675, +44201112345676, +442011123456787 with the originating alpha sender id AMD Telecom, using username demo and password demo, an account active at AMD Telecom’s messaging platform.

The reply for the above request will be:

SUCCESS MessageId: 5093c47680aa7-5267-87898; Recipient:44201112345674

SUCCESS MessageId: 5093c4c4401d9-6574-40394; Recipient:44201112345675

SUCCESS MessageId: 5093c4ef41bc1-1442-67312; Recipient:44201112345676

SUCCESS MessageId: 5093c57d6638e-5200-65999; Recipient:44201112345677

More details will be answered at 2.5 chapter “Dispatching the delivery report”. The default value of the delivery validity period of the SMS is used (24 hours).

2.3.1 Transport of text-messages in the form of flash SMS

In addition to the text-message parameter, you can also add a specific parameter to be able to carry out the task “flash”: flash equals 1.

The terminals receive this message directly to display, not inside the device (so it isn’t saved inside the device).

Example:

http://api2.amdtelecom.net:8208/?username=demo&password=demo&from=AMDTe lecom&to=4420111 2345678text=This%20is%20a%20test%20SMS&flash=1

The flash SMS appears on the terminal display as soon as it ́s received.

2.4 Transport of UTF-8 encoded text messages

You can submit messages containing foreign (non-latin) characters using the Unicode Character Set (UCS)Encoding. The length of UCS-encoded text-messages is limited to 70 characters.

(6)

You can find a complete list of UCS-characters at: http://www.unicode.org/charts/

There isn’t any specific procedure that the user must do to send a Unicode message. If you’re sending a message directly from the browsers’ address bar then just put the UNICODE characters inside the textbox, add parameter “&coding=2” at the end and press enter. If you’re using the API inside programming source code, then just URL encode the message to be sent and add “&coding=2” at the end.

Example:

http://api2.amdtelecom.net:8208/?username=demo&password=demo&from=AMDTe lecom&to=44201112345678text=официальные%20информационныеисточники%2 0органов%20государственной%20власти%20Российской &coding=2

2.5 Dispatching the delivery report.

2.5.1. By requesting the delivery report from our API

A detailed delivery receipt can be requested for each SMS at every status change of the SMS and the final successful or failed delivery of the SMS is processed and stored by AMD Telecom’s Messaging System.

If needed, delivery receipts can be dispatched by the customer system via HTTP- Requests.

A unique message id is being assigned to each valid SMS being sent to AMD Telecom’s Messaging System.

A delivery receipt can be requested using separate API. Sample on transport of text messages:

http://api2.amdtelecom.net:8208/?username=demo&password=demo&from=AMDTe lecom&to=44201112345678text=This%20is%20a%20test%20SMS

The reply received is:

SUCCESSMessageId: 5093c47680aa7-5267-87898; Recipient:44201112345678 Sample request of the delivery receipt for the above example:

http://api2.amdtelecom.net:8208/smstracking/?username=demo&password=demo&i d=509a1bc957642-2809-50136

The reply received is:

{"Tracking":[{"ID":"509a1bc957642-2809-50136","EID":"38c933cb-353f-4166-b5c7-9399014526a2","MSISDN":"3548242033","Code":"007","Description":"Delivered","Trac kedDate":"07-11-2012 11:00:50","MccMnc":"27402","Country":"Iceland","Operator":"Vodafone"}]} or {"Tracking":[{"ID":"509b653372b3c-7481-56837","EID":[{"1":"1cd852d1-f8d3-43ca- 86eb-312278d9fb5d"},{"2":"48b903de-fd3b-4a8b-a849-3f23df7cc4f5"},{"3":"96b00b7f- 793d-4c3a-a940-09876fd9ed4e"}],"MSISDN":"306978051983","Code":"007","Description":"Delivered","T

(7)

rackedDate":"08-11-2012

09:51:34","MccMnc":"20201","Country":"Greece","Operator":"COSMOTE"}]} (for concatenated messages)

Where “EID” is the message id, used for tracking the message inside AMD Telecom’s extranet platform.

2.5.2. By setting up a callback URL

You can setup the callback URL that we will use for sending the delivery receipt to your server from AMD Telecom’s extranet: Account setting -> CallbackURL.

The format should be: http://my.server.com/delivery.php

Notice that the callback URL should be at most 85 (url encoded) characters long (including the protocol http etc).

The transaction you expect to receive from AMD Telecom while submitting an SMS is in the format:

http://my.server.com/delivery.php?type=8&id=509a1bc957642-2809-50136

While submitting an SMS, our platform is always sending you a bit type with code 8 to acknowledge the receipt of the SMS.

The next you expect to receive for the same id is either 1 for Delivered SMS, 2 For Undelivered SMS or 4 for Enroute status.

The id string is the id you receive while submitting the SMS. So for every ID, you will receive more than one type.

If your server is temporary unavailable, AMD Telecom’s platform is sending the delivery report to your URL only once (there is no retry). So you can use the API explained in step 1, to request the delivery report if you are missing a report for a specific MSISDN. The supported parameters are these:

type (message type status: 8 Acknowledged, 4 EnRoute, 2 Undelivered, 1 Delivered) id (message id)

submitdate (date message submitted [UnixTimeStamp]) donedate (date message final state [UnixTimeStamp]) status (message delivery report [see 2.5.3])

txtstatus (message delivery report text) errorcode (message error code if any) errortext (message error text if any)

msgparts (if more than one[1], how many parts in concatenated message) receiver (the MSISDN of the receiver)

(8)

ie: http://my.server.com/delivery.php?type=1& id=509a1e58c3801-4033-73377& submitdate=1352277418& donedate=1352277421&status=007& errorcode=000& errortext=&txtstatus=DELIVRD&msgparts=1&receiver=306988888888&sender=Userid 2.5.3 Description of the Code (status) retrieved by the delivery report API.

Status status: [004] Accepted by SMSC Intermediate status: [022] Unknown Subscriber Final status: [005] Call Barred Final status: [021]

Unexpected data value Final status: [006] Controlling MSC failure Final status: [007] Delivered Final status: [009] HLR Aborted Final status: [018] Rejected by SMSC Final status: [020]

Unavailable while roaming to Final

status: [999]

Uncategorized Status Final

(9)

status: [001] Absent Subscriber Interm/Final status: [003] Accepted Intermediate

2.5.4. Delivery receipts via the web-interface

If you are logged into AMD Telecom’s Messaging System’s customer area, you can retrieve a detailed delivery receipt by entering the phone number (destination) or the user key of the message. You can locate this interface inside the menu “SMS tracking”. ERRUSERAUTH 001 UNKNOWN (Unknown username or password)

ERRUSERAUTH 002 INVALID (Invalid request)

2.5.5 Description of the Error Code (errorcode, errortext) retrieved by the internal system. Status errorcode: [000] errortext: [] No Error (Final) errorcode: [013] errortext: [CALL_BARRED] The MSISDN is blocked (Final) errorcode: [401]

errortext: [OUT_OF_CREDIT] The MSISDN is blocked (Final)

2.6 Throughput limitation Counting the throughput

There is a throughput limitation configured per account by default at 20 SMS per second. The maximum number of allowed SMS per second depends on the connectivity lag between the requested IP and AMD Telecom’s messaging platform.

2.7 Character Support * 7-bit

The characters that supported in a default GSM 03.38, 7-bit encoding are the following: 1234567890

(10)

abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ ΓΔΘΛΞΠΣΦΨΩ ù¡Éß¤ÆæÅåÇØøäÖö¿ñüÄÑà§Ü£¥ìò!*()_-'".,<> @(%40), #(%23), $(%24), %(%25), &(%26), +(%2B), =(%3D), :(%3A), ;(%3B), /(%2F), ?(%3F)

Line Feed (%0A), Carriage Return (%0D), Escape (%1B), Space (%20)

All the above characters are single. Inside every SMS each one of these characters is counted as one. € (Double Character) ~ (Double Character) [ (%5B) (Double Character) ] (%5D) (Double Character) { (%7B) (Double Character) } (%7D) (Double Character) | (%7C) (Double Character)

^ (%5E) (Double Character)

\ (%5C) (Double Character)

FormFeed (%0C) (Double Character)

All the above characters are double. Inside every SMS each one of these characters is counted as two.

ie.: If we have this message: Test%20Message%20~ΔΩ€

It is NOT 17 characters, but 19 characters, because it contains «~» and «€» characters inside.

To provide more flexibility when typing, we also support these characters: {αβγδεζηθικλμνξοπρστυφχψωςάέήίόύώΆΈΉΊΌΎΏϊϋΐΰΪΫ}.

All above characters will be translated to the matching Upper Case Letter of the 7-Bit encoding (that ensures 160chars/SMS and viewable messages).

The safest way to send any character is to URL Encode the text before submission. ie.: in php you can use the urlencode() function

<?php …

(11)

$text = "This is a test message \n with various characters: ¿ñüÄÑà. Κείμενο. &*@"; $url =

"http://api2.amdtelecom.net:8208/?username=".$username."&password=".$password. "&from=".$from."&to=".$from."&text=".urlencode($text)."";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $output = curl_exec($ch); curl_close($ch); … ?> <?php ... ... $url = "http://api2.amdtelecom.net:8208/'; $fields = array( 'username' => $username, 'password' => $password, 'from' => $from, 'to' => $to, 'text' => urlencode($text) );

foreach($fields as $key=>$value) { $fields_string .= $key.'='.$value.'&'; } rtrim($fields_string, '&'); $ch = curl_init(); curl_setopt($ch,CURLOPT_URL, $url); curl_setopt($ch,CURLOPT_POST, count($fields)); curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string); $result = curl_exec($ch); curl_close($ch); ... ... ?>

(12)

This will send the text:

This+is+a+test+message+%0A+with+various+characters%3A+%C2%BF%C3%B1%C3%BC %C3%84%C3%91%C3%A0.+%CE%9A%CE%B5%CE%AF%CE%BC%CE%B5%CE%BD%CE%BF .+%26%2A%40

And the text that will be delivered to the phone will be:

This+is+a+test+message+%0A+with+various+characters%3A+%C2%BF%C3%B1%C3%BC %C3%84%C3%91%C3%A0.+KEIMENO.+%26*%40

(decoded:

This is a test message

with various characters: ¿ñüÄÑà. KEIMENO. &*@) * Unicode

The safest way to send Unicode Characters (Arabic, Cyrillic, Chinese … basically all languages) is to URL Encode the characters as explained above. By that you will ensure character integrity.

To be able to send Unicode you must add the coding=2 parameter at the end of your URL.

There will be 70chars/SMS and all the characters are single (NO double characters).

2.8 Retrieving the Balance through API

In order to retrieve your balance using the http api, you have to request a url like the example below.

http://extranet.amdtelecom.net/api_new/balance/?username=demo&password=de mo

2.9 HTTP API Responses

As described above the response you receive by the http API when you successfully submit a message is something like:

SUCCESS MessageId: 5093c47680aa7-5267-87898; Recipient:44201112345674

(13)

 ERROR:001; STATUS: Invalid username or password The provided username or password are invalid.  ERROR:002; STATUS:Invalid User Type

This error stands for messages submitted from a non-http api account.  ERROR:003; STATUS:Out Of Credit

Insufficient account balance.  ERROR:004; STATUS:Inactive User

User Account is not activated.  ERROR:005; STATUS:Blocked user

User Account is blocked.

 ERROR:007; STATUS:PARAMETER (to) MISSING Parameter to (msisdn) is missing.

 ERROR:008; STATUS:PARAMETER (from) MISSING Parameter from (sender ID) is missing.

 ERROR:009; STATUS:PARAMETER (text) MISSING Parameter text (message text) is missing.  ERROR:010;PARAMETER (username) MISSING

Parameter username is missing.

 ERROR:011;PARAMETER (password) MISSING Parameter password is missing.

 ERROR:012; STATUS:IP [127.0.0.1] NOT VALID

This error stands for messages submitted from a non-white-listed IP address.  ERROR:066; STATUS:Number Of MSISDN greater than 200

Number of MSISDNs greater than allowed.

 ERROR:067; STATUS:MSISDN must have only digits [msisdn] Parameter to contains alphanumeric characters.

 ERROR:068; STATUS:MSISDN [msisdn] too long Parameter to is longer than allowed.

(14)

2.10 Transport of National sender id message

You can submit messages followed by a national sender id .This Sender id is a number that includes only the national destination code which identifies the subscriber's operator followed by the mobile's subscriber's own number. There isn’t any specific procedure that the user must do in order to send a messages with a national sender id. The only requirement is to add parameter “&national =1”

For example:

http://api2.amdtelecom.net:8208/?username=demo&password=demo&from=069712 34567&to=44201112345678text=write your text here &national=1

2.11 Sending Multiple SMS via XML call

To send multiple SMS with the usage of XML call or XML file upload, the user must use the following format:

It starts with the tag '<?xml version="1.0" encoding="utf-8"?>' and all the parts ("head","body") are included inside "middle-msg-push" tag.

Where inside the "head" part we have: <?xml version="1.0" encoding="utf-8"?> <middle-msg-push> <head> <version>1.0</version> <login>username</login> <passwd>password</passwd> <type>0</type> <category>1</category> <schedule></schedule> <expire></expire> <sender>SenderID</sender> <service></service> </head>

 "login": the Username from the registration with AMD Telecom.  "passwd": the Password from the registration with AMD Telecom.  "sender": The SenderID inside each SMS (Numeric, Up to 16 chars |

Alphanumeric, Up to 11 chars).

 "category": values [0/1] (if "0" OR blanc => 7bit SMS, if "1" => Unicode SMS).  "type": values [0/1] (if "0" OR blanc => Normal SMS, if "1" => Flash SMS).

(15)

 "service": values [0/1] (if "0" OR blanc => International SMS(country code included), if "1" => National SMS(country code NOT included)).

 "expire": (ignore) pass as is.  "schedule": (ignore) pass as is.  "version": (ignore) pass as is. Where inside the "body" part we have: <body>

<message>

<idMsgRemote>xxxxxx1</idMsgRemote> <gsm>CCNNNNNNNN1</gsm>

<content>Message Message Message Message 11111</content> </message>

... <message>

<idMsgRemote>xxxxxxn</idMsgRemote> <gsm>CCNNNNNNNNN</gsm>

<content>Message Message Message Message nnnnn</content> </message>

</body>

</middle-msg-push>

"message": each message object

in message => "idMsgRemote": if user wants to have an ID for each message (optional) in message => "gsm": the MSIDN (phone number) WITH country code (CC = country code | NNNNNNNNN = phone number)

in message => "content": the message text (7bit:160 chars/SMS | Unicode:70 chars/SMS)

How to make the call Use the URL:

http://api2.amdtelecom.net:8208/xmlcall.php

Either pass the XML as a POST call to the above URL or Upload an XML file to the above URL. EXAMPLE: <?xml version="1.0" encoding="utf-8"?> <middle-msg-push> <head> <version>1.0</version>

(16)

<login>username</login> <passwd>password</passwd> <type>0</type> <category>1</category> <schedule></schedule> <expire></expire> <sender>SenderID</sender> <service></service> </head> <body> <message> <idMsgRemote>0018109581</idMsgRemote> <gsm>34637448867</gsm>

<content>Info Privilege: BEATRIZ, te recordamos que si aun no lo has utilizado, dispones de tu Cheque Privilege por valor. Puedes utilizarlo como dto. en la compra de cualquier producto. Solo hasta el 30/06/2013. Muestra sms en tienda. Condiciones en /pv</content>

</message> <message>

<content>Info Privilege: JORDI, te recordamos que si aun no lo has utilizado, dispones de tu Cheque Privilege por valor de. Puedes utilizarlo como dto. en la compra de cualquier producto. Solo hasta el 28/06/2013. Muestra sms en tienda. Condiciones en /pv</content>

<content>Info Privilege: PILAR, te recordamos que si aun no lo has utilizado,

dispones de tu Cheque Privilege por valor de . Codigo: . Puedes utilizarlo como dto. en la compra de cualquier producto. Solo hasta el 30/06/2013. Muestra sms en tienda. Condiciones en /pv</content>

<content>Info Privilege: ORIOL, te recordamos que si aun no lo has utilizado,

dispones de tu Cheque Privilege por valor de . Codigo: . Puedes utilizarlo como dto. en la compra de cualquier producto. Solo hasta el 24/06/2013. Muestra sms en tienda. Condiciones en /pv</content>

(17)

<content>Info Privilege: INES, te recordamos que si aun no lo has utilizado, dispones de tu Cheque Privilege por valor de eur. Codigo: . Puedes utilizarlo como dto. en la compra de cualquier producto. Solo hasta el 12/06/2013. Muestra sms en tienda. Condiciones en /pv</content>

<content>Info Privilege: FERRAN, te recordamos que si aun no lo has utilizado, dispones de tu Cheque Privilege por valor de eur. Codigo: . Puedes utilizarlo como dto. en la compra de cualquier producto. Solo hasta el 30/06/2013. Muestra sms en tienda. Condiciones en /pv</content>

<content>Info Privilege: SILVIA, te recordamos que si aun no lo has utilizado, dispones de tu Cheque Privilege por valor de eur.. Puedes utilizarlo como dto. en la compra de cualquier producto. Solo hasta el 25/06/2013. Muestra sms en tienda. Condiciones en /pv</content>

<content>Info Privilege: M. ANGELES, te recordamos que si aun no lo has utilizado, dispones de tu Cheque Privilege por valor. Codigo:. Puedes utilizarlo como dto. en la compra de cualquier producto. Solo hasta el 13/06/2013. Muestra sms en tienda. Condiciones en /pv</content>

<content>Info Privilege: ANNA MARIA, te recordamos que si aun no lo has utilizado, dispones de tu Cheque Privilege por valor de eur. Codigo:. Puedes utilizarlo como dto. en la compra de cualquier producto. Solo hasta el 20/06/2013. Muestra sms en tienda. Condiciones en /pv</content>

</message> </body>