Table of Contents Introduction... 2 Requirements... 2 Connecting to Forthnet Mobile Platform... 2 Message submission... 3 Client Request... 3 Parameters... 4 Parameter user... 4 Parameter pass... 4 Parameter sender... 4 Parameter dest... 5 Parameter message... 5 Parameter not... 6 Server Response... 6 Delivery Notifications... 7 Parameters... 8 Parameter type... 8 Parameter msgid... 8 Parameter status... 8 Parameter timestamp... 9 References... 9 Forthnet Mobile Platform - groupsms http interface v1.0 1 / 9
Introduction The current document describes in detail the HTTP interface provided by Forthnet Mobile Platform for Short Message Service messages (SMSes) submission. The interface enables client applications to send SMSes to subscribers of mobile networks by conveying the message data in requests according to the HTTP protocol (for further information on the HTTP protocol please refer to [1] in References). The requests are received and parsed by the server and the appropriate SMSes are generated and delivered to the mobile subscribers. The Forthnet Mobile Platform supports only text SMSes for the time being. In addition, the Forthnet Mobile Platform supports delivery notifications, i.e. messages that convey the status of SMS transmission (e.g. confirmation that the SMS has been received by the recipient s handset). If a customer is enabled to use this feature, he can request delivery notifications on per SMS basis. If a submitted SMS requests for delivery notifications, the notifications related to the message are collected from the mobile network and are forwarded via HTTP to the client s server. Towards this, a client that desires the delivery notifications feature must provide to Forthnet his server details (i.e. the URL of the page that handles the notifications on the client s server) when his account is going to be activated. The Forthnet Mobile Platform supports both GET and POST methods for HTTP requests submission. This document describes the communication with Forthnet Mobile Platform for: SMS submission via HTTP GET requests, and Notifications Forwarding via HTTP GET requests. Requirements The Forthnet Mobile Platform Bulk SMS http interface doesn t impose any requirements on the operating system (MS Windows, UNIX, Linux, etc.) of the machine where the client application runs. On the contrary, the client application must only support the ability to send standard HTTP GET or POST requests. In addition, in order a user to be allowed to send SMSes via the interface, he must have an account. Connecting to Forthnet Mobile Platform In order a client application to send an HTTP request to the Forthnet Mobile Platform, it has to establish a (TCP/IP) connection with the server. The server s address is the following: http://athost:atport/smsc/insms NOTE: The AThost and ATport information are revealed upon the purchase of the service. Forthnet Mobile Platform - groupsms http interface v1.0 2 / 9
Message submission Client Request In order to submit an SMS using the GET HTTP method, a URL in the following format must be generated: http://athost:atport/smsc/insms?param1=value1¶m2=value2&...¶mn =valuen Example URL http://athost:atport/smsc/insms?dest=%2b306977666777&sender=myname&message=ha ve+a+nice+day&user=demo&pass=demo Toward this, the client application must connect to the server (AThost:ATport) and send a GET request (formatted as follows): GET /smsc/insms?param1=value1¶m2=value2& ¶mn=valuen HTTP1/1\n Host: AThost:ATport\n \n (Three lines total. It is mandatory to send the third blank line) Please note that the values of the parameters must be URL encoded (see [2] in References). So, the value %2B306977666777 of parameter dest in the above example URL is the encoding of +306977666777. The following table presents some special character mappings according to URL encoding: Character URL encoding & %26 + %2B % %25 # %23 Blank space %20 = %3D? %3F ; %3B \n %0D Forthnet Mobile Platform - groupsms http interface v1.0 3 / 9
Parameters Table below contains a list of available parameters: Parameter Description M/O Type Valid Values / Limitations user Account username M String - pass Account password M String - sender Message sender O 1 Numeric or String dest Message destination(s) M Comma separated numstring list If it's a numeric sender of type shortcode we expect 3-6 digits length. If it s an alphanumeric sender we expect up to 11 latin chars (space included). If it s an MSISDN sender we expect it in international format starting with +. One up to 100 target MSISDNs in international format (starting with + ), i.e. +442345234553, +1432545543 message Message Body O 2 String Max 160 chars Message Boolean or The Boolean values true/false or the Integer not notification O Integer values 0, 1, 2 or 3 indicator NOTE 1: Parameters user, pass, sender, dest and message are mandatory while parameter not is optional. Here is an explanation on how you should use these parameters. Parameter user (mandatory) The client s assigned username. Parameter pass (mandatory) The client s assigned password. Parameter sender (mandatory) The originator of the message. Could be either numeric (maximum 20 characters) according to the international GSM format (only the format with the leading plus is allowed, i.e. +306972112233) or alphanumeric (maximum 11 characters). Forthnet Mobile Platform - groupsms http interface v1.0 4 / 9
Examples sender=54546 sender=forthnet sender=+306972112233 Parameter dest (mandatory) The dest parameter is used to specify the destination GSM number(s) of the SMS. A comma-separated list could be used to specify more than one destination number. The maximum allowed number of destinations is 100. Each destination number must not be longer than 20 characters and it must be written in international format with the leading plus sign (e.g. the greek GSM number 6972112233 must be written as +306972112233). The 00 international format (e.g. 00306972112233) is not allowed for this field. Example (one destination) dest=+306977666777 Example (multiple destinations) dest=+306977666777,+306977666778 Please note that according to the URL encoding, the plus character ( + ) corresponds to %2B. So if +306976667788 is to be used as message destination, it must be encoded as %2B306976667788. Parameter message This parameter sets the Short Message text. Its length must not exceed the limit of 160 characters. The allowed characters can be: 1. All uppercase or lowercase Latin letters 2. All uppercase or lowercase Greek letters 3. All decimal digits 4. Characters `~!@#$%^&*()_+-={} []\: ; <>?,./ Forthnet Mobile Platform expects the value of message parameter in UTF-8 encoding. Of course, since it s on URL it must be URL-escaped, i.e. special characters like the ones shown in the table above must be transformed according to URL-encoding. Forthnet Mobile Platform - groupsms http interface v1.0 5 / 9
Parameter not (optional) If this parameter is used with true value, then delivery notifications are requested for the corresponding SMS according to client s account configuration. The default value of parameter not is false. If a user that is not enabled to use the delivery notifications feature sets this parameter as true, the message will be sent but no delivery notification will be submitted. Server Response Upon the receipt of an SMS submission request, the server parses the parameters, performs the required checks and sends back a response. The information regarding the submission status is propagated in the first line of the response body. It includes a status code and a status description. The possible values of the (Code, Description) pair are presented in the table below. If the not parameter is enabled, then the response includes an additional line ( msgid= ) with a message id (whose type is String). This message id must be used to correlate delivery notifications with sent messages (see Delivery Notifications section bellow). If a message has multiple recipients, then a (comma-separated) list of message ids is returned. Each message id corresponds to an SMS sent to one of the recipients. The message ids correspond to the message destinations according to the order that the destinations were contained in the destination list of the request. So, if a valid message submission request with dest=+306977666777,+306977666778 generates a response with msgid=1234,1235 then 1234 is the msgid that corresponds to the SMS sent to the first recipient ( +306977666777 ) while 1235 corresponds to the SMS sent to +306977666778. A sample server response (including the message id information in the body) is the following: HTTP/1.1 200 OK\n Content-Type: text/plain; charset=iso-8859-1 Content-Length: 23 \n \n 001 OK\n msgid=1343,1344\n Forthnet Mobile Platform - groupsms http interface v1.0 6 / 9
The possible (Code, Description) values included in a server response are shown in the following table: Status Code Status Description 001 OK 101 Missing Parameter 102 Illegal Parameter 103 Invalid SMS Number Format 104 Internal Server Error 105 Unauthorized User 106 Unauthorised IP Address 107 Account Disabled 108 Max Message Length Exceeded 109 Invalid Message Text Delivery Notifications Upon the receipt of a delivery notification, Forthnet Mobile Platform will forward it to the specified client s server. Towards this, an HTTP GET request of the following format will be generated and forwarded to the client s server: GET /customer_page?type=2&msgid=id&status=stat×tamp=t HTTP/1.1\n Host: CustomerServerHost:CustomerServerPort\n \n Example GET /not.php?type=2&msgid=1234&status=smscrcv×tamp=2008-02- 08+23%3A56%3A32.333 HTTP/1.1\n Host: 123.123.11.3:80\n \n The client script must reply by using a string which begins with OK or NOK. Otherwise, the server will continue to send the message assuming that the initial attempt was unsuccessful. Forthnet Mobile Platform - groupsms http interface v1.0 7 / 9
Parameters An overview of the parameters contained in a delivery notification HTTP Request is shown in the following table. Please note that all parameters are mandatory and will always be included in the HTTP Request. Parameter Type Possible Values / Comment type Integer always set to 2 msgid String - status String delivery notifications: SMSCRCV SMSCRJT HSRCV HSRJT SMSCFWD SMSCEXP timestamp String yyyy-mm-dd HH:mm:ss.SSS Parameter type This parameter has always the value 2 when the HTTP Request contains a delivery notification. It is used in order the customer s server to able to distinguish notifications from MO SMSes that might be as well forwarded via HTTP GET requests (which have the parameter type set to 1, for more information see [3] in References) to the same page of the client s server. Parameter msgid The parameter msgid identifies the SMS sent by the client that the delivery notification refers to. It is the msgid value that customer collected on the MT submission. Parameter status The status field contains information regarding the status of the transmission of an SMS. As mentioned above, two types of notifications are supported, delivery notifications and billing ones. The latter are valid only in the case of MT billing SMSes. The delivery notification statuses supported are: SMSCRCV denotes that the SMS was received by the SMSC that serves the destination handset. SMSCRJT declares that the SMS was rejected by the SMSC, i.e. due to invalid destination number. HSRCV means that the SMS was successfully delivered to the recipient s handset. HSRJT refers to the case of unsuccessful delivery, for reason other than expiration of validity period. Forthnet Mobile Platform - groupsms http interface v1.0 8 / 9
SMSCFW deals the case where an SMS has to be forwarded from the operator that was chosen to submit it, to another operator to which the subscriber belongs. SMSCEXP denotes the case where the SMS validity period has expired. Parameter timestamp The exact timestamp when the notified event occurred in YYYY-MM-DD HH:MM:SS.SSS format. NOTE: All notification timestamps are in UTC. References [1] RFC 2616: Hypertext Transfer Protocol HTTP/1.1 [2] RFC 1738: Uniform Resource Locators (URL) [3] Forthnet Mobile Platform - Premium SMS http interface Forthnet Mobile Platform - groupsms http interface v1.0 9 / 9