Integration Guide Xura Messaging HTTP-Interface

Transcription

1 Integration Guide Xura Messaging HTTP-Interface Version Content is subject to change Xura Secure Communications GmbH Tel.: : asc-support@xura.com All rights reserved. This product and related documentation are protected by copyright and under licenses restricting its use, copying, distribution and compilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorisation of Xura Secure Communications GmbH.

2 TABLE OF CONTENTS 1 REVISION HISTORY INTRODUCTION Setup and Connection Data Resource Management Sender Identification UCS2 Messages Timeouts Configuration URLs and Downloads Error Codes Mobile Networks HTTP INTERFACE DESCRIPTION SMS Outbound Parameters Text Messages UCS2 Encoded Messages WAP-Push Messages Transparent Messages Concatenated Transparent Messages Splitting of Overlong Messages HTTP Return Values Sample Messages SMS Inbound Parameter HTTP Return Values Delivery Notifications Notification Format HTTP Return Values Ping HTTP Interface LIST OF TABLES AND SAMPLES List of Tables List of Samples Page: 2 of 18

3 1 REVISION HISTORY Date Author Version Comment Frank Merten Revised version Robert Riesener Added http ping Robert Riesener Set udh to mandatory for transparent sms Frank Merten Changed interface URL Frank Merten Minor changes in introduction chapter. Changed interface URL Frank Merten Minor changes in chapter Frank Merten Changed contact information Frank Merten Added parameter Type to Delivery Notification Jakub Flis Added information about password encoding Table 1: Revision History Page: 3 of 18

4 2 INTRODUCTION Xura messaging service platform provides a secure and highly available messaging platform. It offers different messaging interfaces for sending and receiving messages. This document describes the Xura HTTP Interface and provides various examples. For general information such as character mapping and notification states please consult the Xura Messaging Interface Guide. 2.1 Setup and Connection Data The HTTP messaging interface supports sending and receiving of messages via the HTTP GET method. Xura provides customers with the interface URL, customer identification number (cid), a password, and a target URL used for the delivery of data via HTTP(S)-Request. 2.2 Resource Management Due to security reasons Xura uses an IP-address white-list. Each customer must provide their IP- Address to apply for a Xura HTTP account. If the maximum number of connections per IP address or of the system are reached, the system will reply with an HTTP status code 503 (system temporarily not available). In this case it is recommended to retry. Usually 10 parallel connections per IP address are allowed. 2.3 Sender Identification The sender identification can be either alphanumeric (maximum 11 characters) or numeric. Please note that numeric sender identification must always be in international format, e.g UCS2 Messages UCS2 messages are supported by the HTTP Interface. The message text must be supplied url-encoded with 16-bit encoding (2 Bytes per character), e.g. %00A%00B%00C 2.5 Timeouts Xura uses a HTTP timeout of 300 seconds. The HTTP protocol defines the timeout of an HTTP request. We recommend that clients use a higher value in their client implementation, as otherwise delayed responses may not be correctly evaluated. Page: 4 of 18

5 2.6 Configuration URLs and Downloads Configuration constants and network information can be download via HTTP GET requests. Note: All interfaces listed in this chapter are not designed to be accessed by runtime processes or to be used for batch SMS delivery. Xura may apply request throttling filters to restrict the access to less than 10 requests per second per remote IP at any time. There is no guaranteed response time for these types of requests Error Codes All interface error codes are available as HTML documentation online: be provided by Xura>/messagegateway/errorcodes/ Mobile Networks The keys for operator and service provider names can be accessed as XML documents by supplying the country parameter as a query argument: be provided by Xura>/messagegateway/config/networks/list/?country=DE The country parameter is mandatory. The values are the country ISO codes (with exception of Great Britain where UK is used). Example 1: Response for Germany (DE) be provided by Xura>/messagegateway/config/networks/list/?country=DE <?xml version="1.0" encoding="iso "?> <networks listcreated=" :34:55"> <operator key="vistream" name="vistream"/> <operator key="viag" name="o2"/> <operator key="landline" name="landline / Festnetz"/> <operator key="eplus" name="e-plus"/> <operator key="d2" name="d2-vodafone"/> <operator key="d1" name="t-mobile"/> <serviceprovider key="victorvox" name="victorvox"/> <serviceprovider key="phonehouse" name="phonehouse"/> <serviceprovider key="mobilcom" name="mobilcom"/> <serviceprovider key="debitel" name="debitel"/> </networks> Sample 1: Mobile Network List (DE) Page: 5 of 18

