Skip to content
Conversation API/API reference/
/
Send a batch of messages

Conversation API - Batch API | Sinch (0.0.1)

Perform batch operations on select Conversation API resources.

Download OpenAPI description
batch.json
batch.yaml
Overview
support at sinch

support@sinch.com

License

MIT

Languages
Servers
The {region} variable must be set to either us or eu

https://{region}.conversationbatch.api.sinch.com/

Messages

Send a message to one or many recipients. This API supports the same channels as Conversation API.

Operations

Send a batch of messages

Request

Send a message to multiple recipients. Parameter variables can be included in all string fields and customized with recipient specific values. Each recipient in the request will generate a message and subsequent delivery reports based on the channel used.

Security
BearerAuth
Path
project_idstringrequired

The unique ID of the project. You can find this on the Sinch Dashboard.

Bodyapplication/jsonrequired
app_idstringrequired

The ID of the app sending the message.

messageCard (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(AppMessage)required

Message that will be sent to the recipients. Parameters can be specified in any of the string fields inside this structure in the format ${parameter}, where parameter is the parameter name.

One of:

Message that will be sent to the recipients. Parameters can be specified in any of the string fields inside this structure in the format ${parameter}, where parameter is the parameter name.

message.​card_messageobject(CardMessage)

Message containing text, media and choices.

message.​explicit_channel_messageobject

Allows you to specify a channel and define a corresponding channel specific message payload that will override the standard Conversation API message types. The key in the map must point to a valid conversation channel as defined in the enum ConversationChannel. The message content must be provided in a string format. You may use the transcoding endpoint to help create your message. For more information about how to construct an explicit channel message for a particular channel, see that channel's corresponding documentation (for example, using explicit channel messages with the WhatsApp channel).

message.​explicit_channel_omni_messageobject

Override the message's content for specified channels. The key in the map must point to a valid conversation channel as defined in the enum ConversationChannel. The content defined under the specified channel will be sent on that channel.

message.​channel_specific_messageobject

Channel specific messages, overriding any transcoding. The structure of this property is more well-defined than the open structure of the explicit_channel_message property, and may be easier to use. The key in the map must point to a valid conversation channel as defined in the enum ConversationChannel.

message.​agentobject(Agent)

Represents an agent that is involved in a conversation.

processing_strategystring(ProcessingStrategy)

Overrides the app's Processing Mode. Default value is DEFAULT.

Enum ValueDescription
DEFAULT

The request will inherit the app's configured processing mode.

DISPATCH_ONLY

Forces the request to be processed in dispatch mode (without storing contacts and conversations), regardless of the app's configured processing mode. Please note that user replies will still be processed in the app's default processing mode and that the conversation_metadata and correlation_id fields are not supported when using this option with an app in CONVERSATION mode.

recipient_and_paramsArray of objects(RecipientAndParam)[ 1 .. 1000 ] itemsrequired

A list of recipients who will receive the message. Each recipient entry can include custom parameters and metadata that apply only to that recipient.

recipient_and_params[].​recipientContact ID (object) or Channel Identities (object)(RecipientRequest)required

Identifies the recipient. If Dispatch Mode is used, you must use the identified_by field.

One of:

Identifies the recipient. If Dispatch Mode is used, you must use the identified_by field.

recipient_and_params[].​recipient.​contact_idstring(Contact ID string)

The ID of the contact.

Example: "{CONTACT_ID}"
recipient_and_params[].​parametersobject

One or more key value string pairs. The key identifies what parameter to overwrite and the value is the new value.

recipient_and_params[].​message_metadataobject

Custom message metadata for the recipient. This will be merged with the message metadata in the batch request.

recipient_and_params[].​conversation_metadataobject

Custom conversation metadata for the recipient. This will be merged with the conversation metadata in the batch request.

batch_metadataobject

Custom metadata that will be attached to the batch itself and returned in the response. This metadata can later be used to manage the batch. For example, you can use the metadata to cancel it. Note: _batch_id is a reserved field that should not be included in this object, as it will be automatically added by the API.

message_metadataobject

Optional metadata that will be associated with the messages generated by the batch. Returned in the metadata field of a Message Delivery Receipt. This map is converted to a JSON string for compatibility with the Conversation API. See Conversation API metadata for details.

conversation_metadataobject

Metadata that will be associated with the conversation of each message in the batch. This metadata will be included in delivery receipts and can be used to correlate MO (mobile originated) messages with the original batch. See Conversation API metadata reference for details.

send_afterstring(date-time)

Specifies when the batch should be sent. If not provided, it defaults to the current time and sends immediately. The value must be in UTC. If the scheduled time is less than 1 minute from the API call, it will be used as-is (with second-level precision). For times further in the future, the value will be rounded up to the next five-minute mark. The maximum allowed delay is 7 days. The final send_after value is returned in the response.

Example: "2025-01-01T12:34:56Z"
channel_priority_orderArray of strings(ConversationChannel)

Defines the channels to use for message delivery and the order in which they will be attempted. See Conversation API reference for details.

Items Enum ValueDescription
WHATSAPP

The WhatsApp channel.

RCS

The RCS channel.

SMS

The SMS channel.

MESSENGER

The Facebook Messenger channel.

VIBERBM

The Viber Business Messages channel.

MMS

The MMS channel.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

KAKAOTALKCHAT

The KakaoTalk chat channel (used primarily in ConsultationTalk).

Example: ["WHATSAPP"]
ttlstring

The timeout allotted for sending the message, expressed in seconds. Passed to channels which support it and emulated by the Conversation API for channels without ttl support but with message retract/unsend functionality. Channel failover will not be performed for messages with an expired TTL.

The format is an integer with the suffix s (for seconds). Valid integer range is 3 to 315,576,000,000 (inclusive). Example values include 10s (10 seconds) and 86400s (24 hours).

channel_propertiesobject

Channel-specific properties. The key in the map must point to a valid channel property and the maximum allowed property value length is 1024 characters.

correlation_idstring

An arbitrary identifier that will be propagated to callbacks related to this message, including MO messages from the recipient. The MO callbacks will always use the last correlation_id available in the conversation, similar to how conversation_metadata works. Only applicable to messages sent with the CONVERSATION processing mode. Up to 128 characters long.

curl -i -X POST \
  'https://us.conversationbatch.api.sinch.com/v1/projects/{project_id}/messages' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "app_id": "{{APP}}",
    "message": {
      "text_message": {
        "text": "Hello ${user}! Your code is ${code}"
      }
    },
    "recipient_and_params": [
      {
        "recipient": {
          "contact_id": "{{CONTACT-1}}"
        },
        "parameters": {
          "user": "User 1",
          "code": "123"
        }
      },
      {
        "recipient": {
          "contact_id": "{{CONTACT-2}}"
        },
        "parameters": {
          "user": "User 2",
          "code": "456"
        }
      },
      {
        "recipient": {
          "contact_id": "{{CONTACT-3}}"
        },
        "parameters": {
          "user": "User 3",
          "code": "789"
        }
      }
    ]
  }'

