cellip CELLIPS SMS INTERFACE DESCRIPTION HTTP GET INNEHÅLLSFÖRTECKNING

Transcription

1 INNEHÅLLSFÖRTECKNING Innehållsförteckning Introduction Scope HTTP Get interface Mobile Terminated Messages Usage Parameters Codes Delivery Reports Pull Mobile Originated Messages Usage Pull Codes HTTP Secure Server Hostnames And Posts Transaction Rate Limit URI Encoding Examples Mobile terminated messages Send a sms Send a flash sms Send a sms with alphanumeric sender Send a sms with åäö Send a binary sms Mobile originated messages Pull Delivery reports Pull Appendix Terminology URL Encoding Page 1 of 11

2 1 INTRODUCTION 1.1 SCOPE This document describes the Cellip SMS HTTP GET Interface. It describes the basics of how to use the HTTP GET Interface (from now on referred to as Interface ) and provides a list of available parameters. This document is intended for application developers and/or integrators. Basic knowledge of the HTTP protocol is assumed 1. 2 HTTP GET INTERFACE 2.1 MOBILE TERMINATED MESSAGES USAGE To send a message using the interface, the client creates and sends a HTTP GET request containing both login credentials and information regarding sender, the actual message and its recipient(s). The fact that login credentials are used in every single request eliminates the need of separate login and logout requests to setup and tear down sessions. The URL is constructed using the server hostname and ports given below together with this path: cgi-bin/sendsms Upon reception of the GET-request Cellip SMS validates the credentials and parameters. If all checks are passed Cellip SMS responds with a 202 Accepted and then proceeds to send the message to the given mobile subscriber. Should there be anything wrong with the request, it will be rejected and a response is sent back to the client indicating the nature of the error, please see section of codes below. If a delivery report is requested, a GET-request will be sent from Cellip SMS to the client indicating the outcome of the message. Cellip SMS will authenticate itself using a username and a password, if such credentials have been previously configured for the client. It s strongly recommended that the client uses SSL-encryption to secure the connection. If desired, Cellip SMS can also use SSL-encryption when sending delivery reports back to the client PARAMETERS The table below lists available parameters for MT-messages. Parameters not marked as Mandatory can be left out of the request. Other parameters must be present or the request will be rejected. All parameters must be URL encoded 2. Page 2 of 11

3 Name Mandatory Example User Yes Username of client. User=myuser Pass Yes Password of client. Pass=mypassword To Yes Recipient of the message, specified as MSISDN number in International format with preceding + character. Multiple recipients can be given in a single request. Multiple recipients must be separated by ;. From No 3 Sender of message. If not specified this parameter defaults to client preset name or number. Maximum of characters accepted depending FromType: To= To= ; ; From= From=MyCompanyAB N = 15 characters I = 15 characters S = 6 characters A = 11 characters Only characters 0-9 and + is allow for FromType N, I and S. Characters 0-9, A-Z, a-z and whitespace are allowed for FromType A. FromType No Format of the From -parameter. Defaults to I =International. Available formats are N =National, I =International, S =Short and A =Alphanumeric. Msg Yes The actual message. If message type is binary this parameter should be given in hexadecimal form. MsgType No Message type. 0 =Text, 1 =Flash, 3 =Binary. Defaults to 0. Additional messages types will be available in later release. FromType=I, FromType=N, FromType=A, FromType=S Msg=Hello+world MsgType=0 DLR No Delivery Report requested. 0 =NO, 1 =YES. Defaults to 0. DLR=1 RouteType No Route Type. Specifies routing rule. Currently only Standard is available. RouteType=Standard Extld No External Id. For future use. ExtId=MyId VP No Validity Period. Number of minutes that message is valid. Defaults to 4320 minutes (3 days). Maximum value is minutes. FDA No First Delivery Attempt. The preferred time when message delivery should first be attempted. The parameter is given in absolute time. TZ No Time Zone. Specifies in which time zone the FDA-parameter time is given. Defaults to Europe/Stockholm. See appendix 4.4 for a list of available time zones. UDH No User Data Header. This parameter is given in hexadecimal form. For advanced users. For future use. DCS No Data Coding Scheme. The parameter is used when message type is binary. Acceptable values are VP=1440 FDA= %3a00%3a00 TZ=Europe%2FLondon UDH=050003FF0201 DCS=0 ER No Enable reply. 0 =NO, 1 =YES. Defaults to 0. For future use. ER=1 Prio No Message priority, ranging from 1 (highest) to 3 (lowest). Defaults to 2. For future use. Prio=1 Page 3 of 11

