Obtain Transaction Status Results

This page describes how you can find out about the status of your request to send an SMS. You have two choices, you can do a status request to TeleSign and ask for the status of a message, or you can set up callbacks. 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.

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.

SMS API Explorer
NOTE: When using the SMS API Explorer, you will be charged your contracted rate for each transaction. The time shown in ms is not indicative of regular transmission rates, and only applies to the SMS API Explorer.
Path Params
1 path param not set
reference_id

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

  1. Click the Query tab.
  2. For the query value field across from reference_id enter the reference ID number for the transaction you want to retrieve status information about.
  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.

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:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
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
{
  "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"
  },
  "additional_info": {
    "mnc": "03",
    "mcc": "220"
  }
}

Status Callback (POST)

Delivery results can be obtained by using the 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 the callback notification, your server should respond to TeleSign with HTTP 200 OK response.
  5. If TeleSign does not receive a response, or is unable to deliver your callback notification on the first attempt, the TeleSign server waits 10 seconds, then tries again. If the second attempt fails, the server waits an additional 30 seconds and then makes a 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"
  }
}

Next Steps

Some next steps you may want to take include: