Download OpenAPI specification:Download
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.
Note that portions of the Conversation API batch endpoint specification are very similar to the Conversation API messages endpoint, and you can use the corresponding documentation as additional reference material.
The structure of a batch request consists of a single message definition with up to 1000 recipients for the message. Parameter variables are also supported in all string fields of the message, and can be customized for each recipient.
Message and conversation metadata can also be specified at both the request and recipient level. The request-level metadata will be merged with the recipient-level metadata, with precedence for recipient defined metadata.
Each recipient on the request will generate a new Conversation API message, and delivery receipts will be generated accordingly for each message. The metadata field of the receipts will contain a JSON string that consists of the metadata passed in the request and an additional field called _batch_id that is set to the batch id returned in successful responses. This allows you to associate each message (that was sent in a batch) to the corresponding batch. The field is also passed in the conversation_metadata, which allows you to map between a batch and an MO. The _batch_id field is reserved, so ensure you do not include it in any of the request metadata fields (at either the request or recipient level), as it will be overwritten.
This endpoint also allows scheduling the batch instead of sending immediately, which can be done by using the field send_after. This field specifies the time when the batch of messages should be sent. Because it may be modified by the API, it will be returned in the response. If not specified, the current date will be used.
The send_after field can be specified in seconds if it is set to a time that is less than 1 minute into the future from the time the API call is made. For times that are further into the future, it will be rounded to the next five minute multiple in the hour. For example, if the time specified is 2022-11-30T13:27:22, and the API call is made at 2022-11-30T13:10:33, the send_after value will be rounded to 2022-11-30T13:30:00. Maximum allowed scheduling time is 7 days.
| project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
| app_id required | string The ID of the app sending the message. | ||||||
required | Card (object) or Carousel (object) or Choice (object) or Location (object) or Media (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object) (AppMessage) Message that will be sent to the recipients. Parameters can be specified in any of the string fields inside this structure in the format | ||||||
required | Array of objects (RecipientAndParam) [ 1 .. 1000 ] items List of recipients that will receive the message, along with custom parameters and metadata for each one. | ||||||
| processing_strategy | string (ProcessingStrategy) Overrides the app's Processing Mode. Default value is
| ||||||
object Custom metadata that will be associated with the batch, and can later be used to perform operations against it, including cancelling the batch. | |||||||
object Metadata that will be associated with the messages generated by the batch.
Returned in the Check Conversation API metadata reference for more information. | |||||||
object Metadata that will be associated with the conversation of each message in the batch. Check Conversation API metadata reference for more information. | |||||||
| send_after | string <date-time> Specifies the date and time at which the batch should be sent to the recipients. If not specified, the current date will be used instead (resulting in immediate sending). Represented in ISO 8601 format and default time zone is UTC. | ||||||
| channel_priority_order | Array of strings (Channel Identifier) Explicitly defines the channels to be used and the order in which they are tried when sending the message. See the Conversation API reference for more information. | ||||||
| ttl | string 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 | ||||||
object 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_id | string 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 |
OK
| batch_id | string The ID of the batch sent. This ID will be present in the |
| send_after | string <date-time> Time at which the batch of messages will be sent to the recipients. |
Malformed request
Invalid credentials
Permission denied. The specified project may not be allowed to use the batch endpoint.
Internal error
{- "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"
}
}
]
}{- "batch_id": "01GCA8RWNW9FVGVSYS1BMKRW80",
- "send_after": "2022-11-28T12:46:59Z"
}Cancel one or more scheduled batches by their ID or batch metadata. If the using metadata to identify the batch, note that all batches with the matching metadata key and value will be cancelled.
If you wish to cancel a scheduled batch, ensure you do so before the date and time specified in the send_after field. Otherwise, you will be unable to cancel the batch. Note that batches for immediate sending (that is, batches created without the send_after field specified) cannot be cancelled.
The cancellation is conducted asynchronously, so this method will always return a 200 response, regardless of whether the cancellation succeeded or not.
| project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
OK
Invalid credentials
Permission denied. The specified project may not be allowed to use the batch endpoint.
Internal error
{- "batch_id": "01GJJE4HZTAR53YE1WAA6VCF4D"
}{- "error": {
- "code": 403,
- "message": "",
- "status": "PERMISSION_DENIED",
- "details": [ ]
}
}