HTTP XML API

Introduction

This document contains information required for Content Providers to send and receive SMS messages to mobile-phone subscribers using the TeletopiaSMS HTTP XML API Gateway interface. The interface is intended for developers and requires basic knowledge of HTTP and XML. To use this interface you will need a TeletopiaSMS Gateway account.

The interface is designed to allow a simple and robust implementation regardless of which platform the Content Provider decides to implement their solution.

In order to receive messages sent from end-users (MO or mobile originated) or delivery reports (DLR), the Content Provider must specify a URL, which is configurable through our service configuration web pages.

Advantages of using this API include:

• Supports both text and binary messages.
• Supports bulk and premium rate messages.
• Easy to integrate with your own solutions. Most programming languages have an API for making HTTP requests.
• Text messages containing non-GSM characters will be sent as Unicode (UCS2).
• Supports sending multiple messages per request.

Example of sending a message using the HTTP XML API:

$ netcat api1.teletopiasms.no 80
POST /gateway/v3/xml HTTP/1.1
Host: api1.teletopiasms.no
Content-Type: application/xml
Content-Length: xxx

<submitRequest>
<auth>
    <username>xxx</username>
    <password>xxx</password>
</auth>
<messages>
    <message>
        <recipient>4700000000</recipient>
        <contentText>
            <text>Hello World</text>
        </contentText>
    </message>
</messages>
</submitRequest>

The response from the gateway will be in the following format:

<submitResponse>
    <responses>
        <response>
            <accepted>1</accepted>
            <messageId>unique_message_id</messageId>
            <recipient>4700000000</recipient>
            <statusCode>1000</statusCode>
            <statusDescription>accepted</statusDescription>
        </response>
    </responses>
</submitResponse>

URLS

All TeletopiaSMS HTTP based API services are available as HTTPS (SSL encrypted) as well as HTTP. We recommend using HTTPS whenever possible as HTTP is mainly provided for compatibility with older systems.

Should the primary end-point become unreachable, we have backup end-points available. We encourage the Content Providers to design their systems to switch URL’s whenever they lose connection. Do not try to load-balance by sending round robin or random. Use secondary as a fallback if primary fails.

The available end-points are:

HTTP XML Requests

The HTTP XML API allows submitting multiple message per request. The XML message object must be submitted using HTTP POST requests. The Content-type for the request SHOULD be set to "application/xml".

SENDING MESSAGES TO END USER (MT)

This section describes the protocol used by the Content Providers to send SMS messages to mobile-phone subscribers, from here on referred to as MT or mobile terminated messages.

Structure of XML Submit Request Object for MT Messages

<submitRequest>
    <auth>
        <username></username>
        <password></password>
    </auth>
    <messages>
        <message>
            <clientRef></clientRef>
            <gateway></gateway>
            <senderType></senderType>
            <sender></sender>
            <recipient></recipient>
            <expire></expire>
            <sendTime></sendTime>
            <requestDlr></requestDlr>
            <price></price>
            <ageLimit></ageLimit>
            <serviceCode></serviceCode>
            <tag></tag>
            <contentText>
                <dcs></dcs>
                <text></text>
                <recodeText></recodeText>
            </contentText>
            <contentSmsText>
                <dcs></dcs>
                <pid></pid>
                <udh></udh>
                <text></text>
            </contentSmsText>
            <contentSmsBinary>
                <dcs></dcs>
                <pid></pid>
                <udh></udh>
                <ud></ud>
            </contentSmsBinary>
        </message>
    </messages>
</submitRequest>

Only one of contentText, contentSmsText and contentSmsBinary may be present in the message object.

Send Message Parameters

Send response

The success of the send request is determined by the HTTP status code. Status code 200 means success. Some important HTTP status codes:

Structure of XML Submit Response Object for MT Messages

<submitResponse>
    <responses>
        <response>
            <accepted></accepted>
            <clientRef></clientRef>
            <messageId></messageId>
            <recipient></recipient>
            <statusCode></statusCode>
            <statusDescription></statusDescription>
        </response>
    </responses>
</submitResponse>

Send Response Parameters

RECEIVING DELIVERY REPORTS FOR SENT MESSAGES (DLR)

This section describes the protocol used to receive delivery reports when using the HTTP XML API. The XML delivery report objects are sent as the body a HTTP POST request. You will need to enable reports and configure an URL in the gateway administration control panel.