6 3 HTTP INTERFACE DESCRIPTION 3.1 SMS Outbound Parameters Parameter Type Description Example cid m Customer identification, numeric value 3512 password m Customer authorization, alphanumeric value. Same as other parameters it should be URL-encoded (using Percent-encoding) from m Originating numeric telephone number (with complete country code so that replies are possible, max. 20 characters). or Alphanumeric sender max. 11 characters or Short code to m Target numeric telephone number starting with the complete country code (max. 20 characters). content m Content of the SMS message. ASCII Message : URL-encoded Binary SMS : Hexadecimal coded messages in capital letters Secret, %24%26cr Free-SMS This%20is%20a%20tes t%20message EF version m Interface version. Current version targetformat o String describing the target SMS format: COMMON.1.1 : Text SMS (Default if not set) COMMON.1.2 : Flash SMS COMMON.1.3 : Transparent WAP.1.2 : WAP PUSH Service Indication myid o Alphanumeric ID that can be set by customers (max. 128 characters) jobid o Numeric ID that can be set by customers. Range from 0 to notification o Indicates if a delivery notification is requested. 0: Delivery Notification Off (Default if not set) 1: Delivery Notification On scheduletime o Formatted date (yyyymmddhhmmss) for delayed sms delivery at the given time. validitytime o The maximum live time (yyyymmddhhmmss) of the sms. If the recipient mobile phone is offline and the validity time is reached, the sms message will be deleted from the SMSC. This feature is only available if supported by the network operator. COMMON.1.1 ID Page: 6 of 18

7 Table 2: HTTP Outbound Parameter Definition Text Messages Using only mandatory HTTP Interface parameter a simple text message will be send to the mobile phone. A signle SMS Text message can have up to 160 chars. Messages with more than 160 chars are automatic splittet into multiple SMS message (See chapter: Splitting of Overlong Messages) UCS2 Encoded Messages Using the coding parameter, a text SMS (targetformat=common.1.1) can be UCS2 encoded. The message text must be supplied url-encoded with 16-bit encoding (2 Bytes per character), e.g. %00A%00B%00C. The coding parameters must set to UCS2. If the parameter targetformat is set it must have the value COMMON.1.1 which is also the default. Parameter Type Description Example targetformat o String describing the target SMS format. Can only set to: COMMON.1.1 (Default if not set) coding m String describing the coding of content: ISO : standard encoding (Default if not set) UCS2 : 16-bit ucs2 encoding Table 3: HTTP Outbound Parameter for UCS2 messages This parameter is only permitted if the target format is COMMON.1.1 COMMON.1.1 UCS2 Page: 7 of 18

8 3.1.3 WAP-Push Messages Parameter Type Explanation Example targetformat m String describing the target SMS format. Must be set to: WAP.1.2 WAP.1.2 content m Descriptive text of the WAP Push message Xura url m URL for WAP Push message (URL-encoded) Maximum number of characters: 255 myid o This field identifies the WAP Push message on the mobile device. If myid is not set, the URL serves as the Identifier. expirytime o This field determines the validity period of the WAP Push message on the mobile device. (YYYYMMDDHHMMSS). If this value is not specified, the value will be set at 24 hours after delivery. Table 4: HTTP Outbound Parameter for WAP Push Messages http%3a%2f%2fwap%2 Emindmatics%2Ede Link23b-mindmatics.de Note: For a WAP push message, the content parameter contains the description of the push SMS. The description is displayed on the mobile device when receiving the WAP push message.the URL must be delivered URL-encoded. Example URL: Example URL-Encoded: http%3a%2f%2fwap.mindmatics.de%2fcgi%2fscript.pl%3fid%3d14%26text%3dnew%2520picture The myid parameter is optional. It serves as a Service-Indication (SI) identifier, which enables a device to distinguish between different service indications. If it is not set, the url will be used as the identifier. The calculation of the message length depends also on the setting of the myid parameter. Length calculation without MyId: l(ascii) (ASCII) <= 94 Length of ASCII-Content 1 SMS (Signs sequences: will not be counted in url) l(ascii) > 94 ceil [ ( ( l(ascii) x 2 ) + 72) / 256] Table 5: Length Calculation without MyId Page: 8 of 18