Responses

OK

Bodyapplication/json
batch_idstring

The ID of the batch sent. This ID will be present in the metadata field of all the delivery receipts for messages generated from this batch request, with the key _batch_id.

Example: "01GCA8RWNW9FVGVSYS1BMKRW80"
send_afterstring(date-time)

Time at which the batch of messages will be sent to the recipients.

Example: "2022-11-28T12:46:59Z"
Response
application/json
{
  "batch_id": "01GCA8RWNW9FVGVSYS1BMKRW80",
  "send_after": "2022-11-28T12:46:59Z"
}

Cancel scheduled messages

Request

Cancel one or more scheduled message batches by ID or by batch metadata. If using metadata, all batches matching the given key and value will be cancelled.

To successfully cancel a batch, you must do so before the send_after time. Batches without a send_after value (i.e., batches that are sent immediately) cannot be cancelled.

Cancellation is performed asynchronously. This means that this method always returns a 200 response, even if the cancellation fails.

Security
BearerAuth
Path
project_idstringrequired

The unique ID of the project. You can find this on the Sinch Dashboard.

Bodyapplication/jsonrequired
One of:

ID of the batch to be cancelled.

batch_idstring
curl -i -X DELETE \
  'https://us.conversationbatch.api.sinch.com/v1/projects/{project_id}/messages' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "batch_id": "01GJJE4HZTAR53YE1WAA6VCF4D"
  }'

Responses

OK

Response
No content

Get the status of batch of messages

Request

Retrieve the status of a batch of messages by its unique batch ID.

Security
BearerAuth
Path
project_idstringrequired

The unique ID of the project. You can find this on the Sinch Dashboard.

batch_idstringrequired

The unique ID of the batch. This ID is returned when submitting a batch of messages.

curl -i -X GET \
  'https://us.conversationbatch.api.sinch.com/v1/projects/{project_id}/messages/{batch_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
batch_idstring

The ID of the batch of messages.

meta_dataobject

The metadata associated with the batch of messages.

statusstring

The status of the batch of messages.

Enum"READY""SCHEDULED""PROCESSED""CANCELLED"
send_afterstring(ISO 8601)

The date and time when the batch of messages is or was scheduled to be sent to recipients.

Response
application/json
{
  "batch_id": "string",
  "meta_data": {
    "property1": "string",
    "property2": "string"
  },
  "status": "READY",
  "send_after": "string"
}

Contacts

Create or delete contacts in batches.

Operations

Consents

Manage Conversation API consents in batches.

Operations