HTTP GET/POST API

Introduction

This document contains information required for Content Providers to send and receive SMS messages to mobile-phone subscribers using the TeletopiaSMS HTTP GET/POST Gateway interface. The interface is intended for developers and requires basic knowledge of HTTP. 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).

Example of a send message URL (GET-request):

https://api1.teletopiasms.no/gateway/v3/plain?username=xxx&password=xxx&text=Hello+World&recipient=4700000000

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:

Basic HTTP POST/GET Requests

Simple HTTP requests support submitting a single message per request. The requests are made using HTTP query parameters for GET requests and request body using Content-type: application/x-www-form-urlencoded for POST requests (this is the same way a web browser submits a form).

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. The parameters can be supplied as either GET or POST and must use UTF-8 character encoding.

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:

If the submit was determined to be a success (HTTP status code 200) one response per message is returned, each on a separate line. The response fields are delimited by a colon :

Format for accepted messages

accepted:<recipient-number>:<message-id>

Format for rejected messages

rejected:<recipient-number>:<status-code>:<status-description>

Example of an accepted message

accepted:4700000000:6b151d9e-8617-4e0c-8709-b9506b5963ef

Example of a rejected message

rejected:4700000000:4002:Subscriber account closed

RECEIVING DELIVERY REPORTS FOR SENT MESSAGES (DLR)

This section describes the protocol used to receive delivery reports. The reports are sent to an URL as arguments in 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.

Delivery Report Parameters

Delivery Report Status Codes

RECEIVING MESSAGES FROM THE END USER (MO)

This section describes the protocol to forward user-originated SMS. The messages are sent to an URL as arguments in 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.

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