SMS API - Obtain Transaction Status Results

This page describes how you can retrieve the status of your request to send an SMS using the SMS API. You have two choices, you can make a Get Status request to TeleSign and ask for the status of a message, or you can set up a callback service. Callbacks are better for high volumes of transactions. If you choose the callback method, TeleSign posts the status results for every transaction to a private URI that you select.

Get Status Request

You can test out doing a Get Status request using the SMS API Explorer below. You need your credentials, and you must have sent an SMS and retrieved the reference ID for your request from the response. If you did not already do this, go to the Send an SMS page.

To get the status of your transaction, do the following:

1. Click the Settings tab.
2. For the value field across from reference_id enter the reference ID number for the transaction you want to retrieve status information about (must have occurred within the last 12 hours). (See all available parameters on the API reference page - GET /v1/messaging.)
3. Click the Auth [basic] tab.
4. In the Username field, enter your Customer ID.
5. In the Password field, enter your API key.
6. Click Send.
7. Congratulations! You've just retrieved the status of the SMS request you sent.
8. To get a code snippet, click the Code Generation tab and choose the language and library you want to use to create the code.

📘

NOTE:

After a transaction occurs, you have 12 hours to obtain status results for the transaction. TeleSign recommends that you wait 3-5 minutes after a transaction occurs to send a Get Status request about the transaction.

Examples of a GET Request

An example request looks like this:

Example GET Request with the SMS API

GET https://rest-ww.telesign.com/v1/messaging/ABCDEF0123456789ABCDEF0123456789 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Date: Tue, 31 Jan 2017 14:53:11 GMT

An example response looks like this:

Example GET Response (Body Only

{
    "external_id": "CustomExternalID7349",
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "submit_timestamp": "Tue, 31 Jan 2017 13:36:07 GMT",
  "status": {
    "code": 290,
    "updated_on": "Tue, 31 Jan 2017 13:36:11 GMT",
    "description": "Message in progress"
  }
}

Callback Service

Delivery results can be obtained by using TeleSign's transaction callback service (ideal for high volumes of transactions). You provide TeleSign with a URL, and TeleSign posts the results of your transactions to the specified URL.

To set up the callback service, you do the following:

1. Create a private URI on your web server for receiving callback notifications from TeleSign.
2. Provide TeleSign with your private URI.
3. You will receive callback notifications after a transaction completes.
4. When you receive a callback notification, your server should respond to TeleSign with HTTP 200 OK response.
5. If TeleSign is unable to deliver your callback notification on the first attempt, the TeleSign server tries again. If the second attempt fails, the server makes a third and final attempt.

An example callback looks like this:

Transaction Callback

{
  "status": {
    "updated_on": "2017-06-29T05:23:10.341823Z",
    "code": 200,
    "description": "Delivered to handset"
  },
  "external_id": "ts_test",
  "reference_id": "B573C93641E0016888403090CF48000B",
  "additional_info": {
    "message_parts_count": 1,
    "price": "0.8054",
    "currency": "USD",
    "mcc": "310",
    "mnc": "170;380"
  }
}

SMS API Information

• The URI is https://rest-ww.telesign.com/v1/messaging
• Authentication - You can authenticate with basic or digest authentication
• Use UTF-8 encoded unicode characters as inputs for all TeleSign APIs
• Use Content-Type application/x-www-form-urlencoded in request headers