SMS - Send bulk SMS

This page walks you step-by-step through how to code an integration with Telesign SMS to send a message to multiple recipients with one HTTP request.

Before you begin

Make sure you have the following before you start:

• Transaction Callback Service: You need to have this set up so Telesign can send you delivery status updates for each send. See Transaction callback service for setup instructions.
• Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.
• API enabled: Make sure Bulk SMS is enabled for your account. Contact Telesign Customer Support to request this.

Steps

Step 1: Prepare recipients string

1. Generate the list of phone numbers to send your SMS message to.
2. Generate a unique ID for each phone number.
3. Concatenate each phone number to its ID with a colon in between.
4. Concatenate the phone number/ID pairs into one string, separating pairs with colons.

381606878232:255E3E34382C0E049046BF14FF7F3435,381647559476:255DEBF29DA410049042F97AF48F3D04

🚧

CAUTION

Although it is possible to send messages using this API without tying each phone number to an ID, we strongly recommend generating IDs so you can track the status of each send.

Step 2: Send the SMS

1. Open the POST https://rest-ww.telesign.com/v1/verify/bulk_sms reference page and keep it open in another window.
2. Send a POST https://rest-ww.telesign.com/v1/verify/bulk_sms request. Include the recipients string, the message text, and optionally your own session ID for this entire transaction.

POST /v1/verify/bulk_sms HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com
recipients=381606878232:255E3E34382C0E049046BF14FF7F3435,381647559476:255DEBF29DA410049042F97AF48F3D04&template=Your message here.&session_id=CustomExternalID7349

If the transaction is successful, an HTTP 200 response is returned.

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 23 Jun 2022 19:03:32 GMT
{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "sub_resource": "bulk_sms",
  "status": {
    "updated_on": "2022-06-23T19:03:32.334160Z",
    "code": 293,
    "description": "Bulk request accepted"
  },
  "errors": []
}

If the transaction fails, a Telesign status code and at least one error code is returned in the response, helping you troubleshoot the problem.

HTTP/1.1 503 SERVICE UNAVAILABLE
Date: Thu, 23 Jun 2022 19:03:32 GMT
{
  "status": {
    "updated_on": "2022-06-22T19:03:30.420798Z",
    "code": 500,
    "description": "Transaction not attempted"
  },
  "errors": [
    {
      "code": -90001,
      "description": "System Unavailable, Please try again later."
    }
  ],
  "sub_resource": "bulk_sms"
}

📘

NOTE:

Status codes are returned for both success and failure states, and indicate at a high-level what happened. Possible status codes for this feature are included on the POST https://rest-ww.telesign.com/v1/verify/bulk_sms reference page.

Error codes indicate a specific error that occurred in a failure state. Possible error codes for this API are included on the POST https://rest-ww.telesign.com/v1/verify/bulk_sms reference page.

3. Save the reference ID from the successful response.

Step 3: Get delivery status

1. Search HTTP requests to your Transaction Callback Service to find callbacks containing the reference ID from your original transaction. In addition to callbacks related to the delivery status of the transaction as a whole, you can expect to see Delivery Reports for the send to each recipient phone number.

POST /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
  "status": {
    "updated_on": "Thu, 23 Jun 2022 19:03:44 GMT",
    "code": 200,
    "description": "Delivered to handset"
  },
  "errors": [],
  "sub_resource": "bulk_sms",
  "session_id": "255E3E34382C0E049046BF14FF7F3435",
  "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

2. A Telesign status code of 200 here indicates the message was successfully delivered.

For more details related to interpreting these callbacks, see SMS - Track bulk delivery status.