9 Length calculation with MyId: l(ascii) (ASCII) <= 91 Length of ASCII-Content 1 SMS (Signs sequences: will not be counted in url) l(ascii) > 91 ceil [ ( ( l(ascii) x 2 ) + 78) / 256] Table 6: Length Calculation with MyId Transparent Messages The parameter targetformat=common.1.3 allows delivery of transparent messages to the HTTP interface. This way all possible SMS parameters, e.g. user data header, message class and content, can be set as desired. In the case of a long SMS, it is the client s responsibility to ensure that messages are split and that the user data header contains all the relevant information. Parameter Type Description Example targetformat m String describing the target SMS format. Must be set to: COMMON.1.3 udh m Custom User Data Header (UDH) in binary format. The UDH will be processed transparently; it is the client s responsibility to split long SMS. msgclass m Defines the SMS message class: Valid values are: -1: no value 0: Message Class 0 1: Message Class 1 2: Message Class 2 3: Message Class 3 binary m Specifies whether the content of the message is binary. Valid values are: binary = 1 ascii = 0 Table 7: HTTP Outbound Parameter for Transparent Messages COMMON Note: If concatenated SMS, such as ringtones or logos, are delivered individually by COMMON.1.3, it is not guaranteed that they will be delivered over the same network operator s SMSC. The result of this may be that the concatenated SMS do not reach the mobile device in the correct order. In order to avoid this problem, it is therefore recommended that the above described format, e.g. WAP.1.2 is used or that the SMS is delivered in a single request as described in the section above. Page: 9 of 18

10 3.1.5 Concatenated Transparent Messages In the case of concatenated transparent SMS delivery (COMMON.1.3.), it is possible to transmit the component parts of a single SMS in one HTTP request. The request parameters udh and content must be set multiple times for every single message part. The isbinary and msgclass parameters are equally valid for all parts of the SMS. The order of the parameters have to match up: the first udh will correspond to the first content, the second udh will correspond to the second content, etc. Most importantly, the number of udh parameters has to correspond to the number of content parameters. This option is recommended for sending transparent SMS Splitting of Overlong Messages Xura follows the GSM specifications for setting maximum message length. However, the actual delivery is dependent on the operator and the mobile phone involved. Longer messages will be sent with an internal sequence number. Normally, blocks of 153 characters are sent in the case of an ASCII message with more than 160 characters. The following tables show the maximum length for different types of messages and the maximum block length if the maximum single message length is exceeded. When coding binary SMS, 2 bytes are calculated per hexadecimal value. Hence this type of notation of the message length. The number of send messages will be returned in the HTTP-Response. Lengths for message types with automatic splitting Target format Max. single message length Max. message length for multipart SMS COMMON.1.1 COMMON COMMON.1.1 (UCS2) 70 (2 byte characters) 67 WAP.1.2 2*133 2*128 Table 8: TargetFormats for Automatic Splitting of Overlong Messages Lengths for message types without automatic splitting Target format Binary Maximum length COMMON UDH length < 128 and length ASCII Content <= 160 and ceiling( (Length UDH / 2) * 8/7) + length ASCII <= 160 COMMON UDH length < 128 and length Binary Content <= 140 * 2 and (Length UDH / 2) + (Length Binary Content / 2) <= 140 Table 9: TargetFormats without Automatic Splitting of Overlong Messages Page: 10 of 18

