article

Phong Vu avatar image
Phong Vu posted Phong Vu edited

High Volume SMS API reference (Beta)

High Volume Batch SMS (Beta)

Features

  1. Send messages in a batch at a high volume
  2. Supported in US and CA
  3. Use a Single API Call to send messages to thousands of numbers
  4. Use the same API Endpoint to send a Broadcast or a Personalized message to different numbers
  5. Unlimited SMS Batch Size (New Feature)
  6. Queuing (New Feature)
  7. Push Notifications - Batch status, Outbound Message, Inbound Message, Opt-outs


Endpoint

POST /account/~/a2p-sms/batch

This endpoint is used to send a batch of sms(s). This API can be used to either Broadcast the same message to all recipients or send a customized message to different recipients.


Input Parameters

* accountId := string (path parameter)


Sample Request

POST https://platform.ringcentral.com/restapi/v1.0/account/~/a2p-sms/batch
Content-Type: application/json
Accept: application/json


Sample Broadcast Request

{
'from': TF_NUMBER,
'text': 'Broadcast SMS',
'messages': [{'to':["+14083388064"]},{"to":["+14083388064"]}]
}


Sample Personalized Request

{
'from': TF_NUMBER,
'text': 'Broadcast SMS',
'messages': [{'to':["+2222222233"],'text': 'This is for Dibyendu, stay safe'},{"to":["+14087187847"],'text': 'This is for XYZ, stay safe'}]
}


Sample Response

{
"id":"b1804d6f-137c-473a-925e-b78d8cc34410",
"from":"+18883303674",
"batchSize":2,
"processedCount":0,
"status":"Processing",
"createdAt":"2020-04-01T00:09:00.293Z",
"lastUpdatedAt":"2020-04-01T00:09:00.293Z"
}


Endpoint

GET /restapi/v1.0/account/{accountId}/a2p-sms/batch/{batchId}

This endpoint is used to get the status of a batch. You can use this to identify how many records did the batch process or the completion of the batch.


Input Parameters

* accountId := string (path parameter)

* batchId:=string (path parameter)


Sample Response

{
"id":"0ab4f3d1-9ee6-4d3f-accd-4b0567eb2992",
"from":"+18883303674",
"batchSize":2,
"processedCount":2,
"status":"Completed",
"createdAt":"2020-03-31T21:51:42.682Z",
"lastUpdatedAt":"2020-03-31T21:51:46.212Z"
}


Endpoint

GET /restapi/v1.0/account/{accountId}/a2p-sms/messages?batchId={batchId}&pageToken={pageToken}&perPage={perPage}

This endpoint can be used to get the status of single batch or ALL batches.


Input Parameters

* accountId := string (path parameter)

* batchId:=string (query parameter)

* pageToken:=string (query parameter)

* perPage:=string (query parameter)


Sample Response

{
  "messages":[
  {
    "id":"40146",
    "batchId":"0ab4f3d1-9ee6-4d3f-accd-4b0567eb2992",
    "to":[
      "+14083388064"
    ],
    "createdAt":"2020-03-31T21:51:42.685Z",
    "lastUpdatedAt":"2020-03-31T21:51:46.212Z",
    "messageStatus":"delivered"
  },
  {
    "id":"40147",
    "batchId":"0ab4f3d1-9ee6-4d3f-accd-4b0567eb2992",
    "to":[
      "+14087187847"
    ],
    "createdAt":"2020-03-31T21:51:42.687Z",
    "lastUpdatedAt":"2020-03-31T21:51:46.207Z",
    "messageStatus":"delivered"
  }],
  "paging":{
  "pageToken":"Rjo0MDE0Ng==",
  "perPage":2,
  "firstPageToken":"Rjo0MDE0Ng=="
  }
}


Endpoint

GET /restapi/v1.0/account/~/a2p-sms/messages/{messageId}

This API provides message level delivery details.


Input Parameters

* accountId := string (path parameter)

* messageId:=string (path parameter)


Sample Response

{
"id":"40146",
"from":"+18883303674",
"to":[
"+14083388064"
],
"text":"This is for Dibyendu, stay safe",
"createdAt":"2020-03-31T21:51:42.685Z",
"lastUpdatedAt":"2020-03-31T21:51:46.212Z",
"messageStatus":"delivered"
}


Push Notifications

Push notifications can be used at various levels to stay updated on everything going on with your high volume SMS, from a High Volume SMS batch to an individual message level.


The following push notifications are available.

  • Message Batch notifications : Provides updates on the individual batch status
  • Inbound message notifications : Provides updates on an incoming message to a number
  • Outbound message notifications : Provides updates on the delivery status of outbound messages
  • Opt-out notifications : Provides updates to track customers who opted out


Message Batch notifications

Batch level push notifications provide updates on batch status. A batch could have two states "Processing" and "Completed". The following event filters are supported:

  • /restapi/v1.0/account/~/a2p-sms/batch - Notification for any batch status changes on that account
  • /restapi/v1.0/account/~/a2p-sms/batch - Notification for a specific batchId
  • /restapi/v1.0/account/~/a2p-sms/batch?from=+15553334488 - Notification on batches from a specific From number


Inbound message notifications

Notify incoming messages on a phone number. The following event filters are supported:

  • /restapi/v1.0/account/~/a2p-sms/messages?direction=Inbound - Notification on inbound messages to current account
  • /restapi/v1.0/account/~/a2p-sms/messages?direction=Inbound&to=+15553337788 - Notification on inbound messages to a given phone number.


Outbound message notifications

Notify the delivery status of outbound messages. The following event filters are supported:

  • /restapi/v1.0/account/~/a2p-sms/messages?direction=Outbound - All outbound messages in an account
  • /restapi/v1.0/account/~/a2p-sms/messages?direction=Outbound&batchId=abc123 - All outbound messages from a specific batch
  • /restapi/v1.0/account/~/a2p-sms/messages?direction=Outbound&from=+15553339900 - Outbound Messages from a specific phone number


Opt-out notifications

Provides updates to track customers who opted out. The following event filters are supported:

  • /restapi/v1.0/account/~/a2p-sms/opt-outs - All opt-outs for a given account
  • /restapi/v1.0/account/~/a2p-sms/opt-outs?from=+15553332299 - Opt-outs from a specific phone number


Sample Code / App to Play with various scenarios

You can use the sample Python App to play with various scenarios

https://github.com/dibyenduroy/a2psms/

high-volume sms
1 |3000

Up to 8 attachments (including images) can be used with a maximum of 1.0 MiB each and 10.0 MiB total.

Developer sandbox tools

Using the RingCentral Phone for Desktop, you can dial or receive test calls, send and receive test SMS or Fax messages in your sandbox environment.

Download RingCentral Phone for Desktop:

Tip: switch to the "sandbox mode" before logging in the app:

  • On MacOS: press "fn + command + f2" keys
  • On Windows: press "Ctrl + F2" keys

Article

Contributors

Rylie-Community_Moderator contributed to this article Phong1426275020 contributed to this article