sendsms.php. For optimal availability, your application should automatically
switch over to the second gateway-address, if the primary gateway is not
reachable.
AMD Telecom SMS GATEWAY
HTTP API INTERFACE Technical Specifications
Page 1
Contents
1. Introduction ......................................................................................... 3 1.1 Scope of Document............................................................................. 3 2. Technical description............................................................................. 4 2.1 Functionality........................................................................................ 4 2.2 Parameter............................................................................................ 4 2.3 Transport of text messages...................................................................6 2.4 Transport of UCS encoded text messages............................................. 7 2.5 WAP support........................................................................................ 8 2.6 Processing of delivery receipt............................................................. 10 2.7 Throughput limitation......................................................................... 12 2.8 System messages................................................................................ 12 3. Program examples ............................................................................... 12 3.1 Text messages sent through PHP-scripts............................................. 12 3.2 Transport of transparent Data SMS by PHP......................................... 12
Document Information Prepared By: [ADEA] Project Id: [n/a] Document Ref: [n/a] Date: [2009.10.03]
Page 2
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 Application Messaging: AMD Telecom’s Application Messaging customer account Sufficient credit on your AMD Telecom Application Messaging customer account Access to the AMD Telecom’s Application Messaging HTTP2SMS service is subject to our general terms and conditions of business. For more information, please address to: For questions regarding contracts & prices by email to:
[email protected] For technical questions by email to:
[email protected] For AMD Telecom’s technical hotline by telephone number: +30 239.40.20.336
Page 3
2. Technical description 2.1 Functionality Data is transferred using HTTP-GET/POST requests. AMD Telecom’s messaging system accepts requests at the following URLs: http://www.amdtelecom.net/api/sendsms.php or https://extranet.amdtelecom.net/api/ sendsms.php For optimal availability, your application should automatically switch over to the second gateway-address, if the primary gateway is not reachable. Only this can ensure optimal availability in an internet environment. The different gateway-addresses are located in different subnets. For sending UTF8 SMS like Russian, chinese, arab , special characters the usage of a different api is proposed: http://www.amdtelecom.net/api/sendsms_ext_charset.php or https://extranet.amdtelecom.net/api/sendsms_ext_charset.php 2.2 Parameter The following CGI-parameters are processed: Formal description of possible parameter values
Parameter Username
Value/Pattern alphanumeric
Sample demo
Password
alphanumeric
demo
From
Numeric: up to 16 characters Alphanumeric: up to 11 characters Numeric: International format. Country code included. You can also use comma separated MSISDN Text ISO-8859-1 (max. 160 characters) or Unicode
AMD Telecom
To
Text
44123456789,442 34567788,445434 53454543 This is my first test SMS
Description Username provided by AMD Telecom Password provided by AMD Telecom Numeric of alphanumeric originator for the SMS Destination MSISDN of the SMS
Text of the SMS
Page 4
Flash*
(if parameter encoding=ucs (max. 70 characters) Optional value,1
1
Generate the SMS as flash Validity period of the SMS. If not included, default will apply 24h. Configurable by the account manager Indicated of Unicode encoded SMS Binary SMS, encoded as hex string.
Validity*
Optional value: Value in seconds.
1000
Encoding*
Optional value : UCS Hex encoded Data including Data header indicated by „/“ [0-9AF]+/ [0-9A-F]+
Ucs
Data
01070605041582 00 00/62F22000480 E01 00000000111100 011 1FC79F8FE
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 more than 11 characters.
2.2.2 Account blocking due to multiple 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 10 incorrect password retry per SMS request. Your account will be blocked completely for X minutes.
Page 5
2.3 Transport of text messages The text parameter must be included in the text you need to send. Example: http://www.amdtelecom.net/api/sendsms.php?from=AMDTelecom&to=4420111234 5678&username=demo&password=demo&text=This+is+a+test+SMS The previous example sends the message: “This is a test SMS” to the following number +44201112345678 with the originating alpha sender id AMD Telecom, using username demo and password demo, an account active at AMD Telecom’s messaging platform. 2.3.1 Support for long messages (>160 characters) It is also possible for the client application to submit a message longer than 160 characters, the message will be split automatically into several SMS and be charged accordingly and send out as concatenated text messages. If the receiving phone is able to handle long messages, it will show the text as a single SMS. The reply for the above request will be: SUCCESS Message Id: 3380999; Cost: 0.80; Accepted for delivery; More details will be answered at 2.7 chapter Dispatching the delivery report.
2.3.2 Validity period With the parameter validity, the timestamp of the end of the validity period can be defined. If not set, the default value of the delivering SMSC is used (24 hours). The validity parameter, if set, is defined in minutes. Example: http://www.amdtelecom.net/api/sendsms.php?from=AMDTelecom&to=4420111234 5678&username=demo&password=demo&text=This+is+a+test+SMS&validity=1000 The previous example sends the message: “This is a test SMS” to +44201112345678 with a validity period overriding the default of 24h and is set to 1000 seconds.
Page 6
2.3.3 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 do not save the incoming flash SMS. Example: http://www.amdtelecom.net/api/sendsms.php? from=AMDTelecom&to=4420111234 5678&username=demo&password=demo&text=This+is+a+test+SMS&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, to use this feature you have to add the parameter encoding with the value ucs to your request and you have to encode your text according to UCS. The length of UCS-encoded text-messages is limited to 70 characters. You can find a complete list of UCS-characters at: http://www.unicode.org/charts/ Example: http://www.amdtelecom.net/api/sendsms_ext_charset.php? from=AMDTelecom&to=44201 112345678&username=demo&password=demo&text=официальные+информационные источники+органов+государственной+власти+Российской
Page 7
2.5 WAP support 2.5.1 Sending WAP Configuration (OTA) AMD Telecom’s Application Messaging System supports sending of WAP-configurations, the parameter wapconfig has to be filled with the following parameters: Wapconfig=name,url,proxy,proxyport,proxyauthname,proxyauthsecret,dialstring,auth type,authname,authsecret,calltype,speed,bearer,proxytype,smscaddress,ussdservicec ode,gprsapn,ispname,proxylogintype,logintype Description of Parameters name: Name of this WAP-configuration url: URL of startpage proxy: IP-address of WAP-Proxy proxyport: Type of connection 200: temporary (not encrypted) 201: continuous (not encrypted) 202: temporary (encrypted) 203: continuous (encrypted) proxyauthname: username for WAP-proxy proxyauthsecret: password for WAP-proxy dialstring: dialin-Number authtype: authentication protocol (pap (default) or chap) authname: username authsecret: password calltype: (analogue (default) or isdn) speed: connection-speed: 9600 (default), 14400,19200, 28800, 38400, 43200, 57600
Page 8
bearer: bearer-type, possible is gsm/csd (necessary parameters are proxy and dialstring), gsm/sms (necessary parameters are proxy and smscaddress), gsm/ussd (necessary parameters are proxytype, proxy and ussdservicecode), is-136/csd (necessary parameters are proxy and dialstring) and gprs (necessary parameters is proxy). If bearer is not specified, gsm/csd will be set. roxytype: msisdn_no or ipv4 mscaddress: number of the SMS-service-center ssdservicecode: USSD-service-code prsapn: GPRS-access-point ispname: name of provider (if the parameter ispname or the parameter name will be shown, depends on the cellular phone, normally it is sufficient to set ‚name’) roxylogintype: automatic or manual ogintype: automatic or manual
It depends on the cellular phone which parameters and bearer-types are supported. Example: http://www.amdtelecom.net/api/wap.php?from=AMDTelecom&wapconfig=WAP,htt p://wap.yourdomain.com,192.168.1.2,,,,12345,pap,user,pwd,isdn,,&to=44201112345 678&username=demo&password=demo&text=044d0442043e04420020043e04340438 043d00200442043504410442
2.5.2 Sending WAP-bookmarks AMD Telecom’s Messaging Platform supports the transmission of WAP bookmarks via SMS, the bookmark information must inserted at the wapbookmark parameter in the following format: wapbookmark=name,url name: name of the bookmark url: URL of the bookmar
Example (WAP bookmark): http://www.amdtelecom.net/api/wap.php?from=AMDTelecom& wapbookmark=AMDTelecom,http://www.amdtelecom.net&to=44201112345678&use rname=demo&password=demo This request sends a bookmark with the name „AMDTelecom” and the URL http://www.amdtelecom.net to phone number +44201112345678.
Page 9
2.5.3 Sending WAP-Push Service Indications AMD Telecom’s Messaging Platform includes a WAP-Push encoder, the CGI-Parameter “wappush” must be filled with the title and the WAP-URL of the service indication in the following format: wappush=title,wapurl title: will be shown on the handset (optional) wapurl: WAP-Url The WAP-Push encoder has been successfully tested with the following handsets: Sample WAP-Push: http://www.amdtelecom.net/api/wap.php?from=AMDTelecom&wappush =AMDTelecom,http://wap.amdtelecom.net&to=44201112345678&username=demo& password=demo This sample will send a WAP-Push with the title „AMDTelecom” to the MSISDN +44201112345678. If the service indication is activated, the phone will retrieve the WAP-Url „http://wap.amdtelecom.net“.
2.6 Dispatching the delivery report. 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 Application Messaging System. If needed, delivery receipts can be dispatched by the customer system via HTTPRequests. A unique message id is being assigned to each valid SMS being sent to AMD Telecom’s Application Messaging System. A delivery receipt can be requested using separate API. Sample on transport of text messages: http://www.amdtelecom.net/api/sendsms.php?from=AMDTelecom&to=4420111234 5678&username=demo&password=demo&text=This+is+a+test+SMS The reply received is:
Page 10
SUCCESS MessageId: 3380999; Cost: 0.80; Accepted for delivery;
Sample request of the delivery receipt for the above example: http://www.amdtelecom.net/api/delivery.php?username=demo&password=demo&i d=3380999 The reply received is: SUCCESS MessageId: 3380999; Status: 41; 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 our extranet : Account setting -> CallbackURL The format should be : http://my.server.com/delivery.php 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=3380999 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, keep in mind that our 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.
2.6.1 Explanation of the Status retrieved by the delivery report API. Status 32 40
41 42 44
Description SMS is accepted by the SMSC, but is not forwarded to the destination network SMS is received by the destination network, but no further information has been received by the target network (99% possibility of absent subscriber) SMS is delivered to the handset of the destination MSISDN SMS is not delivered due to unknown / invalid subscriber MSIDN SMS is sent to an absent subscriber. The target network stated
Status Intermediate Intermediate
Final Final Intermediate
Page 11
45
46
64
that the subscriber is either absent or in status call bared. SMS is delivered after the target network stated that the Final subscriber was primary absent while trying to terminate the SMS to his mobile phone SMS is not delivered to the handset of the destination MSISDN. Final High possibility of reaching the expiration time of the SMS sent. The MSISDN belongs to a valid subscriber but probably the subscriber had no signal at his mobile phone while trying to terminate the SMS, and the validity period is over The account balance is 0, and the SMS cannot be processed. Final Please purchase SMS capacity
Delivery receipts via the web-interface: If you are logged into AMD Telecom’s Application Messaging System customer area, you can retrieve a detailed delivery receipts by entering a phone number or the user key of the message. You find this interface in the menu Tracking SMStracking. ERRUSERAUTH 001 UNKNOWN (Unknown username or password) ERRUSERAUTH 002 INVALID (invalid request) ERRMSGNOTFOUND
2.7 Throughput limitation 2.7.1 Counting the throughput There is no throughput limit configured per account. The maximum number of allowed SMS per second depends on the connectivity lag between the requested IP and the messaging platform.
2.8 System messages The following feedback is released:
3. Program examples 3.1 Text messages sent through PHP-scripts 3.2 Transport of transparent Data SMS by PHP
Page 12
