openapi: 3.1.0 tags: - name: Messages description: |- Send a message to one or many recipients. This API supports the same [channels](https://developers.sinch.com/docs/conversation/channel-support/) as Conversation API. - name: Contacts description: |- Create or delete contacts in batches. - name: Consents description: |- Manage Conversation API consents in batches. info: description: |- Perform batch operations on select Conversation API resources. 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: "/v1/projects/{project_id}/messages": parameters: - $ref: "#/components/parameters/project_id" post: description: |- 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. tags: - Messages summary: Send a batch of messages operationId: Batch_SendBatch 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": [], }, } delete: description: |- 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. tags: - Messages summary: Cancel scheduled messages operationId: Batch_CancelBatch 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": [], }, } "/v1/projects/{project_id}/messages/{batch_id}": parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/batch_id" get: description: |- Retrieve the status of a batch of messages by its unique batch ID. tags: - Messages summary: Get the status of batch of messages operationId: Batch_GetBatchStatus responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/GetBatchStatusResponse" "401": description: Invalid credentials "403": description: Permission denied. The specified project may not be allowed to use the batch endpoint. "404": description: Batch not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: BatchNotFound: summary: Batch not found value: { "error": { "code": 404, "message": "Batch with batch_id {batch_id} was not found", "status": "NOT_FOUND", "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": [ ], }, } "/v1/projects/{project_id}/contacts": parameters: - $ref: "#/components/parameters/project_id" post: description: |- Creates a batch of up to 1000 contacts as specified by the list of contacts. The contacts are created asynchronously. A `CONTACT_CREATE` event will be generated for every successfully created contact. tags: - Contacts summary: Create contacts operationId: Batch_CreateContacts requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateContactsRequest" examples: CreateContacts: summary: Create multiple contacts value: { "contacts": [ { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{PHONE_NUMBER_1}}" } ], "language": "EN_US" }, { "channel_identities": [ { "channel": "RCS", "identity": "{{PHONE_NUMBER_2}}" } ], "language": "EN_US" }, { "channel_identities": [ { "channel": "RCS", "identity": "{{PHONE_NUMBER_3}}" } ], "language": "EN_US" } ] } 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": [], }, } delete: description: |- Deletes a batch of up to 1000 contacts as specified by the list of contact IDs. The contacts are deleted asynchronously. A `CONTACT_DELETE` event will be generated for every successfully deleted contact. tags: - Contacts summary: Delete contacts operationId: Batch_DeleteContacts requestBody: content: application/json: schema: $ref: "#/components/schemas/DeleteContactsRequest" examples: DeleteContacts: summary: Delete multiple contacts value: { "contact_ids": [ "{{CONTACT_1}}", "{{CONTACT_2}}", "{{CONTACT_3}}", "{{CONTACT_4}}", "{{CONTACT_5}}" ] } 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": [ ], }, } "/v1/projects/{project_id}/consents": parameters: - $ref: "#/components/parameters/project_id" post: description: |- Insert consent records for multiple identifications in a single request. If the request fails, none or only some of the records may be inserted. Retry the batch later to try again. tags: - Consents summary: Insert consent records operationId: Batch_InsertConsents requestBody: content: application/json: schema: $ref: "#/components/schemas/InsertConsentsRequest" examples: InsertConsents: summary: Insert multiple consents value: { "app_id": "{{APP_ID}}", "consent_records": [ { "identification": "{{PHONE_NUMBER_1}}", "consent_type": "OPT_OUT_ALL" }, { "identification": "{{PHONE_NUMBER_2}}", "consent_type": "OPT_OUT_MARKETING" }, { "identification": "{{PHONE_NUMBER_3}}", "consent_type": "OPT_OUT_NOTIFICATION" } ], } required: true responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/InsertConsentsResponse" "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" } } 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 batch_id: name: batch_id description: The unique ID of the batch. This ID is returned when submitting a batch of messages. 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 GetBatchStatusResponse: type: object properties: batch_id: description: The ID of the batch of messages. type: string meta_data: description: The metadata associated with the batch of messages. type: object additionalProperties: type: string status: description: The status of the batch of messages. type: string enum: - READY - SCHEDULED - PROCESSED - CANCELLED send_after: description: The date and time when the batch of messages is or was scheduled to be sent to recipients. type: string format: ISO 8601 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" description: |- Represents a recipient and optional parameters for a message in a batch request. Each recipient can have custom parameters and metadata that apply only to that recipient. properties: recipient: $ref: "../conversation.yaml#/components/schemas/RecipientRequest" parameters: description: One or more key value string pairs. The key identifies what parameter to overwrite and the value is the new value. type: object additionalProperties: type: string message_metadata: description: Custom message metadata for the recipient. This will be merged with the `message metadata` in the batch request. type: object additionalProperties: type: string conversation_metadata: description: Custom conversation metadata for the recipient. This will be merged with the `conversation metadata` in the batch 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: |- A list of recipients who will receive the message. Each recipient entry can include custom parameters and metadata that apply only to that recipient. type: array minItems: 1 maxItems: 1000 items: $ref: "#/components/schemas/RecipientAndParam" batch_metadata: description: |- 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: `_batch_id` is a reserved field that should not be included in this object, as it will be automatically added by the API. type: object additionalProperties: type: string message_metadata: description: |- Optional metadata that will be associated with the messages generated by the batch. Returned in the `metadata` 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. type: object additionalProperties: type: string conversation_metadata: description: |- 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. type: object additionalProperties: type: string send_after: description: 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. type: string format: date-time example: 2025-01-01T12:34:56Z channel_priority_order: description: |- 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. 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 CreateContactsRequest: type: object required: - "contacts" properties: contacts: description: |- List of contacts to be created in Conversation API. type: array minItems: 1 maxItems: 1000 items: $ref: "../conversation.yaml#/components/schemas/ContactCreateRequest" CreateContactsResponse: type: object properties: batch_id: description: The ID of the batch sent. type: string example: 01GCA8RWNW9FVGVSYS1BMKRW80 DeleteContactsRequest: type: object required: - "contact_ids" properties: contact_ids: description: |- List of IDs for contacts to be deleted in Conversation API. type: array minItems: 1 maxItems: 1000 items: type: string DeleteContactsResponse: type: object properties: batch_id: description: The ID of the batch sent. type: string example: 01GCA8RWNW9FVGVSYS1BMKRW80 InsertConsentsRequest: type: object required: - "app_id" - "consent_records" properties: app_id: description: The ID of the Conversation API app under which the consent records are to be stored. type: string consent_records: type: array description: > A list of consent records to create. Each record must include an `identification` field, which uniquely identifies the subject (e.g., phone number or contact ID), and a `consent_type`. items: type: object required: - identification properties: identification: type: string description: Unique identifier for the subject of the consent (e.g., phone number, contact ID). consent_type: type: string enum: - OPT_OUT_ALL - OPT_OUT_NOTIFICATION - OPT_OUT_MARKETING description: > The type of consent being inserted. InsertConsentsResponse: type: object properties: batch_id: description: The unique ID for the batch of consent records created. type: string 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).