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/