AMD Telecom SMS GATEWAY HTTP API INTERFACE. Technical Specifications

Transcription

1 AMD Telecom SMS GATEWAY HTTP API INTERFACE Technical Specifications Page 1

2 Contents 1. Introduction Scope of Document Introduction to HTTP2SMS Requirements Technical description Functionality Parameter...3-4e Alphanumeric Originator Address Code Account blocking due to multiple invalid HTTP requests Transport of text messages Transport of text-messages in the form of flash SMS Transport of UTF-8 encoded text messages Dispatching the delivery report By requesting the delivery report from our API By setting up a callback URL Description of the Code retrieved by the delivery report API Delivery receipts via the web-interface Description of the Error Code (errorcode, errortext) Throughput limitation Character Support Retrieving Balance through API HTTP API Responses Transport of National sender id message Sending Multiple SMS via XML call.14 Document Information Prepared By: [ADEA] Project Id: [n/a] Document Ref: [n/a] Date: [ ] Page 2

3 1. Introduction 1.1 Scope of Document Introduction to HTTP2SMS SMS Messages can be transmitted using HTTP protocol. Information about our services can be found on: 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: Technical description 2.1 Functionality Data is transferred using HTTP-GET requests. AMD Telecom s messaging system accepts requests at the following URLs: or for additional security enhancement for the interconnection HTTPS is also possible: Parameters Username: alphanumeric ie: demo (Username provided by AMD Telecom) Password: alphanumeric ie: demo (Password provided by AMD Telecom) From: Numeric: up to 15 characters - Alphanumeric: up to 11 characters Page 3

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 , , 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)) 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 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: lecom&to= &text=this%20is%20a%20test%20sms The above example sends the message: This is a test SMS to the following number with the originating alpha sender id AMD Telecom, using username demo and password demo, an account active at AMD Telecom s messaging platform. Page 4

5 The response for the previous request will be: SUCCESS Message Id: 5093c47680aa ;Recipient: Sending Multiple SMS via one POST/GET function Example : lecom&to= , , , &tex t=this%20is%20a%20test%20sms The previous example sends the message: This is a test SMS to the following numbers , , 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: 5093c47680aa ; Recipient: SUCCESS MessageId: 5093c4c4401d ; Recipient: SUCCESS MessageId: 5093c4ef41bc ; Recipient: SUCCESS MessageId: 5093c57d6638e ; Recipient: 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) 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: lecom&to= text=This%20is%20a%20test%20SMS&flash=1 The flash SMS appears on the terminal display as soon as it ś 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. Page 5

6 You can find a complete list of UCS-characters at: 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: lecom&to= text=официальные%20информационныеисточники%2 0органов%20государственнои %20власти%20России скои &coding=2 2.5 Dispatching the delivery report 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: lecom&to= text=this%20is%20a%20test%20sms The reply received is: SUCCESSMessageId: 5093c47680aa ; Recipient: Sample request of the delivery receipt for the above example: d=509a1bc The reply received is: {"Tracking":[{"ID":"509a1bc ","EID":"38c933cb-353f-4166-b5c a2","MSISDN":" ","Code":"007","Description":"Delivered","Trac keddate":" :00:50","MccMnc":"27402","Country":"Iceland","Operator":"Vodafone"}]} or {"Tracking":[{"ID":"509b653372b3c ","EID":[{"1":"1cd852d1-f8d3-43ca- 86eb d9fb5d"},{"2":"48b903de-fd3b-4a8b-a849-3f23df7cc4f5"},{"3":"96b00b7f- 793d-4c3a-a fd9ed4e"}],"MSISDN":" ","Code":"007","Description":"Delivered","T Page 6

7 rackeddate":" :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 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: 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: 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) sender (the Sender ID) Page 7

8 ie: id=509a1e58c & submitdate= & donedate= &status=007& errorcode=000& errortext=&txtstatus=delivrd&msgparts=1&receiver= &sender=userid Description of the Code (status) retrieved by the delivery report API. Status status: [004] Accepted by SMSC Intermediate status: [022] Unknown Subscriber status: [005] Call Barred status: [021] Unexpected data value status: [006] Controlling MSC failure status: [007] Delivered status: [009] HLR Aborted status: [018] Rejected by SMSC status: [020] Unavailable while roaming to status: [999] Uncategorized Status Page 8

9 status: [001] Absent Subscriber Interm/ status: [003] Accepted Intermediate 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) Description of the Error Code (errorcode, errortext) retrieved by the internal system. Status errorcode: [000] errortext: [] No Error () errorcode: [013] errortext: [CALL_BARRED] The MSISDN is blocked () errorcode: [401] errortext: [OUT_OF_CREDIT] The MSISDN is blocked () 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: Page 9

10 abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ ΓΔΘΛΞΠΣΦΨΩ ù Éß ÆæÅåÇØøäÖö ñüäñà Ü #(%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 Page 10

11 $text = "This is a test message \n with various characters: ñüäñà. Κείμενο. &*@"; $url = " "&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 = " $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);......?> Page 11

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. 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: 5093c47680aa ; Recipient: Below are listed responses you might get while you attempt to submit a message. Page 12

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 [ ] 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. Page 13

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: &to= text=write your text here &national= 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). Page 14

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> <idmsgremote>xxxxxx1</idmsgremote> <gsm>ccnnnnnnnn1</gsm> <content>message Message Message Message 11111</content>... <idmsgremote>xxxxxxn</idmsgremote> <gsm>ccnnnnnnnnn</gsm> <content>message Message Message Message nnnnn</content> </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: 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> Page 15

16 <login>username</login> <passwd>password</passwd> <type>0</type> <category>1</category> <schedule></schedule> <expire></expire> <sender>senderid</sender> <service></service> </head> <body> <idmsgremote> </idmsgremote> <gsm> </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> <idmsgremote> </idmsgremote> <gsm> </gsm> <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> <idmsgremote> </idmsgremote> <gsm> </gsm> <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> <idmsgremote> </idmsgremote> <gsm> </gsm> <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> <idmsgremote> </idmsgremote> <gsm> </gsm> Page 16

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> <idmsgremote> </idmsgremote> <gsm> </gsm> <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> <idmsgremote> </idmsgremote> <gsm> </gsm> <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> <idmsgremote> </idmsgremote> <gsm> </gsm> <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> <idmsgremote> </idmsgremote> <gsm> </gsm> <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> </body> </middle-msg-push> Page 17