HTTP JSON API

Introduction

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

The interface is designed in order 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.

Benfits 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 JSON API:

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

{
  "auth": {
    "username": "xxx",
    "password": "xxx",
  },
  "messages": [
    {
      "recipient": "4700000000",
      "contentText": {
        "text": "Hello world"
      }
    }
  ]
}

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

{
  "responses": [
    {
      "accepted": "4700000000",
      "messageId": "unique_message_id"
    }
  ]
}

We support both HTTP and HTTPS and we have backup end-points available in case one of the servers should become unreachable. 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.

URL for send (primary)http://api1.teletopiasms.no/gateway/v3/json
URL for send (secondary)http://api2.teletopiasms.no/gateway/v3/json
URL for send (tertiary)http://api3.teletopiasms.no/gateway/v3/json
Secure web service for send (primary)https://api1.teletopiasms.no/gateway/v3/json
Secure web service for send (secondary)https://api2.teletopiasms.no/gateway/v3/json
Secure web service for send (tertiary)https://api3.teletopiasms.no/gateway/v3/json

All TeletopiaSMS HTTP based API services are available as HTTPS (SSL encrypted) as well as HTTP. We recommend using HTTPS whenever possible.

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

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 JSON Request Object for MT Messages

{
  "auth": {
    "username": <String>,
    "password": <String>,
  },
  "messages": [
    {
      "clientRef": <String>,
      "gateway": <String>,
      "senderType": <Number>,
      "sender": <String>,
      "recipient": <String>,
      "expire": <String>,
      
      "billing": {
        "price": <Number>,
        "ageLimit": <Number>,
        "serviceCode": <String>
      },
      
      "contentText": {
        "dcs": <Number>,
        "text": <String>
      },
      
      "contentSmsText": {
        "dcs": <Number>,
        "pid": <Number>,
        "udh": <String>,
        "text": <String>
      },
      
      "contentSmsBinary": {
        "dcs": <Number>,
        "pid": <Number>,
        "udh": <String>,
        "ud": <String>,
      }
    }
  ]
}

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

Send Message Parameters

Field name Field type Size (max) Mandatory Description
usernameStringyesUsername for gateway.
passwordStringyesPassword for gateway.
clientRefString100noThis is an optional Content Provider generated message id. This id will be included in delivery reports.
tagString100noOptional string to "tag" a message, e.g. service name. Makes it possible to split statistics, search in logs. Will create separate lines on invoice.
senderTypeIntegerno Type of sender number.
  • 0: Unknown (default)
  • 1: Shortcode
  • 2: Reserved
  • 3: National
  • 4: International MSISDN
  • 5: Alphanumeric
senderStringno Sender number or alphanumeric sender id. Alphanumeric sender id should only be letters and digits, maximum 11 characters. See more information about alphanumeric sender addresses.
recipientStringyes Recipient number (MSISDN). The format of the number is E.164, without any leading + or trunk prefix. (Example: 4712345678).
gatewayStringnoIgnore unless otherwise instructed by TeletopiaSMS.
expireStringnoThe time at which the message should no longer be attempted to be delivered to the recipient. This field will be used when the operators support message expiration dates, otherwise the operator default value will be used.
priceIntegernoThe price for the reverse-billing premium rate message in 1/100 of the local currency. For example in order to charge a Norwegian user NOK 5,- the value 500 must be used.
ageLimitIntegernoAge limit for message. Commonly supported values for the various operators are 16 and 18. If operator does not have support for the given age limit, the first allowed limit above the value specified will be used.
Parameters for the text content type
dcsIntegerno Data coding scheme. The specified value must be 0-255. If dcs is not specified the GSM 7-bit alphabet will be used unless the text contains characters not part of the GSM 7-bit alphabet, in which case UCS2 will be used. If dcs is set to 0, the message will be sent using the GSM 7-bit alphabet, all characters not supported by this alphabet will be replaced by ? (question mark).
textStringyesText content. Long messages will be split into multiple SMS.
Parameters for the textsms content type
dcsIntegernoData coding scheme. The specified value must be 0-255.
pidIntegernoProtocol identifier. This value is not supported for all carriers. The specified value must be 0-255.
udhString280noUser data header specified as a hex encoded string. See more information about hex encoded strings.
textString160yesText content. Maximum 140 bytes (160 characters in GSM 7-bit alphabet)
Parameters for the binarysms content type
dcsIntegeryesData coding scheme. The specified value must be 0-255.
pidIntegernoProtocol identifier. This value is not supported for all carriers. The specified value must be 0-255.
udhString280noUser data header specified as a hex encoded string. See more information about hex encoded strings.
udString280yesUser data specified as a hex encoded string. The combined maximum length of the udh and ud is 140 bytes (or 280 characters as a hex encoded string). See more information about hex encoded strings.

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:

