Multi-message submit

Added by Anders Lindh, last edited by Anders Lindh on Aug 11, 2008  (view change)
Space Search
Searching Messaging API
Table of Contents
1. Introduction

The standard GET/POST API is limited to submitting the same content to one or more recipients, and in cases where big amounts of MT messages (with varying content) need to be submitted, a unique request must be made for each recipient and message. This quickly becomes a bottleneck, and multiple threads that submit messages need to be put in place in order to achieve the required performance. To overcome this complexity, the API has been extended to accept a submit request in XML format where multiple recipient each with unique content and attributes can be specified. 

This extension is configured on a per account basis. Please check with Roottori support that your account is configured for multi-message submit.
2. Multi-submit API endpoint

Multi-submit requests are submitted to the same URL as in the GET/POST variant:

http://gw1.roottori.fi/eapi/push

The HTTP request method must be POST, the content-type of the request must be signalled as "text/xml" using the content-type header. Authentication information is passed using the request query string as in the GET/POST variant.  

3. Multi-submit XML document

The request body must contain a valid multi-submit XML document, that contains each individual message along with originators, recipients and message content. The document contains an "sms-message" element for each message, and it is recommended that no more than 100 sms-message element are included in one request. The DTD for the XML document is following:

<!ELEMENT submit-request (sms-message*)>
<!ATTLIST submit-request version CDATA #DEFAULT "1.0">
<!ELEMENT sms-message (recipient+, originator, data-coding-scheme, user-data, user-data-binary, user-data-header, delivery-receipt)>
<!ELEMENT recipient (#CDATA, mobile-network-code, mobile-country-code)>
<!ELEMENT mobile-network-code (#CDATA)>
<!ELEMENT mobile-country-code (#CDATA)>
<!ELEMENT originator (#CDATA)>
<!ELEMENT data-coding-scheme (#CDATA)>
<!ELEMENT user-data (#CDATA)>
<!ELEMENT user-data-binary (#CDATA)>
<!ELEMENT user-data-header (#CDATA)>
<!ELEMENT delivery-receipt (#CDATA)>

The allowed values for the different elements, along with additional notes and restrictions, are:

Element
Required
Description
recipient
Yes
The msisdn of the recipient, in international format (optionally prefixed with a "+" or "00"). Multiple recipients can be specified for a single sms-message element (one recipient element per recipient). 
The recipient element can contain the optional "mobile-country-code" and "mobile-network-code" elements. These specify said values for the recipient (these bypass the internal operator check, greatly increasing performance). Applications with big instantaneous submit batches must include these values when known for each recipient.
originator
Yes
The originator of the message. Max 16 digits or 11 alphanumeric characters (within the US-ASCII character set)
data-coding-scheme
No
As specified in GSM 03.38. Defaults to "0", i.e. plain text.
user-data
On of user-data or
user-data-binary is required
Plain-text user data encoded according to the document encoding.
user-data-binary

User data, hex encoded. 
user-data-header
No
The optional user-data-header of the message
delivery-receipt
No
Set to "1" to enable delivery receipts. Default "0", no delivery receipt requested.
4. Response

The response is returned identically as in the GET/POST API variant.

5. Example

An example of such document

<?xml version="1.0" encoding="UTF-8"?>
<submit-request>
  <sms-message>
    <originator>Roottori</originator>
    <recipient>
      +358400000001
      <mobile-country-code>244</mobile-country-code>
      <mobile-network-code>05</mobile-network-code>
    </recipient>
    <user-data>test 1, 2, 3, €</user-data>
  </sms-message>
  <sms-message>
    <originator>Roottori</originator>
    <recipient>+358400000001</recipient>
    <recipient>358400000002</recipient>
    <user-data>test 2: 1, 2, 3, €</user-data>
  </sms-message>
  <sms-message>
    <originator>Roottori</originator>
    <recipient>+358400000001</recipient>
    <user-data-binary>010603AEB48002056A0045C60D03726F6F74746F72692E66692F30313233343536373839302F3132333435363738393000110335383730393733313339000810C30720080811202031010342696E617279205741502D53492074657374000101</user-data-binary>
    <user-data-header>0605040B8423F0</user-data-header>
    <data-coding-scheme>04</data-coding-scheme>
  </sms-message>
</submit-request>

Labels

 
(None)