Obtain Transaction Status Results

In general, whenever you send a bulk SMS request, you directly receive a response about the status of your bulk SMS request. In addition, you receive a delivery receipt (DLR) for every message that was part of your bulk SMS request. Each DLR can be matched with the phone number it is for if you use the session_id parameter for each MSISDN.

The payload for a DLR for an individual message looks like the example “DLR Payload.”

DLR Payload
{
  "status": {
    "updated_on": "Wed, 05 Oct 2016 14:51:28 GMT",
    "code": 200,
    "description": "Delivered to handset"
  },
  "errors": [],
  "sub_resource": "bulk_sms",
  "session_id": "255E3E34382C0E049046BF14FF7F3435",
  "reference_id": "B56259E45884010488343BAA15FB0002"
}

You must use callbacks to get the receipts.

You can read more about callbacks and obtaining status results in these sections:

Status Callback (POST)

To get status callbacks, you use the TeleSign Verify Transaction Callback web service. It is a service that sends the transaction status for each transaction to a callback URL that you provide.

NOTE:

You must use standard ports in order for transaction callbacks to work properly. For HTTP, the default standard port would be 80, and for HTTPS (transport layer security (TLS)), the default standard port would be 443.

To use the Verify Transaction Callback service, refer to the Get Status / Verify Transaction Callback API page.

Examples

A successful response body looks like this:

Successful Response Body
{
  "reference_id": "B562A981D0E0010488434B07861B1862",
  "sub_resource": "bulk_sms",
  "errors": [],
  "status": {
    "updated_on": "2016-10-21T14:05:36.181346Z",
    "code": 293,
    "description": "Bulk request accepted"
  }
}

A generic unsuccessful response looks like this:

Generic Unsuccessful Response
{
  "status": {
    "updated_on": "2016-10-25T12:33:45.420798Z",
    "code": 500,
    "description": "Transaction not attempted"
  },
  "errors": [
    {
      "code": -90001,
      "description": "System Unavailable, Please try again later."
    }
  ],
  "sub_resource": "bulk_sms"
}

An unsuccessful response where the cause is too many recipients looks like this:

Unsuccessful Response - Too Many Recipients
{
  "status": {
    "updated_on": "2016-10-25T12:33:45.420798Z",
    "code": 500,
    "description": "Transaction not attempted"
  },
  "errors": [
    {
      "code": -10003,
      "description": "Max number of recipients exceeded."
    }
  ],
  "sub_resource": "bulk_sms"
}

An unsuccessful response where the cause is that the feature is not enabled appears as shown in “Unsuccessful Response - Customer Feature Not Enabled.”

Unsuccessful Response - Customer Feature Not Enabled
{
  "status": {
    "updated_on": "2016-10-25T12:33:45.420798Z",
    "code": 500,
    "description": "Transaction not attempted"
  },
  "errors": [
    {
      "code": -20002,
      "description": "This product is not enabled for this CustomerID."
    }
  ],
  "sub_resource": "bulk_sms"
}

Next Steps

This section offers some suggestions for next steps to take.

  • SMS API - Read about how to get started with the SMS API, which lets you send individual SMS messages easily.
  • SMS Verify API - Explore the SMS Verify API, which is great for sending one-time passcode (OTP) messages.