openapi: 3.1.0 info: description: |- Send batches of messages with up to 1000 recipients per request, with all channels and messages supported by Conversation API. title: Conversation API - Batch API | Sinch version: "0.0.1" license: name: MIT url: "https://www.sinch.com/toc" contact: email: support@sinch.com name: support at sinch servers: - url: "https://{region}.conversationbatch.api.sinch.com" variables: region: default: us enum: - us - eu description: The {region} variable must be set to either us or eu security: - BearerAuth: [] paths: "/v1beta/projects/{project_id}/batches:send": parameters: - $ref: "#/components/parameters/project_id" post: description: |- 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](/docs/conversation/callbacks/#message-delivery-receipt) 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. tags: - Batch API summary: Send a batch operationId: Batch_SendBatch x-tagAfterOperationSummary: label: Beta color: white background: green requestBody: content: application/json: schema: $ref: "#/components/schemas/SendBatchRequest" examples: TextMessageBatch: summary: Text message batch value: { "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" }, }, ], } ChoiceMessageBatch: summary: Choice message batch value: { "app_id": "{{APP}}", "message": { "choice_message": { "text_message": { "text": "Hello ${name}, what do you want to do?", }, "choices": [ { "text_message": { "text": "Choice 1" }, "postback_data": "${payload}-choice-1", }, { "text_message": { "text": "Choice 2" }, "postback_data": "${payload}-choice-2", }, { "text_message": { "text": "Choice 3" }, "postback_data": "${payload}-choice-3", }, ], }, }, "recipient_and_params": [ { "recipient": { "contact_id": "{{CONTACT-1}}" }, "parameters": { "name": "User 1", "payload": "user-1" }, }, { "recipient": { "contact_id": "{{CONTACT-2}}" }, "parameters": { "name": "User 2", "payload": "user2" }, }, ], } BatchWithMetadata: summary: Batch with metadata value: { "app_id": "{{APP}}", "message": { "text_message": { "text": "Text message" } }, "recipient_and_params": [ { "recipient": { "contact_id": "{{CONTACT-1}}" }, "message_metadata": { "recipient_only": "arbitrary_value", "arbitrary_key": "overriding metadata", }, }, { "recipient": { "contact_id": "{{CONTACT-2}}" }, "conversation_metadata": { "recipient_only": "arbitrary_value", "arbitrary_key": "overriding metadata", }, }, ], "message_metadata": { "arbitrary_key": "arbitrary_value" }, "conversation_metadata": { "arbitrary_key": "arbitrary_value" }, } ScheduledBatch: summary: Scheduled batch value: { "app_id": "{{APP}}", "send_after": "2022-11-30T17:00:00", "message": { "text_message": { "text": "This is a scheduled message for 3 recipients!", }, }, "recipient_and_params": [ { "recipient": { "contact_id": "{{CONTACT-1}}" } }, { "recipient": { "contact_id": "{{CONTACT-2}}" } }, { "recipient": { "contact_id": "{{CONTACT-3}}" } }, ], "batch_metadata": { "CampaignId": "ef6b5e86-3a1f-43b4-8cba-d44b2d8162c5" }, } required: true responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SendBatchResponse" "400": description: Malformed request content: application/json: schema: $ref: "#/components/schemas/BadRequestResponse" examples: TextMessageViolation: summary: Text message violation value: { "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.", }, ], }, ], }, } MultipleViolations: summary: Multiple violations value: { "error": { "code": 400, "message": "Invalid argument", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.BadRequest", "field_violations": [ { "field": "recipient_and_params[0].recipient", "description": "Field is mandatory.", }, { "field": "message.text_message.text", "description": "Field is mandatory.", }, ], }, ], }, } "401": description: Invalid credentials "403": description: Permission denied. The specified project may not be allowed to use the batch endpoint. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: PermissionDenied: summary: Permission denied value: { "error": { "code": 403, "message": "", "status": "PERMISSION_DENIED", "details": [], }, } "500": description: Internal error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: InternalError: summary: Internal error value: { "error": { "code": 500, "message": "There was an internal server error.", "status": "INTERNAL_ERROR", "details": [], }, } "/v1beta/projects/{project_id}/batches:cancel": parameters: - $ref: "#/components/parameters/project_id" post: description: |- 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. tags: - Batch API summary: Cancel batches operationId: Batch_CancelBatch x-tagAfterOperationSummary: label: Beta color: white background: green requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelBatchRequest" examples: CancelById: summary: Cancel batch by id value: { "batch_id": "01GJJE4HZTAR53YE1WAA6VCF4D" } CancelByMetadata: summary: Cancel batches by metadata value: { "metadata_filter": { "key_name": "CampaignId", "key_value": "ef6b5e86-3a1f-43b4-8cba-d44b2d8162c5", }, } required: true responses: "200": description: OK "401": description: Invalid credentials "403": description: Permission denied. The specified project may not be allowed to use the batch endpoint. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: PermissionDenied: summary: Permission denied value: { "error": { "code": 403, "message": "", "status": "PERMISSION_DENIED", "details": [], }, } "500": description: Internal error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: InternalError: summary: Internal error value: { "error": { "code": 500, "message": "There was an internal server error.", "status": "INTERNAL_ERROR", "details": [], }, } components: parameters: project_id: name: project_id description: The unique ID of the project. You can find this on the [Sinch Dashboard](https://dashboard.sinch.com/convapi/apps). in: path required: true schema: type: string schemas: BadRequest: type: object properties: "@type": type: string field_violations: type: array items: $ref: "#/components/schemas/FieldViolation" description: List of field violations in the request additionalProperties: true BadRequestResponse: type: object properties: code: type: integer format: int32 message: type: string status: type: string details: type: array items: $ref: "#/components/schemas/BadRequest" CancelBatchRequest: description: Either id or metadata oneOf: - title: batch_id description: ID of the batch to be cancelled. type: object properties: batch_id: type: string - title: metadata_filter description: Key and value of metadata of batches to be cancelled. All batches with matching batch_metadata values will be cancelled. type: object properties: metadata_filter: type: object properties: key_name: type: string key_value: type: string ErrorResponse: type: object properties: code: type: integer format: int32 message: type: string status: type: string details: type: array FieldViolation: type: object properties: field: type: string description: Field name which the violation refers to description: type: string description: Description of the violation found in the field GoogleProtobufAny: type: object properties: "@type": type: string description: The type of the serialized message. additionalProperties: true description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. RecipientAndParam: type: object required: - "recipient" properties: recipient: $ref: ../conversation.yaml#/components/schemas/RecipientRequest parameters: description: Custom parameters for the recipient that will be replaced in the request's message. type: object additionalProperties: type: string message_metadata: description: Custom message metadata for the recipient, which will be merged with the message metadata in the request. type: object additionalProperties: type: string conversation_metadata: description: Custom conversation metadata for the recipient, which will be merged with the conversation metadata in the request. type: object additionalProperties: type: string SendBatchRequest: type: object description: This is the request body for sending a batch of messages. required: - "app_id" - "message" - "recipient_and_params" properties: app_id: description: The ID of the app sending the message. type: string message: $ref: "../conversation.yaml#/components/schemas/AppMessage" description: "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." processing_strategy: $ref: "../conversation.yaml#/components/schemas/ProcessingStrategy" recipient_and_params: description: |- List of recipients that will receive the message, along with custom parameters and metadata for each one. type: array minItems: 1 maxItems: 1000 items: $ref: "#/components/schemas/RecipientAndParam" batch_metadata: description: |- Custom metadata that will be associated with the batch, and can later be used to perform operations against it, including [cancelling the batch](/docs/conversation/api-reference/batch-api/batch/tag/Batch-API/#tag/Batch-API/operation/Batch_CancelBatch). type: object additionalProperties: type: string message_metadata: description: |- Metadata that will be associated with the messages generated by the batch. Returned in the `metadata` field of a [Message Delivery Receipt](/docs/conversation/callbacks/#message-delivery-receipt). This map will be converted to a JSON string for compatibility with Conversation API. Check [Conversation API metadata reference](/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=conversation_metadata&t=request) for more information. type: object additionalProperties: type: string conversation_metadata: description: |- Metadata that will be associated with the conversation of each message in the batch. Check [Conversation API metadata reference](/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=conversation_metadata&t=request) for more information. type: object additionalProperties: type: string send_after: description: 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. type: string format: date-time example: 2022-11-28T12:46:59Z channel_priority_order: description: |- Explicitly defines the channels to be used and the order in which they are tried when sending the message. See the [Conversation API reference](/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=channel_priority_order&t=request) for more information. type: array items: $ref: "../conversation.yaml#/components/schemas/ConversationChannel" ttl: description: |- 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). type: string channel_properties: description: |- 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. type: object additionalProperties: type: string correlation_id: type: string description: |- 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. SendBatchResponse: type: object properties: batch_id: description: The ID of the batch sent. This ID will be present in the `metadata` field of all the [delivery receipts](/docs/conversation/callbacks/#message-delivery-receipt) for messages generated from this batch request, with the key `_batch_id`. type: string example: 01GCA8RWNW9FVGVSYS1BMKRW80 send_after: description: Time at which the batch of messages will be sent to the recipients. type: string format: date-time example: 2022-11-28T12:46:59Z securitySchemes: BearerAuth: type: http scheme: bearer description: | The token is sent in the `Authorization` header preceded by `Bearer`. It's required for all requests made to the REST API. For more information, see [Authentication](/docs/conversation/api-reference/batch-api/#authentication). tags: - name: Batch API description: |- 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](/docs/conversation/message-types/) supported by the Conversation API on any [Conversation API channel](/docs/conversation/channel-support/). Note that portions of the Conversation API batch endpoint specification are very similar to the [Conversation API messages endpoint](/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages), and you can use the corresponding documentation as additional reference material.