Download OpenAPI specification:Download
Send a message to one or many recipients. This API supports the same channels as Conversation API.
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.
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 Message (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 A list of recipients who will receive the message. Each recipient entry can include custom parameters and metadata that apply only to that recipient. | ||||||||||||||||||||||||||||||
processing_strategy | string (ProcessingStrategy) Overrides the app's Processing Mode. Default value is
| ||||||||||||||||||||||||||||||
object 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: | |||||||||||||||||||||||||||||||
object Optional metadata that will be associated with the messages generated by the batch.
Returned in the | |||||||||||||||||||||||||||||||
object 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_after | string <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 | ||||||||||||||||||||||||||||||
channel_priority_order | Array of strings (Channel Identifier) Defines the channels to use for message delivery and the order in which they will be attempted. See Conversation API reference for details.
| ||||||||||||||||||||||||||||||
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 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.
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": [ ]
}
}
Retrieve the status of a batch of messages by its unique batch ID.
project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
batch_id required | string The unique ID of the batch. This ID is returned when submitting a batch of messages. |
OK
Invalid credentials
Permission denied. The specified project may not be allowed to use the batch endpoint.
Batch not found
Internal error
{- "batch_id": "string",
- "meta_data": {
- "property1": "string",
- "property2": "string"
}, - "status": "READY",
- "send_after": "string"
}