11 3.1.7 HTTP Return Values In response to their HTTP(S) Request, the customer receives a XML Document (HTTP response code 200) containing the information displayed in the following table. For global errors, the interface will generate an HTTP response unequal to 200, e.g. Service Unavailable (HTTP 503) Internal Server Error (HTTP 500) Receiving a successful result from Xura means that the message was accepted and queued. Tag Description Example <smsreport > </smsreport> <date> </date> <result> </result> <errorcode> </errorcode> <errormessage> </errormessage> <msgid> </msgid> <msgparts> </msgparts> Table 10: HTTP Response Tags Root-Tag which contains single return values. Tag which contains the date and time of delivery in the form of: YYYY-MM-DD HH:MM:SS Z Tag that shows whether the SMS was successfully (success) or unsuccessfully (error) delivered to Xura. Possible values: error or success. This tag contains a numerical code in case of an error (i.e. if the result tag returns error ). In case of an error this tag displays a detailed error message. In case of a success, this tag contains the unique message ID (GUID) of this message. The message ID is a string containing maximum 128 characters. For successful deliveries, this tag shows the number of message parts transmitted :00: success -70 maximum content length exceeded 2D67C865FB6FA25A9261C7 5E8D2F0F2B 1 Page: 11 of 18

12 Example of a successful delivery response (Content type: text/xml): <?xml version= 1.0 encoding= ISO ?> <smsreport> <date> :00: </date> <result>success</result> <msgid>2d67c865fb6fa25a9261c75e8d2f0f2b </msgid> <msgparts>1</msgparts> </smsreport> Sample 2: Successful Delivery Response Example of an unsuccessful delivery response (Content type: text/xml): <?xml version= 1.0 encoding= ISO ?> <smsreport> <date> :05: </date> <result>error</result> <errorcode>-70</errorcode> <errormessage>maximum content length exceeded</errormessage> </smsreport> Sample 3: Unsuccessful Delivery Response Sample Messages Text Message via Lynx Using lynx, the delivery of an SMS message via the web interface could be read as follows: lynx dump Xura URL>? version=3.0&cid=3512&password=secret&to= &from= &content= Dies+ist+ein+test Sample 4: Text Message via Lynx Text Messages Xura URL>? version=3.0 &cid=3512 &password=secret &to= &from= &content=dies+ist+ein+test Sample 5: Text Message Xura URL>? version=3.0 &cid=3512 &password=secret &to= &from= &content=this+is+the+euro+sign+%80 Sample 6: Euro sign in Messages Flash Messages Xura URL>? version=3.0 &cid=3512 &password=secret &to= &from= &content=dies+ist+ein+test &targetformat=common.1.2 Sample 7: Flash Message Page: 12 of 18

13 UCS2 encoded Messages Xura URL>? version=3.0 &cid=3512 &password=secret &to= &from= &content=%00t%00h%00i%00s%00+%00i%00s%00+%00a%00+%00t%00e%00s%00t &targetformat=common.1.1 &coding=ucs2 Sample 8: UCS2 encoded Message Transparent Messages Xura URL>? version=3.0 &cid=3512 &password=secret &to= &from= &content=024a3a6d39bd9165bdd5c ead197d4460a dc d c3125a092f DB54498A23049B824C3125A092F B3126D8A22C516828BC145A0A DC12720A22C49B824E414460A28D B414520A22C494424B212618A23000 &targetformat=common.1.3 &udh= &msgclass=3 &binary=1 Sample 9: Transparent Message Concatenated Transparent Messages Xura URL>? version=3.0 &cid=3512 &password=secret &from=0000 &to= &targetformat=common.1.3 &binary=1 &msgclass=3 &udh=4d c43004d454c4f44593a2a a a d0a454e443a494d454c4f4459 &udh=5e c57004d454c4f44593a2a a a a a d0a454e443a494d454c4f4459 &udh= c3b004d454c4f44593a2a a a a a d0a454e443a494d454c4f4459 &content= &content= &content= Sample 10: Concatenated Transparent Message WAP Push messages Xura URL>? version=3.0 &cid=3512 &password=secret &to= &from= &content=mindmatics AG &url=http%3a%2f%2fwww%2emindmatics%2ecom &targetformat=wap.1.2 Sample 11: WAP Push Message with URL Parameter Page: 13 of 18