Code Response Type Description
200SuccessRequest was understood by the gateway, check the response body for the submit status.
400Bad RequestRequest is invalid or contains invalid/unsupported data.
403ForbiddenAuthentication failed.
500Internal Server ErrorAn error occurred when processing the message.

Structure of JSON Response Object for MT Messages

{
  "responses": [
    {
      "accepted": <Number>,
      "clientRef": <String>,
      "messageId": <String>
    }
  ]
}

Send Response Parameters

Field name Field type Mandatory Description
acceptedIntegeryes Value indicating whether message was accepter or not:
  • 1 - Message was accepted
  • 0 - Message was not accepted
clientRefStringnoThe custom identifier of the message. This value may be specified when a message is submitted
messageIdStringyesUnique message id generated by TeletopiaSMS for the message.

This section describes the protocol used to receive delivery reports when using the HTTP JSON API. The JSON 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.

Structure of JSON Delivery Report Object for MT Messages

{
  "messageId": <String>,
  "clientRef": <String>,
  "status": <Number>
}

Delivery Report Parameters

Field name Field type Mandatory Description
messageIdStringyesThe identifier of the message, which was returned in the response object.
clientRefStringnoThe custom identifier of the message. This value may be specified when a message is submitted.
deliveredIntegeryes Value indicating whether message was delivered or not:
  • 1 - Message was delivered
  • 0 - Message delivery failed
statusCodeIntegeryesThe status code. This is a more detailed version of the delivery field. See section for statusCodes.

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.

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.

Delivery Report Status Codes

Code Description
1000Message in transit, not yet delivered
2000Message has been successfully delivered to recipient
30XXBilling failed
3000Billing failed, reason not available
3001Subscriber is temporarily barred
3002Subscriber has insufficient funds
3003Subscriber is too young
3004The maximum number of messages to this account has been exceeded
40XXBarred
4000Barred, reason not available
4001Subscriber account barred
4002Subscriber account closed
4003Subscriber is reserved against receiving overcharged content
50xxAccess failed
5000Access failed
60xxInvalid message
6000Invalid message
6001Invalid destination address
6002Invalid originating address
6003Invalid price
6004Invalid content
70XXGateway error
7000Gateway error
7001Unable to route message
7002Something wrong with message or sent to operator missing capability to deliver message
7003Technical problems submitting message. Failed all retries etc. Considered an error, probably remote
7004Wrong operator for CPA message
7005The number is probably not in use. NOT used for CPA
7006Prepaid subscriber for operator does not support GAS messages
90xxExpired/Refunded
9000Expired
9001Overcharged transaction refunded

This section describes the protocol to forward user-originated SMS when using the HTTP JSON API. The JSON 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.

Structure of JSON Message Object for MO Messages

{
  "messageId": <String>,
  "recipient": <String>,
  "sender": <String>,
  "text": <String>
}

Receive Message Parameters

Field name Field type Mandatory Description
messageIdStringyesThe identifier of the message.
senderStringyesThe phone number of the end-user this message came from. The format of the number is E.164, without any leading + or trunk prefix. (Example: 4712345678).
recipientStringyesThe number the message was sent to. This can be a shortcode, a national number or an international number.
textStringyesMessage content sent by end-user.

Date Data Type

All dates are specified using the format described in RFC 3339.

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)
  • # (hash)
  • ! (exclamation point)

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');