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

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

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

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/plain
URL for send (secondary)http://api2.teletopiasms.no/gateway/v3/plain
URL for send (tertiary)http://api3.teletopiasms.no/gateway/v3/plain
Secure web service for send (primary)https://api1.teletopiasms.no/gateway/v3/plain
Secure web service for send (secondary)https://api2.teletopiasms.no/gateway/v3/plain
Secure web service for send (tertiary)https://api3.teletopiasms.no/gateway/v3/plain

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

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 submit a form).

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.

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). Multiple recipients can be specified as one value separated by , (comma) or by multiple recipient parameters.
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.
contentTypeStringno Specify how the message content will be delivered to TeletopiaSMS. If not specified contentType=text is assumed.
  • text
  • textsms
  • binarysms
See the following sections for the parameters used for each of these content types.
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.

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

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.

Delivery Report Parameters

Field name Field type Mandatory Description
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.
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 delivered field. See section for delivery report status codes.

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

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.

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.

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