The Conversation API Batch endpoint allows you to send batches of messages to up to 1000 recipients per request. Because this is an endpoint of the Conversation API, you can send all message types supported by the Conversation API on any Conversation API channel.

Overall, the Conversation API Batch endpoint has a very similar structure to the Conversation API Messages endpoint. For more information, including any schemas or structures unique to the Batch endpoint, see this endpoint's API reference. Additionally, you can download the OpenAPI specification here.


The Conversation API Batch endpoint uses OAuth2 Access Tokens to authenticate API calls. To obtain an Access Token, you must first create an access key in the Sinch Customer Dashboard under Settings | Access Keys. A Key ID and Key Secret will be provided when creating the access key in the customer dashboard.

The Project ID will also be visible on the Access Keys page in the customer dashboard.

The created access key can be used in the different authentication flows in both the us and eu regions.

To get an OAuth token, you will post your Key ID and Key Secret to the Sinch endpoint. The following snippet illustrates how to obtain an Access Token that can be used to authenticate towards the Conversation API.:

curl https://auth.sinch.com/oauth2/token -d grant_type=client_credentials --user <Key ID>:<Key Secret>

You can then make a call to the batch endpoint using the obtained access token in the request header. For example:

curl -i -X POST \
  'https://eu.conversationbatch.api.sinch.com/v1beta/projects/<Project ID>/batches:send' \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'


When requests are erroneous, a response with standard HTTP status codes will be returned. For example, status code 4xx for client errors. Additionally, some responses may include a JSON body of the following form:
  "error": {
    "code": 400,
    "message": "Invalid argument",
    "status": "INVALID_ARGUMENT",
    "details": [{
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "field_violations": [
          "field": "message.text_message.text",
          "description": "Field is mandatory."

The table below describes the fields of the error object:

NameDescriptionJSON Type
CodeHTTP status codeNumber
MessageA developer-facing error messageString
StatusResponse status nameString
DetailsList of detailed error descriptionsArray of objects

Common error responses

400Malformed request
401Incorrect credentials
403Permission denied. This can happen if your project is not allowed to use the batch endpoint.
429See Conversation API Rate Limits
500Something went wrong on our end, try again with exponential back-off

Asynchronous Error Handling in the Conversation API Batch Endpoint

When sending messages in batches using Conversation Batch API, some errors may not occur immediately. Instead, some errors may arise during message delivery (after the initial API request has been accepted). This scenario is particularly true for errors encountered during parameter substitution in the batch of messages. To effectively handle such asynchronous errors, the Conversation API Batch endpoint employs a detailed callback mechanism.

Understanding Asynchronous Errors

Asynchronous errors refer to issues that are detected after the initial API request has been processed. In the context of the Conversation API Batch endpoint, these errors typically involve problems that occur when substituting parameters into messages for individual recipients.

For instance, if a parameter expected to be substituted into a message's text is missing or invalid, the error cannot be detected until the API attempts to process the message for that specific recipient. These issues are not immediate and require a different approach to error handling.

Handling Asynchronous Errors with Callbacks

To notify you of any asynchronous errors that occur, the Conversation Batch API uses callbacks. These callbacks provide detailed information about the error, including which message failed and why.

Callback Structure

Below is an example of a callback for an asynchronous error:

  "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"
In this example, the message_delivery_report section provides key details about the error, including the status of "FAILED" and a reason object that explains the nature of the failure. The message_metadata field offers additional context about the batch and message that encountered the error.
It's essential to enable the MESSAGE_DELIVERY trigger for the App you're sending batches from to receive these callbacks. This setting ensures that you're notified of any delivery failures.

Error Codes and Descriptions

When dealing with asynchronous errors, especially in the context of batch messaging through the Conversation Batch API, understanding the nuances of the error responses is key to effective troubleshooting and resolution. In the case of asynchronous errors, the primary error code you are likely to encounter is BAD_REQUEST.

Understanding Metadata Fields

The metadata fields within the error callbacks provide detailed context about the error, making it easier to identify and rectify the issue. Key metadata fields include:

  • messageIndex: Perhaps one of the most relevant fields, messageIndex indicates the zero-based index of the recipient in the original batch request whose message triggered the error. This is particularly useful for identifying exactly which message (out of, potentially, thousands) failed, allowing for targeted troubleshooting.
  • batchId: The ID of the batch in which the error occurred. This is useful for tracking and logging, especially when you are sending multiple batches and need to identify which specific batch contained the erroneous message.

Example Use of Metadata Fields

Consider a batch request sent to 1000 recipients where one of the messages fails because of a missing parameter value in the message template. The callback containing the BAD_REQUEST error would include a messageIndex that points to the specific recipient in your request list. For example, if messageIndex is 150, the 151st recipient (because the index is zero-based) in your original batch request is the one associated with the failed message. This precise information allows you to quickly locate the error in your request data and correct it without having to manually sift through all the recipients.

Practical Implications

Understanding and utilizing the metadata fields effectively can significantly streamline the debugging and error resolution process. It enables you to:

  • Quickly identify the exact message and recipient that caused the error.
  • Understand the scope and impact of the error within the batch.
  • Make targeted corrections to your batch requests to prevent future errors.

By paying close attention to these metadata fields and incorporating checks and validations in your batch message preparation process, you can minimize errors and enhance the reliability of your messaging operations through the Conversation Batch API.

Best Practices for Error Handling

To effectively manage asynchronous errors, consider the following best practices:

  • Monitor Callbacks: Regularly monitor the callbacks you receive for any errors to promptly address issues.
  • Validate Parameters Before Sending: Where possible, validate the parameters and their presence in your messages before sending them to minimize errors.

By employing these error handling strategies, you can ensure a more robust and reliable messaging experience for your users through the Conversation Batch API.