14 3.2 SMS Inbound Parameter Xura forwards inbound messages via HTTP GET Request. Therefore the customers has to provide its URL. The basic URL must be less than 254 character. Xura also needs to know the timeout of the customers web server. The following table shows all standard parameters which can be forwarded. All HTTP GET parameter names can be customized. guid Parameter Type Description Example m Unique identifier of the message. The GUID can be used to refer to the message or track processing of the message. content m The content of the sms. Sound 1 coding to m m This parameter describes the encoding of a message depends on the SMS encoding we received from the mobile network. Possible values are: -ISO (default for standard text SMS) -BINARY -UCS2 Receiving number of the message (short code or longnumber). to_country m The country code of the short code number. DE from m The mobile phone number of the user sending the sms. The parameter can also be a encrypted number in some specific countries. from_country o The country of the originator msisdn. DE from_operator o The operator, as far as known. D1 from_serviceprovider timestamp o o The serviceprovider, as far as known. The serviceprovider can differ from the operator. The timestamp of a message is generated when a messages was received by Xura and is formatted according to RFC BFC5FE99CEEFEE3 5DD7FF2DADE9498 ISO DEBITEL keyword o Matched keyword of the MO message. Sound T12:59:40+02:00. udh o UserDataHeader of the message Table 11: HTTP Inbound Parameter Definition Example with standard parameter names: URL>?guid=34BFC5FE99CEEFEE35DD7FF2DADE9498&content=Sound%201&timestamp= &to=12345&to_country=de&from= Sample 12: Inbound Message with Standard Parameter Names HTTP Return Values A delivery is performed successfully if the Xura server receives the HTTP-Status Code 200 OK from the customer web server. If the customer web server does not send this status in time Xura will reattempt the delivery. The content of the HTTP-response will not be parsed and evaluated. Page: 14 of 18

15 3.3 Delivery Notifications Notifications are delivered by Xura via HTTP POST to the customer s web server. Therefore the customers has to provide its URL. The basic URL must be less than 254 character. An reply from the customer server must be sent within 300 seconds (timeout), otherwise the notification will be delivered again. The HTTP interface will forward the final delivery status to the client, such as Delivered, Expired, Undeliverable, etc. The delivery status will be encoded in the <errorcode> tag. The detailed error code will be encoded in the <detailederror> tag. For detailed information regarding possible notification states and errors see WP Xura Messaging Interface Guide Notification Format Tag Explanation Example <notificationreport> Root-tag, which contains the single return values <date> Time stamp containing the date and the time :51 of the arrival of the notification, having the format DDMMYYYY HH:MM:SS <result> Tag, which indicates if the SMS has been success successfully (success) or unsuccessfully (error) delivered by Xura. Possible values: error or success <errorcode> Contains the error code - only present in 1001 error case. <detailederror> Contains the detailed error code - only 007 present in error case. <errormessage> Contains an error message - only present in sms timeout error case. <msgid> Message ID of the original delivered MT 0C9270F5B00ACD01DC3F4AB28 message. <jobid> Numeric id, which can be set by the customer, 1234 when sending a MT message. If the jobid has not been set by the former delivery, this tag will not be present anymore <myid> Alphanumeric id, which can be set by the ABC1234DE customer, when sending a MT message. If the myid has not been set by the former delivery, this tag will not be present. <cid> Customer s numeric identification. 0 <recnbr> Msisdn, which has been set by the former SMS delivery. <type> This optional parameter defines whether the message was delivered as SMS message or as TRUSTEGO message. Possible values are SMS or TRUSTEGO. This parameter is only available when requested. TRUSTEGO Table 12: HTTP Notification Parameter Tags Page: 15 of 18