4 Charset No Characters Set. Specifies the character set for the message of the request. Defaults to ISO See appendix A for supported character sets. Concat No Concatenate 0 =NO, 1 =YES. Set to 1 if message that results in more than one SMS should be concatenated by the end user terminal. Defaults to 1. MaxMsgs No Maximum messages. Defaults to 10 = maximum 10 SMS. If the value is 0 unlimited messages can be sent. This parameter only applies if Concat= 1. CharSet=ISO Concat=0 MaxMsgs=3 1 Hypertext Transfer Protocol HTTP/1.1 RFC Uniform Resource Identifiers (URI): Generic Syntax, RFC Note that a default From-parameter must be configured in the system to be able to leave this parameter out RESPONSE CODES This is not an exhaustive list of response codes, but the one most likely to be returned. 202 Accepted for delivery Message has been accepted for delivery. 400 Bad Request The request is malformed. 403 Forbidden Invalid credentials. 409 Rate Limit Exceeded Rate limit exceeded. In addition to the response code a text description and a unique id is given in the response body, see the examples below DELIVERY REPORTS Delivery reports are not sent to the customer per default. To obtain the outcome of a MT-message the user has to pull the status of specific MT-messages at their own discretion PULL The client can pull the status of a MT-message at any time. To do this, the client creates and sends a HTTP GET request containing both login credentials and the transaction id(s) of the MT-message(s). Multiple transaction ids may be given in a single request. If multiple transaction ids are sent, they must be separated by a ;. The URL is constructed using the server hostname and ports given below together with this path: cgi-bin/getmessagestatus The table below specifies the parameters for the pull request. Page 4 of 11

5 Name Mandatory Example User Yes Username of client. User=myuser Pass Yes Password of client. Pass=mypassword Transaction ID Yes Transaction ID of MT-message TransactionId=7ac00906-e9ec-4cbe-a806-ddab2cb4068b TransactionId=7ac00906-e9ec-4cbe-a806-ddab2cb4068b; 1ec e9ec-4cbe-a806-dd122cb4068b Cellip SMS will respond to this request with a 200-response and a body containing the status of the MTmessage. The result is given in JSON-format. Cellip SMS will respond with a result and a status code for each transaction id given in the request. The examples below show the difference between using a single and multiple transaction IDs. Result Status Code 1 1 The message has been successfully delivered. 2 1 The message could not be delivered. 2 2 The message could not be routed by Cellip SMS. 2 3 The message could not be delivered before the validity period expired. 2 4 Unknown transaction ID. 2 5 Internal error The message is pending. Examples when requesting status using a single transaction ID: { Result : 1, StatusCode : 1} { Result : 2, StatusCode : 4} Examples when requesting status using multiple transaction IDs: { Results : [{ TransactionId : 0e5d76c2-ca5a-4019-b5e2-08ab66cc101d, Result : 1, StatusCode : 1}, { TransactionId : eda0ae82-98d7-40b3-bbaa-205b68b63c0b, Result : 2, StatusCode : 4}]} { Results : [{ TransactionId : 0e5d76c2-ca5a-4019-b5e2-08ab66cc101d, Result : 1, StatusCode : 1}, { TransactionId : eda0ae82-98d7-40b3-bbaa-205b68b63c0e, Result : 1, StatusCode : 1}]}. 2.2 MOBILE ORIGINATED MESSAGES USAGE Using Cellip SMS it is possible to receive MO-messages to virtual numbers. To receive MO-messages, the user has to use pull, which means that the client will request the status of specific MO-messages at their own discretion. Page 5 of 11

6 When a message has been delivered to the client, it will be deleted from Cellip SMS. The responsibility for the message is thereby handed over to the client PULL The client can pull waiting MO-messages from Cellip SMS at any time. To obtain a list of waiting messages construct a GET request to this path: cgi-bin/getmessagelist The table below specifies the parameters for the request: Name Mandatory Example User Yes Username of client. User=myuser Pass Yes Password of client. Pass=mypassword The body of the response from Cellip SMS will contain a parameter specifying the number of messages waiting and zero or more transaction IDs. Examples of possible response bodies: { Result : 1, Messages : [{ TransactionId : aa c9f9-4b25-aa14-38dadfb8ef8e }, { TransactionId : 56ef83b9-a535-46ec-8511-bcb30370f51b }]} { Result : 1, Messages : []} Two messages (with transaction id aa c9f9-4b25-aa14-38dadfb8ef8e and 56ef83b9-a535-46ec bcb30370f51b) are waiting. No messages are waiting. A single message can then be retrieved using a specific transaction id together with a GET request to this path: cgi-bin/getmessageforid The table below specifies the parameters for the request: Name Mandatory Example User Yes Username of client. User=myuser Pass Yes Password of client. Pass=mypassword Transaction ID Yes Transaction ID of message to be retrieved. TransactionId=56ef83b9-a535-46ec bcb30370f51b Page 6 of 11

