# Send a batch of messages 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. Endpoint: POST /v1/projects/{project_id}/messages Version: 0.0.1 Security: BearerAuth ## Path parameters: - `project_id` (string, required) The unique ID of the project. You can find this on the Sinch Dashboard. ## Request fields (application/json): - `app_id` (string, required) The ID of the app sending the message. - `message` (object, 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 , where is the parameter name. - `message.explicit_channel_message` (object) 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 . The message content must be provided in a string format. You may use the [transcoding endpoint](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Transcoding/) 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](https://developers.sinch.com/docs/conversation/channel-support/) (for example, using explicit channel messages with [the WhatsApp channel](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support/#explicit-channel-messages)). - `message.explicit_channel_omni_message` (object) 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 . The content defined under the specified channel will be sent on that channel. - `message.channel_specific_message` (object) Channel specific messages, overriding any transcoding. The structure of this property is more well-defined than the open structure of the property, and may be easier to use. The key in the map must point to a valid conversation channel as defined in the enum . - `message.agent` (object) Represents an agent that is involved in a conversation. - `message.agent.display_name` (string) Agent's display name - `message.agent.type` (string) Agent's classification. It can be UNKNOWN_AGENT_TYPE, HUMAN or BOT. Enum: "UNKNOWN_AGENT_TYPE", "HUMAN", "BOT" - `message.agent.picture_url` (string) The Agent's picture url. - `processing_strategy` (string) Overrides the app's [Processing Mode](https://developers.sinch.com/docs/conversation/processing-modes/). Default value is . Enum: "DEFAULT", "DISPATCH_ONLY" - `recipient_and_params` (array, required) 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.recipient` (object, required) Identifies the recipient. If [Dispatch Mode](https://developers.sinch.com/docs/conversation/processing-modes/) is used, you must use the field. - `recipient_and_params.parameters` (object) 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_metadata` (object) Custom message metadata for the recipient. This will be merged with the in the batch request. - `recipient_and_params.conversation_metadata` (object) Custom conversation metadata for the recipient. This will be merged with the in the batch request. - `batch_metadata` (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](https://developers.sinch.com/docs/conversation/api-reference/batch-api/batch/tag/Batch-API/#tag/Batch-API/operation/Batch_CancelBatch). Note: is a reserved field that should not be included in this object, as it will be automatically added by the API. - `message_metadata` (object) Optional metadata that will be associated with the messages generated by the batch. Returned in the field of a [Message Delivery Receipt](https://developers.sinch.com/docs/conversation/callbacks/#message-delivery-receipt). This map is converted to a JSON string for compatibility with the Conversation API. See [Conversation API metadata](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=message_metadata&t=request) for details. - `conversation_metadata` (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](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=conversation_metadata&t=request) for details. - `send_after` (string) 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 value is returned in the response. Example: "2025-01-01T12:34:56Z" - `channel_priority_order` (array) Defines the channels to use for message delivery and the order in which they will be attempted. See [Conversation API reference](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=channel_priority_order&t=request) for details. Enum: "WHATSAPP", "RCS", "SMS", "MESSENGER", "VIBERBM", "MMS", "INSTAGRAM", "TELEGRAM", "KAKAOTALK", "KAKAOTALKCHAT", "LINE", "SINCH_CHAT", "WECHAT", "APPLEBC" - `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 (for seconds). Valid integer range is 3 to 315,576,000,000 (inclusive). Example values include (10 seconds) and (24 hours). - `channel_properties` (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 works. Only applicable to messages sent with the processing mode. Up to 128 characters long. ## Response 200 fields (application/json): - `batch_id` (string) The ID of the batch sent. This ID will be present in the field of all the [delivery receipts](/docs/conversation/callbacks/#message-delivery-receipt) for messages generated from this batch request, with the key . Example: "01GCA8RWNW9FVGVSYS1BMKRW80" - `send_after` (string) Time at which the batch of messages will be sent to the recipients. Example: "2022-11-28T12:46:59Z" ## Response 400 fields (application/json): - `code` (integer) - `message` (string) - `status` (string) - `details` (array) - `details.@type` (string) - `details.field_violations` (array) List of field violations in the request - `details.field_violations.field` (string) Field name which the violation refers to - `details.field_violations.description` (string) Description of the violation found in the field ## Response 403 fields (application/json): - `code` (integer) - `message` (string) - `status` (string) - `details` (array) ## Response 500 fields (application/json): - `code` (integer) - `message` (string) - `status` (string) - `details` (array)