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 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 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": 1,
            "messageId": "unique_message_id",
            "recipient": "4700000000",
            "statusCode": 1000,
            "statusDescription": "accepted"
        }
    ]
}

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:

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
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

HTTP JSON Requests

The HTTP JSON API allows submitting multiple message per request. The JSON message object must be submitted using HTTP POST requests. The request SHOULD be sent with the header Content-type: application/json.

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

{
    "auth": {
        "username": <String>,
        "password": <String>,
    },
    "messages": [
        {
            "clientRef": <String>,
            "gateway": <String>,
            "senderType": <Number>,
            "sender": <String>,
            "recipient": <String>,
            "expire": <String>,
            "sendTime": <String>,
            "requestDlr": <Number>,
            "price": <Number>,
            "ageLimit": <Number>,
            "serviceCode": <String>,
            "tag": <String>,
            
            "contentText": {
                "dcs": <Number>,
                "text": <String>,
                "recodeText": <Number>
            },
            
            "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 nameField typeSize (max)MandatoryDescription
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.
senderTypeIntegernoType of sender number.
  • 0: Unknown/autodetect (default)
  • 1: Short code / Network specific number
  • 2: (Reserved, no longer used)
  • 3: (Reserved, no longer used)
  • 4: International MSISDN
  • 5: Alphanumeric
senderStringnoSender number or alphanumeric sender id. Alphanumeric sender id should only be letters and digits, maximum 11 characters. See more information about alphanumeric sender addresses.
NOTE: Use international format including country code when using numeric sender.
recipientStringyesRecipient 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. See datatypes section for supported date format.
sendTimeStringnoThe time at which the message should be sent. The message will be stored until the specified time before it is sent. The message route and cost will be decided at the time the message is sent. See datatypes section for supported date format.
requestDlrIntegernoRequest deliver report for message. Set to 1 to enable (default) and 0 to disable.
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
dcsIntegernoData 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 either by ? (question mark) or with a similar-looking character from the GSM 7-bit alphabet.
textStringyesText content. Long messages will be split into multiple SMS.
recodeTextIntegernoInstruct the gateway to convert the text content.
  • 0: Disabled (default)
  • 1: The gateway will try to replace some of the UCS2 (Unicode) characters with similar-looking characters from GSM 7-bit alphabet. If the text contains UCS2 characters that cannot be replaced (emojis etc), the encoding will fall back to UCS2. recodeText=1 is only applicable when dcs is not specified.
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:

CodeResponse TypeDescription
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>,
            "recipient": <String>,
            "statusCode": <String>,
            "statusDescription": <String>
        }
    ]
}

Send Response Parameters

Field nameField typeMandatoryDescription
acceptedIntegeryesValue 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
messageIdStringnoUnique message id generated by TeletopiaSMS for the message.
recipientStringnoThe recipient specified in the send request.
statusCodeStringyesThe status code. This is a more detailed version of the accepted field. See section for delivery report status codes.
statusDescriptionStringyesHuman readable string describing the status code.

RECEIVING DELIVERY REPORTS FOR SENT MESSAGES (DLR)

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.

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

{
  "messageId": <String>,
  "clientRef": <String>,
  "delivered": <Number>,
  "statusCode": <Number>,
  "time": <String>,
  "timestamp": <Number>,
  "mcc": <String>,
  "mnc": <String>,
  "partCount": <Number>
}

Delivery Report Parameters

Field nameField typeMandatoryDescription
messageIdStringyesThe identifier of the message, this is the id returned when submitting a message.
clientRefStringnoThe custom identifier of the message. This value may be specified when a message is submitted.
deliveredIntegeryesValue 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 delivered field. See section for delivery report status codes.
timeStringyesThe time at which the delivery report was received by TeletopiaSMS from operator (RFC 3339 format).
timestampNumberyesThe time at which the delivery report was received by TeletopiaSMS from operator (in milliseconds from 1970-01-01 UTC).
mccStringnoThe MCC country code the message was routed to. Note this parameter may not always be available.
mncStringnoThe MNC operator code the message was routed to. Note this parameter may not always be available.
partCountNumberyesThe number of SMS message parts the text message was split into by TeletopiaSMS.

Delivery Report Status Codes

Status codes marked with PR are only used for premium rate SMS.

CodeDescription
1000Message in transit, not yet delivered
2000Message has been successfully delivered to recipient
30XXBilling failed
3000PRBilling failed, reason not available
3001PRSubscriber is temporarily barred
3002PRSubscriber has insufficient funds
3003PRSubscriber is too young
3004PRThe maximum number of messages to this account has been exceeded
40XXBarred
4000PRBarred, reason not available
4001PRSubscriber account barred
4002PRSubscriber account closed
4003PRSubscriber is reserved against receiving overcharged content
50xxAccess failed
5000Access failed
60xxMessage rejected
6000Message rejected
6001Invalid recipient MSISDN
6002Invalid sender-id
6003PRInvalid price
6004Invalid content
70XXMessage undeliverable
7000Message undeliverable
7001Message unroutable (usually invalid msisdn)
7002Rejected by operator: Rejected payload
7003Technical error
7005Rejected by operator: Unknown subscriber
90xxExpired/Refunded
9000Expired
9001PRPremium rate transaction refunded

RECEIVING MESSAGES FROM THE END USER (MO)

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.

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 JSON Message Object for MO Messages

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

Receive Message Parameters

Field nameField typeMandatoryDescription
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.

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)
  • # (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');
  • node.js:
    > Buffer.from('Hello').toString('hex');
    '48656c6c6f'

DOCUMENT VERSION HISTORY

Updated 2022/06/10
  • Updated senderType parameter for MT messages
  • Added note for the sender parameter for MT messages
Updated 2021/01/06
  • Specified that GET or POST parameters for the HTTP GET/POST API must use UTF-8 character encoding.
Updated 2020/10/30
  • Updated description for status codes 7001, 7002 and 7005
Updated 2020/07/07
  • Removed unused status codes 7004 and 7006
  • Updated some status code descriptions
Updated 2019/05/02
  • Added documentation for requestDlr and sendTime parameters.
  • Added documentation for mcc, mnc, time, timestamp and partCount parameters in delivery report.
Updated 2019/01/03
  • Clarify description of recodeText parameter
  • Encourage use of HTTPS instead HTTP
Updated 2018/09/18
  • Added gateway parameter recodeText
Updated 2017/10/30
  • Added delivered (0/1) parameter to JSON and XML delivery report
Updated 2017/08/14
  • Added status code 9001 (Refunded)
  • Reorganized section order
  • Added column for maximum parameter length
Updated 2017/07/12
  • Initial version