Documentation

Introduction

This technical document is intended for developers who wish to use the textLab HTTP or REST API for sending messages, and describes the various programming methods and commands used by developers when using this API.

To use this API, you need to have a valid textLab Pro account and request an API access by mailing support@ttagsystems.com. You will be issued a username, password and api_id: keep these at hand.

You can test the API using credits assigned to your account, and purchase credits to start sending your own, customized messages.

—

SMS messages are sent by making HTTP calls to the API. You can loop through your list of mobile numbers and make HTTP requests to send SMS messages to them. It’s quick to get started and there is no need to understand the additional or advanced features unless you want to use them.

Some more facts about this API:

• Supports JSON and XML data formats.
• Supports HTTP (port 80).
• You can send to multiple handsets in one single HTTP request – this is useful if you are sending the same message text to all handsets.
• Supports persistent connections (keep-alive) and the use of multiple concurrent connections.
• Various HTTP status codes are used.

Authentication and session IDs

In order to deliver a message, the system needs to authenticate the request as coming from a valid source.

Sending Message

This command allows you to send one or more SMS messages. To send messages to your database of mobile numbers, you can call this command in a loop.

Query a Message

This command returns the status of a message.

Error Codes

The following error messages are generated by the textLab gateway during the validation phase, before a message is accepted. They are sent back to your application as an API response.

Message Status Codes

These are message statuses that are generated after textLab gateway has accepted a message for delivery.

Getting Started

This section will cover the HTTP method, one of the simpler server-based forms of communication to textLab gateway. It can be used either in the form of a HTTP POST, or as a URL (GET). We recommend POST for larger data transfers, due to the size limitations of GET. Communication to our API can be done either via HTTP on port 80 or HTTPS on port 443.

All calls to the API must be URL-encoded. Batch messaging is catered for in a variety of ways.

Note: Please note that parameters are case-sensitive. All examples shown use HTTP GET. Sample code can be provided upon request.

In order to use the textLab gateway you need a textLab account and at least one registered connection (API sub-product instance) between your application and our gateway. Each connection method is known as a sub-product (of our API product).

You can request an HTTP API access when signing up for an account or by emailing support@ttagsystems.com. A HTTP API will be added to your account for you. This will allow you to start testing the textLab Gateway immediately once your account is provisioned.

Basic Commands

In order to send a message, the system will firstly need to authenticate you as a valid user. You can use the auth command to obtain a session ID. If you do not use auth to obtain a session ID, you will have to pass your account details with every command.

All other commands are then made up of three segments: authentication, the basic message components (message content and recipients) and the additional message parameters. In the examples below, we will include the authentication and basic message components. The additional message parameters will be included only where they are relevant.

Basic Command Structure:

Authentication and Session IDs

In order to deliver a message, the system needs to authenticate the request as coming from a valid source.

We use a number of parameters to achieve this:

• API_ID: This is issued upon addition of an HTTP sub-product to your account. A single account may have multiple API IDs associated with it.
• User: This is the username of your account.
• Password: The current password you have set on your account.

You can have multiple sessions open, however the session ID will expire after fifteen minutes of inactivity.

You will then have to re-authenticate to receive a new session ID. Alternatively, you can ping every 10 minutes or so to ensure that the current session ID is kept live.

Ping

This command is only useful if you are using the Authentication command to get a session ID for authenticating your API requests. Session ID’s expire after 15 minutes of inactivity (if no API request is made with the session ID for 15 minutes).

Note that any API command using a session ID will cause your session ID to remain active for another 15 minutes.

You can call this API command once every 10 minutes or so to keep your session active. Should your session expire, your application needs to make a new authentication request to get a new session ID.

Sending message

This command allows you to send one or more SMS messages. To send messages to your database of mobile numbers, you can call this command in a loop.

The server will respond with a unique identifier for each message (referred to as an API message ID). This API message ID can be used to track and monitor the status of your message. You can also send to multiple handsets in one single HTTP/S request (up to 500 messages). This is useful if you are sending the same message text to all handsets.

For high volume messaging, we encourage the use of persistent (keep-alive) HTTP/S connections. Multiple concurrent HTTP/S connections may also be used for additional performance.

Query a Message

This command returns the status of a message. You can query the status with either the apimsgid or climsgid. The API Message ID (apimsgid) is the message ID returned by the gateway when a message has been successfully submitted. If you specified your own unique client message ID (climsgid) on submission, you may query the message status using this value. You may also authenticate with api_id, user and password.

Receiving Messages

We makes HTTP requests to your application just like a regular web browser. By including parameters and values in its requests, we send data to your application that you can act upon before responding. You can configure the URLs and HTTP Methods using the REST API.

When we receive a message for one of your phone numbers we make a synchronous HTTP request to the message URL configured for that number. We send the following parameters with its request as POST parameters or URL query parameters, depending on which HTTP method you’ve configured:

Data Formats – Phone Numbers
All phone numbers in requests should be in E.164 format if possible. For example, (647) 333-3535 would come through as ‘+16473333535’. However, there are occasionally cases where we can’t normalize an incoming caller ID to E.164. In these situations we will report the raw caller ID string.

Data Formats – Date and Time
All dates and times in requests from us are GMT in RFC 2822 format. For example, 4:27 PM EDT on March 11, 2015 would be ‘Wed, 11 Mar 2015 20:27:00 +0000’.