# 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](/docs/conversation/api-reference/batch-api/batch).

## 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](https://developers.sinch.com/docs/conversation/api-reference/#authentication).

## Base URL

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

| Server | URL |
|  --- | --- |
| Conversation Batch API (US) | `https://us.conversationbatch.api.sinch.com` |
| Conversation Batch API (EU) | `https://eu.conversationbatch.api.sinch.com` |
| Conversation Batch API (BR) | `https://br.conversationbatch.api.sinch.com` |


## 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](https://developers.sinch.com/docs/conversation/callbacks#batch-status-update) and [Message Delivery Receipts](https://developers.sinch.com/docs/conversation/callbacks#message-delivery-receipt) 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](https://developers.sinch.com/docs/conversation/api-reference/#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](https://developers.sinch.com/docs/conversation/callbacks##batch-status-update) with an error status.
- **Message-level errors:** You receive a [Message Delivery Receipt](https://developers.sinch.com/docs/conversation/callbacks#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:


```json

{
  "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.