Overview

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.

Authentication

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 '{ ... }'

Errors

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

Common error responses

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"
}

Error Codes and Descriptions

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

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.