16 A notification always corresponds to a previously sent MT message. When a message has been sent successfully, a global unique identifier (msgid) will be included in the response. Note: For a concatenated message only one notification will be sent. Example for a successful DLN with type paramter: <?xml version="1.0" encoding="iso "?> <notificationreport> <date> :51:23</date> <result>success</result> <msgid>0c9270f5b00acd01dc3f4ab28dcd1442</msgid> <cid>0</cid> <recnbr> </recnbr> <type>sms</type> </notificationreport> Sample 13: Successful DLN without MyId and JobId Example for a successful DLN with MyId and JobId: <?xml version="1.0" encoding="iso "?> <notificationreport> <date> :51:23</date> <result>success</result> <msgid>0c9270f5b00acd01dc3f4ab28dcd1442</msgid> <jobid>1234</jobid> <myid>abc1234de</myid> <cid>0</cid> <recnbr> </recnbr> </notificationreport> Sample 14: Successful DLN with MyId and JobId Example for an unsuccessful DLN: <?xml version="1.0" encoding="iso "?> <notificationreport> <date> :51:23</date> <result>error</result> <msgid>0c9270f5b00acd01dc3f4ab28dcd1442</msgid> <cid>0</cid> <recnbr> </recnbr> <errorcode>1001</errorcode> <detailederror>007</ detailederror > <errormessage>sms timeout</errormessage> </notificationreport> Sample 15: Unsuccessful DLN without MyId and JobId Example for an unsuccessful DLN with MyId JobId: <?xml version="1.0" encoding="iso "?> <notificationreport> <date> :51:23</date> <result>error</result> <msgid>0c9270f5b00acd01dc3f4ab28dcd1442</msgid> <jobid>1234</jobid> <myid>abc1234de</myid> <cid>0</cid> <recnbr> </recnbr> <errorcode>1001</errorcode> <detailederror>007</ detailederror > <errormessage>sms timeout</errormessage> </notificationreport> Sample 16: Unsuccessful DLN with MyId and JobId Page: 16 of 18

17 3.3.2 HTTP Return Values A notification delivery is performed successfully if the Xura server receives the HTTP-Status Code 200 OK from the customer web server. If the customer web server does not send this status in time Xura will reattempt the delivery. The content of the HTTP-response will not be parsed and evaluated. 3.4 Ping HTTP Interface It is possible to check if the http interface is up and running by calling the following url. be provided by Xura>/messagegateway/ping.jsp be provided by Xura>/messagegateway/clientcertificate/ping.jsp Example of a ping result: <?xml version="1.0" encoding="iso "?> <pingreport version="3.1"> <date> :00: </date> <result>success</result> <msgid>994147b9e9378c e5828d0b69</msgid> </pingreport> Sample 17: Http ping result xml Page: 17 of 18

18 4 LIST OF TABLES AND SAMPLES 4.1 List of Tables Table 1: Revision History... 3 Table 2: HTTP Outbound Parameter Definition... 7 Table 3: HTTP Outbound Parameter for UCS2 messages... 7 Table 4: HTTP Outbound Parameter for WAP Push Messages... 8 Table 5: Length Calculation without MyId... 8 Table 6: Length Calculation with MyId... 9 Table 7: HTTP Outbound Parameter for Transparent Messages... 9 Table 8: TargetFormats for Automatic Splitting of Overlong Messages Table 9: TargetFormats without Automatic Splitting of Overlong Messages Table 10: HTTP Response Tags Table 11: HTTP Inbound Parameter Definition Table 12: HTTP Notification Parameter Tags List of Samples Sample 1: Mobile Network List (DE)... 5 Sample 2: Successful Delivery Response Sample 3: Unsuccessful Delivery Response Sample 4: Text Message via Lynx Sample 5: Text Message Sample 6: Euro sign in Messages Sample 7: Flash Message Sample 8: UCS2 encoded Message Sample 9: Transparent Message Sample 10: Concatenated Transparent Message Sample 11: WAP Push Message with URL Parameter Sample 14: Inbound Message with Standard Parameter Names Sample 18: Successful DLN without MyId and JobId Sample 17: Successful DLN with MyId and JobId Sample 20: Unsuccessful DLN without MyId and JobId Sample 19: Unsuccessful DLN with MyId and JobId Sample 21: Http ping result xml Page: 18 of 18