Overview

The Conversation Batch API allows you to perform batch operations on select Conversation API resources, such as sending a message to multiple recipients or creating a set of contacts.

You can download the OpenAPI specification here.

Authentication

The Conversation Batch API uses OAuth2.0 Access Tokens to authenticate requests. For detailed instructions on how to obtain and use access tokens, refer to the Authentication guide for the Conversation API.

Base URL

The following URLs can be used when making requests to the Conversation Batch API:

Callbacks

The Conversation Batch API uses callbacks to inform your system about the status of your batch and its messages. Callbacks are sent to the preconfigured webhooks on your Conversation app. It’s recommended to subscribe to both Batch Status Update Notifications and Message Delivery Receipts to track the full lifecycle of your batches and individual messages.

Successful Processing

As a batch moves through the system, you’ll receive Batch Status Update Notifications to track its progress. Once messages are handled, a Message Delivery Receipt is sent for each one with the final result.

Error Handling

If a request is invalid, the Conversation Batch API immediately returns an appropriate HTTP status code (e.g., 4xx for client errors) with a JSON body describing the issue.

For more information on errors, see Conversation API Errors.

Asynchronous Errors

Some errors can occur after the request is accepted. For example, an error that occurs when a message fails during scheduled or delayed delivery. In these cases, the API sends callbacks to notify you:

• Batch-level errors: You will receive a Batch Status Update Notification with an error status.
• Message-level errors: You receive a Message Delivery Receipt with FAILED status and a reason.

See the error types for each callback for more details.

Below is an example of a message_delivery_report callback, with FAILED status:

{
  "app_id": "your_app_id",
  "project_id": "your_project_id",
  "message_delivery_report": {
    "message_id": "message_identifier",
    "status": "FAILED",
    "contact_id": "contact_identifier",
    "reason": {
      "code": "BAD_REQUEST",
      "description": "Validation failed after parameters substitution for batch [batch_id] and message at index [index]. Details: [Parameter key cannot be blank and value cannot be empty.]"
    }
  },
  "message_metadata": "{\"batchId\":\"batch_id\",\"messageIndex\":index}",
  "correlation_id": "optional_correlation_id"
}

The message_delivery_report callback structure for batch messages is largely the same as for single message sends. However, when using the Conversation Batch API, the callback includes an additional message_metadata field. This field provides context to help identify which specific message in the batch failed.

• batchId indicates which batch the failed message belonged to.
• messageIndex refers to the position of the recipient in the original batch request.