Always return HTTP status code 200 when receiving gateway requests. Any other code will trigger a re-send and could possibly stall the queue of delivery reports. In case there is an error in your system, if a database server is not working, you can return HTTP status code 500. We will then wait for some time, and try to resend at a later time.

Structure of XML Delivery Report Object for MT Messages

<dlr>
  <messageId></messageId>
  <clientRef></clientRef>
  <delivered></delivered>
  <statusCode></statusCode>
  <time></time>
  <timestamp></timestamp>
  <mcc></mcc>
  <mnc></mnc>
  <partCount></partCount>
</dlr>

Delivery Report Parameters

Delivery Report Status Codes

RECEIVING MESSAGES FROM THE END USER (MO)

This section describes the protocol to forward user-originated SMS when using the HTTP XML API. The XML messages objects are sent as the body a HTTP POST request. You will need to enable message reception and configure an URL in the gateway administration control panel.

Always return HTTP status code 200 when receiving gateway requests. Any other code will trigger a re-send and could possibly stall the queue of messages. In case there is an error in your system, if a database server is not working, you can return HTTP status code 500. We will then wait for some time, and try to resend at a later time.

Structure of XML Message Object for MO Messages

<deliverMsg>
  <messageId></messageId>
  <recipient></recipient>
  <sender></sender>
  <text></text>
</deliverMsg>

Receive Message Parameters

PARAMETER DATATYPES

Date Data Type

All dates are specified using the format described in RFC 3339, unless otherwise noted.

Example of timestamps using the format specified in RFC 3339:

2015-11-27T22:54:33Z
2015-11-27T22:54:33.231Z
2015-11-27T22:54:33.231+01:00

The SMS Gateway will always send timestamps containing the fractional seconds part, but it will accept timestamps both with and without fractional seconds.

Alphanumeric Sender

Alphanumeric numbers may be up to 11 characters long. We will accept any character string of length 11 and less, but not all characters are supported by all the operators. We recommend only using the following characters:

• Numbers [0-9]
• Upper and lower case letters [A-Za-z]
• & (ampersand)

Note that space characters should also be avoided as not all operators support this.

Hex Encoded Strings

Hex encoded strings are used as a way to specify binary data in a text document. The string "Hello" will result in the byte array [48, 65, 6C, 6C, 6F] when using utf-8 encoding. The hex string is the string representing the values in this array using 2 characters per value: "48656C6C6F".

Examples of making a hex string:

• Python:

  >>> import binascii
  >>> binascii.hexlify('Hello'.encode('utf8'))
  b'48656c6c6f'

• Java:

  javax.xml.bind.DatatypeConverter.printHexBinary("Hello".getBytes(StandardCharsets.UTF_8));

• PHP:

  bin2hex('Hello');

• node.js:

  > Buffer.from('Hello').toString('hex');
  '48656c6c6f'

DOCUMENT VERSION HISTORY

• Added status code for message sent to recipient number that are to a country on the account block list:
  • 6005 - Recipient country is blocked for your account

• Removed price and ageLimit parameters for MT messages
• Removed premium rate status codes:
  • 3000 - Billing failed, reason not available
  • 3001 - Subscriber is temporarily barred
  • 3002 - Subscriber has insufficient funds
  • 3003 - Subscriber is too young
  • 3004 - The maximum number of messages to this account has been exceeded
  • 4000 - Barred, reason not available
  • 4001 - Subscriber account barred
  • 4002 - Subscriber account closed
  • 4003 - Subscriber is reserved against receiving overcharged content
  • 6003 - Invalid price
  • 9001 - Premium rate transaction refunded
• Removed # and ! from recommended characters in alphanumeric senders.

• Updated tag parameter description for MT messages

• Updated senderType parameter for MT messages
• Added note for the sender parameter for MT messages

• Specified that GET or POST parameters for the HTTP GET/POST API must use UTF-8 character encoding.

• Updated description for status codes 7001, 7002 and 7005

• Removed unused status codes 7004 and 7006
• Updated some status code descriptions

• Added documentation for requestDlr and sendTime parameters.
• Added documentation for mcc, mnc, time, timestamp and partCount parameters in delivery report.

• Clarify description of recodeText parameter
• Encourage use of HTTPS instead of HTTP

• Added gateway parameter recodeText

• Added delivered (0/1) parameter to JSON and XML delivery report

• Added status code 9001 (Refunded)
• Reorganized section order
• Added column for maximum parameter length

• Initial version