Want to provide feedback?

Write to docs@telesign.com.

Get Started with the Bulk SMS API

The Bulk SMS web service enables you to send SMS messages in bulk to your end users with up to a maximum of 1000 messages per request. This API is specifically for a use case where you are doing bulk requests. If you want to send messages individually, you should try looking at the SMS API page instead.

The documentation for the Bulk SMS web service includes the following sections:

General Information

All requests submitted for the Bulk SMS API:

  • Can be authenticated with Basic (easiest to implement) and Digest.
  • Use https://rest-ww.telesign.com/v1/verify/bulk_sms as the base endpoint
  • Accept only UTF-8 encoded unicode characters as inputs.
  • Use Content-Type - application/x-www-form-urlencoded in request headers

Send a Bulk SMS Request

For instructions about how to send your first Bulk SMS Request, see the Bulk SMS Request (POST v1/verify/bulk_sms) page. This section provides information about what parameters you can send in a bulk SMS request. You use a bulk SMS request to specify a message be sent to a list of phone numbers you choose.

For a complete list of request and response parameters, refer to:

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.

Status Callback (POST)

To get status callbacks, you must set up an endpoint to receive the callbacks at. For details about receiving callbacks, see the Obtain Transaction Status Results 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:

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"
}

Status Codes

Status codes for the Bulk SMS API are the same as those for the SMS API, with the addition of:

HTTP Response Code Associated Text String Description
200 293 Bulk request accepted The bulk request was accepted by TeleSign

Next Steps

This section offers some suggestions for next steps to take.