Overview

The Conversation Batch API allows you to perform batch operations in Conversation API, like sending messages with up to 1000 recipients, or creating and deleting batches of contacts.

The following batch operations are detailed in the API reference:

• Send a batch of messages
• Cancel scheduled messages
• Get the status of a batch of messages
• Create contacts
• Delete contacts

You can download the OpenAPI specification here.

The sections below contain more general information regarding the endpoints, including authentication information and information on errors and error handling.

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>

Making a request using access tokens

After obtaining an access token, you can then make a call to the Conversation Batch API by including the obtained access token in the request header. For example:

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

Base URL

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

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 Batch API

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 Batch API 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 Batch API, 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.