7 Example of possible response bodies: { Result : 1, From : Test, FromType : A, To : , ToType : I, Msg : Test, MsgType : 0, Timestamp : :02:01 } { Result : 2} A message from Test to number containing the message Test. Timestamp is given in UTC. The given transaction id is unknown. The client can also use a single request to directly retrieve a message, if there are any available. With this request the oldest message will be returned. cgi-bin/getnextmessage Name Mandatory Example User Yes Username of client. User=myuser Pass Yes Password of client. Pass=mypassword Example of possible response bodies: { Result : 1, From : Test, FromType : A, To : , ToType : I, Msg : Test, MsgType : 0, Timestamp : :02:01 } { Result : 3} { Result : 4} A message from Test to number containing the message Test. Timestamp is given in UTC. No more messages are waiting. An internal error occurred. The following result codes are used in getmessagelist, getmessageforid and getnextmessage. 1 No error. 2 The given transaction ID is unknown. 3 No more messages are waiting. 4 An internal error occurred RESPONSE CODES This is not an exhaustive list of response codes, but the one most likely to be returned. 200 OK The request has been successfully processed. 400 Bad Request The request is malformed. 403 Forbidden Invalid credentials. 409 Rate Limit Exceeded Rate limit exceeded. Page 7 of 11

8 2.3 HTTP SECURE Cellip SMS currently uses a certificate issued by CAcert Inc. for authentication. Unless not already done, the CAcert Inc. root certificate must be installed on the client system. For instructions on how this is done, please refer to SERVER HOSTNAMES AND POSTS This table defines which hostname and port to use for a selected service when submitting the GET-request. Please note that this information may be subject to change and that different information may have been provided along with the username and password. Service Hostname Port HTTP GET msgsms1..com?? HTTP GET using SSL msgsms1..com?? 2.5 TRANSACTION RATE LIMIT Clients may be configured with a transaction rate limit to ensure that Cellip SMS will not be overloaded. The limit is calculated as all client initiated requests per seconds, including all requests concerning both MO and MT-messages. When the rate limit is exceeded requests will be rejected with a 409 Rate Limit Exceeded -response. Once the client drops below the limit, Cellip SMS will again start processing requests. 2.6 URI ENCODING The Uniform Resource Identifier RFC 4 defines which characters are allowed in a URI. Two character sets are defined, reserved and unreserved. Reserved characters are defined as the set of characters that may have a special meaning in a URI. Unreserved characters do not have any special meaning. If a reserved character appears in a parameter this might break the format of the URI. Therefore all parameters must be encoded using percent-encoding before sent. If a character is not in either set (not reserved and not unreserved) it must also be percent-encoded. Refer to RFC3986 for a list of reserved/unreserved characters and how encoding/decoding is done. 4 Uniform Resource Identifiers (URI): Generic Syntax, RFC EXAMPLES 3.1 MOBILE TERMINATED MESSAGES SEND A SMS A complete URL for sending Hello World to the subscriber with number is given below. Pasting this URL into a web browser and pressing Enter creates the correct GET-request and sends it to the specified host and port. Page 8 of 11

9 If everything is correct the web browser will display a message similar to the one given below. Accepted for delivery, eda0ae82-98d7-40b3-bbaa-205b68b63c0b SEND A FLASH SMS The message is a flash SMS containing the message Hello World. = SEND A SMS WITH ALPHANUMERIC SENDER The message is sent from sender alphanumeric address Test SEND A SMS WITH ÅÄÖ The message contains åäö/åäö SEND A BINARY SMS The binary message contains Hello world f20776f726c64&udh=050003c80101&dcs=4 3.2 MOBILE ORIGINATED MESSAGES PULL Example of getnextmessage: Page 9 of 11

10 GET/cgi-bin/getnextmessage?TransactionId=&User=myuser&Pass=mypassword HTTP/1.1 Host: :12345 Accept-Encoding: identity Example of getmessageforid: GET /cgi-bin/getmessageforid?transactionid=eb6e7532-e e c2dadc1&user=myuser&pass=mypassword HTTP/1.1 Host: :12345 Accept-Encoding: identity Example of getmessagelist: GET /cgi-bin/getmessagelist?transactionid=&user=myuser&pass=mypassword HTTP/1.1 Host: :12345 Accept-Encoding: identity 3. DELIVERY REPORTS PULL The message below is an example of a GET-request sent to Cellip SMS, to request the status of transaction id bc757d8a-a0db-4e0d-a388-bf6d6eee0d87, which was delivered successfully. GET /cgi-bin/getmessagestatus?user=myuser&pass=mypassword&transactionid= bc757d8a-a0db-4e0da388-bf6d6eee0d87 HTTP/1.1 Host: :55520 Connection: keep-alive The message below is an example of a valid response to a delivery report. HTTP/ OK Server: Cellip SMS/svn Date: Thu, 09 Sep :10:20 GMT Content-Length: 31 Content-type: text/html Pragma: no-cache Cache-Control: no-cache { Result : 1, StatusCode : 1} Page 10 of 11

11 4 APPENDIX 4.1 TERMINOLOGY API HTTP Cellip SMS MSISDN MT MO Application Programming Interface Hypertext Transfer Protocol Cellip Comunication Platform Mobile Phone Number Mobile Terminated Mobile Originated 4.2 URL ENCODING The following specifies HTML URL Encoding Reference and introduction to URL encoding/url encoded strings. See and Page 11 of 11