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: '#/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: '#/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: '#/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: '#/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: '#/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
    CallMessageField:
      description: Message for triggering a call.
      type: object
      title: Call
      properties:
        call_message:
          title: Call Message
          type: object
          required:
            - phone_number
            - title
          properties:
            phone_number:
              description: Phone number in E.164 with leading +.
              type: string
              example: '+15551231234'
            title:
              description: |-
                Title shown close to the phone number.
                The title is clickable in some cases.
              type: string
              example: Message text
    Coordinates:
      type: object
      title: Geographic coordinates
      required:
        - latitude
        - longitude
      properties:
        latitude:
          description: The latitude.
          type: number
          format: float
        longitude:
          description: The longitude.
          type: number
          format: float
    LocationMessageField:
      type: object
      description: Message containing geographic location.
      title: Location
      properties:
        location_message:
          title: Location Message
          type: object
          required:
            - coordinates
            - title
          properties:
            coordinates:
              $ref: '#/components/schemas/Coordinates'
            label:
              description: Label or name for the position.
              type: string
            title:
              description: >-
                The title is shown close to the button or link that leads to a
                map showing the location. The title can be clickable in some
                cases.
              type: string
    TextMessageField:
      type: object
      title: Text
      description: A message containing only text.
      properties:
        text_message:
          type: object
          title: Text Message
          required:
            - text
          properties:
            text:
              description: The text to be sent.
              type: string
    UrlMessageField:
      description: A generic URL message.
      type: object
      title: URL
      properties:
        url_message:
          title: URL Message
          type: object
          required:
            - title
            - url
          properties:
            title:
              description: >-
                The title shown close to the URL. The title can be clickable in
                some cases.
              type: string
            url:
              description: The url to show.
              type: string
    choiceTypes:
      type: object
      oneOf:
        - $ref: '#/components/schemas/CallMessageField'
        - $ref: '#/components/schemas/LocationMessageField'
        - $ref: '#/components/schemas/TextMessageField'
        - $ref: '#/components/schemas/UrlMessageField'
    choiceCommonProps:
      type: object
      properties:
        postback_data:
          description: >-
            An optional field. This data will be returned in the
            ChoiceResponseMessage. The default is message_id_{text, title}.
    Choice:
      description: >-
        A choice is an action the user can take such as buttons for quick
        replies or other call to actions.
      type: object
      title: Choice message
      allOf:
        - $ref: '#/components/schemas/choiceTypes'
        - $ref: '#/components/schemas/choiceCommonProps'
    CardHeight:
      description: You can set the desired size of the card in the message.
      type: string
      x-enumDescriptions:
        UNSPECIFIED_HEIGHT: The height of the card is unspecified.
        SHORT: The shortest card height.
        MEDIUM: Medium card height.
        TALL: The tallest card height.
      enum:
        - UNSPECIFIED_HEIGHT
        - SHORT
        - MEDIUM
        - TALL
    MediaProperties:
      title: Media Properties
      type: object
      required:
        - url
      properties:
        thumbnail_url:
          type: string
          description: An optional parameter. Will be used where it is natively supported.
        url:
          description: Url to the media file.
          type: string
        filename_override:
          description: Overrides the media file name.
          type: string
    CardMessage:
      description: Message containing text, media and choices.
      title: Card Message
      type: object
      properties:
        choices:
          description: >-
            You may include choices in your Card Message. The number of choices
            is limited to 10.
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        description:
          description: >-
            This is an optional description field that is displayed below the
            title on the card.
          type: string
        height:
          $ref: '#/components/schemas/CardHeight'
        title:
          description: The title of the card message.
          type: string
        media_message:
          type: object
          description: A message containing a media component.
          allOf:
            - $ref: '#/components/schemas/MediaProperties'
        message_properties:
          type: object
          description: Optional additional properties.
          properties:
            whatsapp_header:
              description: >-
                Optional. Sets the header for the footer of a WhatsApp reply
                button message, if there is no media in the message. Ignored for
                other channels. Ignored if not transcoded to a native WhatsApp
                message with reply buttons.
              type: string
    CardMessageField:
      description: Field containing a Card Message
      type: object
      title: Card
      properties:
        card_message:
          $ref: '#/components/schemas/CardMessage'
    CarouselMessageField:
      description: >-
        Message containing a list of cards often rendered horizontally on
        supported channels.
      type: object
      title: Carousel
      properties:
        carousel_message:
          title: Carousel Message
          type: object
          required:
            - cards
          properties:
            cards:
              description: A list of up to 10 cards.
              type: array
              items:
                $ref: '#/components/schemas/CardMessage'
            choices:
              description: >-
                Optional. Outer choices on the carousel level. The number of
                outer choices is limited to 3.
              type: array
              items:
                $ref: '#/components/schemas/Choice'
    Choices:
      type: object
      properties:
        choices:
          type: array
          description: The number of choices is limited to 10.
          items:
            $ref: '#/components/schemas/Choice'
    ChoiceMessagePropertiesField:
      type: object
      title: Properties
      description: Additional properties for the message.
      properties:
        message_properties:
          type: object
          properties:
            whatsapp_footer:
              description: >-
                Optional. Sets the text for the footer of a WhatsApp reply
                button or URL button message. Ignored for other channels.
              type: string
    ChoiceMessageField:
      description: Message containing choices/actions.
      type: object
      title: Choice
      properties:
        choice_message:
          title: Choice Message
          type: object
          required:
            - choices
          allOf:
            - description: A message containing choices.
            - $ref: '#/components/schemas/Choices'
            - $ref: '#/components/schemas/TextMessageField'
            - $ref: '#/components/schemas/ChoiceMessagePropertiesField'
    MediaMessageField:
      type: object
      title: Media Message
      description: >-
        A message containing a media component, such as an image, document, or
        video.
      properties:
        media_message:
          $ref: '#/components/schemas/MediaProperties'
    TemplateReference:
      type: object
      title: Template reference with concrete parameter values
      description: >-
        The referenced template can be an omnichannel template stored in
        Conversation API Template Store as an AppMessage. You may also reference
        external channel-specific templates, such as a WhatsApp Business
        Template. Note that channel-specific template references are not
        supported when populating the `explicit_channel_omni_message` field.
      required:
        - template_id
      properties:
        version:
          type: string
          description: >-
            Used to specify what version of a template to use. Required when
            using `omni_channel_override` and `omni_template` fields.

            This will be used in conjunction with `language_code`. Note that,
            when referencing omni-channel templates using the [Sinch Customer
            Dashboard](https://dashboard.sinch.com/), the latest version of a
            given omni-template can be identified by populating this field with
            `latest`.
        language_code:
          description: >-
            The BCP-47 language code, such as `en_US` or `sr_Latn`.

            For more information, see
            http://www.unicode.org/reports/tr35/#Unicode_locale_identifier.
            English is the default `language_code`.

            Note that, while many API calls involving templates accept either
            the dashed format (`en-US`) or the underscored format (`en_US`),
            some channel specific templates (for example, WhatsApp
            channel-specific templates) only accept the underscored format. Note
            that this field is required for WhatsApp channel-specific templates.
          type: string
        parameters:
          description: |-
            Required if the template has parameters. Concrete values must
            be present for all defined parameters
            in the template. Parameters can be different for
            different versions and/or languages of the template.
          type: object
          additionalProperties:
            type: string
        template_id:
          description: >-
            The ID of the template. Note that, in the case of WhatsApp
            channel-specific templates, this field must be populated by the name
            of the template.
          type: string
    TemplateReferenceWithVersion:
      type: object
      allOf:
        - required:
            - version
        - $ref: '#/components/schemas/TemplateReference'
    TemplateMessageField:
      type: object
      description: Message referring to predefined template
      title: Template Message
      properties:
        template_message:
          type: object
          title: Template Message
          properties:
            channel_template:
              description: >-
                Optional. Channel specific template reference with parameters
                per channel.

                The channel template if exists overrides the omnichannel
                template.

                At least one of `channel_template` or `omni_template` needs to
                be present.

                The key in the map must point to a valid conversation channel as

                defined by the enum ConversationChannel.
              type: object
              additionalProperties:
                $ref: '#/components/schemas/TemplateReference'
            omni_template:
              $ref: '#/components/schemas/TemplateReferenceWithVersion'
    ChoiceItem:
      type: object
      title: Choice
      description: A message component for interactive messages, containing a choice.
      required:
        - title
      properties:
        title:
          type: string
          description: Required parameter. Title for the choice item.
        description:
          type: string
          description: >-
            Optional parameter. The description (or subtitle) of this choice
            item.
        media:
          description: Optional parameter. The media of this choice item.
          allOf:
            - $ref: '#/components/schemas/MediaProperties'
        postback_data:
          type: string
          description: >-
            Optional parameter. Postback data that will be returned in the MO if
            the user selects this option.
    ProductItem:
      type: object
      title: Product
      description: A message component for interactive messages, containing a product.
      required:
        - id
        - marketplace
      properties:
        id:
          type: string
          description: Required parameter. The ID for the product.
        marketplace:
          type: string
          description: Required parameter. The marketplace to which the product belongs.
          example: FACEBOOK
        quantity:
          type: integer
          format: int32
          description: Output only. The quantity of the chosen product.
        item_price:
          type: number
          format: float
          description: Output only. The price for one unit of the chosen product.
        currency:
          type: string
          description: Output only. The currency of the item_price.
    ListItem:
      type: object
      title: List Item
      description: Item containing either choiceItem or ProductItem
      oneOf:
        - required:
            - choice
          type: object
          properties:
            choice:
              $ref: '#/components/schemas/ChoiceItem'
          title: Choice
        - required:
            - product
          type: object
          properties:
            product:
              $ref: '#/components/schemas/ProductItem'
          title: Product
    ListSection:
      type: object
      title: List Section
      description: Section for interactive WhatsApp messages containing ListItem
      required:
        - items
      properties:
        title:
          description: Optional parameter. Title for list section.
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/ListItem'
    ListMessageField:
      type: object
      title: List
      description: >-
        A message containing a list of options to choose from. All items must be
        of the same type.
      properties:
        list_message:
          title: List Message
          type: object
          required:
            - title
            - sections
          properties:
            title:
              description: >-
                A title for the message that is displayed near the products or
                choices.
              type: string
            description:
              description: >-
                This is an optional field, containing a description for the
                message.
              type: string
            media:
              $ref: '#/components/schemas/MediaProperties'
            sections:
              description: >-
                List of ListSection objects containing choices to be presented
                in the list message.
              type: array
              items:
                $ref: '#/components/schemas/ListSection'
            message_properties:
              description: >-
                Additional properties for the message. Required if sending a
                product list message.
              properties:
                catalog_id:
                  description: >-
                    Required if sending a product list message. The ID of the
                    catalog to which the products belong.
                  type: string
                menu:
                  description: >-
                    Optional. Sets the text for the menu of a choice list
                    message.
                  type: string
                whatsapp_header:
                  description: >-
                    Optional. Sets the text for the header of a WhatsApp choice
                    list message. Ignored for other channels.
                  type: string
    NameInfo:
      type: object
      title: Name of the contact
      description: Name information of the contact.
      required:
        - full_name
      properties:
        full_name:
          description: Full name of the contact
          type: string
        first_name:
          description: First name.
          type: string
        last_name:
          description: Last name.
          type: string
        middle_name:
          description: Middle name.
          type: string
        prefix:
          description: Prefix before the name. e.g. Mr, Mrs, Dr etc.
          type: string
        suffix:
          description: Suffix after the name.
          type: string
    PhoneNumberInfo:
      type: object
      title: Phone number
      description: Phone numbers of the contact.
      required:
        - phone_number
      properties:
        phone_number:
          description: Phone number with country code included.
          type: string
        type:
          description: Phone number type, e.g. WORK or HOME.
          type: string
    AddressInfo:
      type: object
      title: Address information
      description: Physical addresses of the contact.
      properties:
        city:
          description: City Name
          type: string
        country:
          description: Country Name
          type: string
        state:
          description: Name of a state or region of a country.
          type: string
        zip:
          description: Zip/postal code
          type: string
        type:
          description: Address type, e.g. WORK or HOME
          type: string
        country_code:
          description: Two letter country code.
          type: string
    EmailInfo:
      type: object
      title: Email information
      description: Email addresses of the contact.
      required:
        - email_address
      properties:
        email_address:
          description: Email address.
          type: string
        type:
          description: Email address type. e.g. WORK or HOME.
          type: string
    OrganizationInfo:
      type: object
      title: Organization information
      description: Organization information of the contact.
      properties:
        company:
          description: Company name
          type: string
        department:
          description: Department at the company
          type: string
        title:
          description: Corporate title, e.g. Software engineer
          type: string
    UrlInfo:
      type: object
      title: URL Info
      description: A URL/website
      required:
        - url
      properties:
        url:
          description: The URL to be referenced
          type: string
        type:
          description: Optional. URL type, e.g. Org or Social
          type: string
    ContactInfoMessageField:
      type: object
      description: Message containing contact information.
      title: Contact Info
      properties:
        contact_info_message:
          title: Contact Info Message
          type: object
          required:
            - name
            - phone_numbers
          properties:
            name:
              $ref: '#/components/schemas/NameInfo'
            phone_numbers:
              description: Phone numbers of the contact
              type: array
              items:
                $ref: '#/components/schemas/PhoneNumberInfo'
            addresses:
              description: Physical addresses of the contact
              type: array
              items:
                $ref: '#/components/schemas/AddressInfo'
            email_addresses:
              description: Email addresses of the contact
              type: array
              items:
                $ref: '#/components/schemas/EmailInfo'
            organization:
              $ref: '#/components/schemas/OrganizationInfo'
            urls:
              description: URLs/websites associated with the contact
              type: array
              items:
                $ref: '#/components/schemas/UrlInfo'
            birthday:
              description: Date of birth in YYYY-MM-DD format.
              type: string
    AppMessageTypes:
      type: object
      oneOf:
        - $ref: '#/components/schemas/CardMessageField'
        - $ref: '#/components/schemas/CarouselMessageField'
        - $ref: '#/components/schemas/ChoiceMessageField'
        - $ref: '#/components/schemas/LocationMessageField'
        - $ref: '#/components/schemas/MediaMessageField'
        - $ref: '#/components/schemas/TemplateMessageField'
        - $ref: '#/components/schemas/TextMessageField'
        - $ref: '#/components/schemas/ListMessageField'
        - $ref: '#/components/schemas/ContactInfoMessageField'
    TemplateReferenceField:
      type: object
      title: Template (Reference)
      properties:
        template_reference:
          $ref: '#/components/schemas/TemplateReferenceWithVersion'
    OmniMessageOverride:
      oneOf:
        - $ref: '#/components/schemas/TextMessageField'
        - $ref: '#/components/schemas/MediaMessageField'
        - $ref: '#/components/schemas/TemplateReferenceField'
        - $ref: '#/components/schemas/ChoiceMessageField'
        - $ref: '#/components/schemas/CardMessageField'
        - $ref: '#/components/schemas/CarouselMessageField'
        - $ref: '#/components/schemas/LocationMessageField'
        - $ref: '#/components/schemas/ContactInfoMessageField'
        - $ref: '#/components/schemas/ListMessageField'
    WhatsAppInteractiveTextHeader:
      type: object
      description: Header of the interactive message with text.
      required:
        - type
        - text
      properties:
        type:
          type: string
          x-enumDescriptions:
            text: The text of the header.
          enum:
            - text
        text:
          type: string
          description: Text for the header. Formatting allows emojis, but not Markdown.
    WhatsAppInteractiveHeaderMedia:
      type: object
      description: Media object for the header.
      required:
        - link
      properties:
        link:
          type: string
          description: URL for the media.
    WhatsAppInteractiveImageHeader:
      type: object
      description: Header of the interactive message with image.
      required:
        - type
        - image
      properties:
        type:
          type: string
          x-enumDescriptions:
            image: The image associated with the header.
          enum:
            - image
        image:
          $ref: '#/components/schemas/WhatsAppInteractiveHeaderMedia'
    WhatsAppInteractiveDocumentHeader:
      type: object
      description: Header of the interactive message with document.
      required:
        - type
        - document
      properties:
        type:
          type: string
          x-enumDescriptions:
            document: The document associated with the header.
          enum:
            - document
        document:
          $ref: '#/components/schemas/WhatsAppInteractiveHeaderMedia'
    WhatsAppInteractiveVideoHeader:
      type: object
      description: Header of the interactive message with video.
      required:
        - type
        - video
      properties:
        type:
          type: string
          x-enumDescriptions:
            video: The video associated with the header.
          enum:
            - video
        video:
          $ref: '#/components/schemas/WhatsAppInteractiveHeaderMedia'
    WhatsAppInteractiveBody:
      type: object
      description: Body of the interactive message.
      required:
        - text
      properties:
        text:
          type: string
          description: >-
            The content of the message (1024 characters maximum). Emojis and
            Markdown are supported.
    WhatsAppInteractiveFooter:
      type: object
      description: Footer of the interactive message.
      required:
        - text
      properties:
        text:
          type: string
          description: >-
            The footer content (60 characters maximum). Emojis, Markdown and
            links are supported.
    ChannelSpecificCommonProps:
      type: object
      properties:
        header:
          description: The header of the interactive message.
          type: object
          oneOf:
            - $ref: '#/components/schemas/WhatsAppInteractiveTextHeader'
            - $ref: '#/components/schemas/WhatsAppInteractiveImageHeader'
            - $ref: '#/components/schemas/WhatsAppInteractiveDocumentHeader'
            - $ref: '#/components/schemas/WhatsAppInteractiveVideoHeader'
          discriminator:
            propertyName: type
            mapping:
              text: '#/components/schemas/WhatsAppInteractiveTextHeader'
              image: '#/components/schemas/WhatsAppInteractiveImageHeader'
              document: '#/components/schemas/WhatsAppInteractiveDocumentHeader'
              video: '#/components/schemas/WhatsAppInteractiveVideoHeader'
        body:
          $ref: '#/components/schemas/WhatsAppInteractiveBody'
        footer:
          $ref: '#/components/schemas/WhatsAppInteractiveFooter'
    FlowChannelSpecificMessage:
      allOf:
        - $ref: '#/components/schemas/ChannelSpecificCommonProps'
        - type: object
          title: Flow channel specific message
          description: A message type for sending WhatsApp Flows.
          required:
            - flow_id
            - flow_cta
          properties:
            flow_id:
              type: string
              description: ID of the Flow.
            flow_token:
              type: string
              description: Generated token which is an identifier.
            flow_mode:
              type: string
              description: The mode in which the flow is.
              default: published
              enum:
                - draft
                - published
              x-enumDescriptions:
                draft: The flow is in draft mode.
                published: The flow is published.
            flow_cta:
              type: string
              description: >-
                Text which is displayed on the Call To Action button (20
                characters maximum, emoji not supported).
            flow_action:
              type: string
              default: navigate
              enum:
                - navigate
                - data_exchange
              x-enumDescriptions:
                navigate: The navigate flow action.
                data_exchange: The data exchange flow action.
            flow_action_payload:
              type: object
              properties:
                screen:
                  type: string
                  description: >-
                    The ID of the screen displayed first. This must be an entry
                    screen.
                data:
                  type: object
                  description: Data for the first screen.
    PaymentOrderDetailsChannelSpecificMessage:
      allOf:
        - $ref: '#/components/schemas/ChannelSpecificCommonProps'
        - type: object
          title: Payment Order Details channel specific message.
          description: A message type for sending WhatsApp Payment Requests.
          required:
            - payment
          properties:
            payment:
              type: object
              description: The payment order details content.
              required:
                - type
                - reference_id
                - type_of_goods
                - total_amount_value
                - order
              properties:
                type:
                  type: string
                  description: The country/currency associated with the payment message.
                  enum:
                    - br
                    - sg
                  x-enumDescriptions:
                    br: Brazil
                    sg: Singapore
                reference_id:
                  type: string
                  description: Unique reference ID.
                type_of_goods:
                  type: string
                  description: The type of good associated with this order.
                  enum:
                    - digital-goods
                    - physical-goods
                  x-enumDescriptions:
                    digital-goods: Digital goods.
                    physical-goods: Physical goods.
                payment_settings:
                  type: object
                  description: The payment settings.
                  required:
                    - dynamic_pix
                  properties:
                    dynamic_pix:
                      type: object
                      description: The dynamic Pix payment settings.
                      required:
                        - code
                        - merchant_name
                        - key
                        - key_type
                      properties:
                        code:
                          type: string
                          description: The dynamic Pix code to be used by the buyer to pay.
                        merchant_name:
                          type: string
                          description: Account holder name.
                        key:
                          type: string
                          description: Pix key.
                        key_type:
                          type: string
                          description: Pix key type.
                          enum:
                            - CPF
                            - CNPJ
                            - EMAIL
                            - PHONE
                            - EVP
                          x-enumDescriptions:
                            CPF: The CPF key type.
                            CNPJ: The CNPJ key type.
                            EMAIL: The EMAIL key type.
                            PHONE: The PHONE key type.
                            EVP: The EVP key type.
                total_amount_value:
                  type: integer
                  description: Integer representing the total amount of the transaction.
                order:
                  type: object
                  description: The payment order.
                  required:
                    - items
                    - subtotal_value
                    - tax_value
                  properties:
                    catalog_id:
                      type: string
                      description: >-
                        Unique ID of the Facebook catalog being used by the
                        business.
                    expiration_time:
                      type: string
                      description: |-
                        UTC timestamp indicating when the order should expire.

                        The timestamp must be given in seconds.

                        The minimum threshold for the timestamp is 300 seconds.
                    expiration_description:
                      type: string
                      description: Description of the expiration.
                    subtotal_value:
                      type: integer
                      description: Value representing the subtotal amount of this order.
                    tax_value:
                      type: integer
                      description: Value representing the tax amount for this order.
                    tax_description:
                      type: string
                      description: Description of the tax for this order.
                    shipping_value:
                      type: integer
                      description: Value representing the shipping amount for this order.
                    shipping_description:
                      type: string
                      description: Shipping description for this order.
                    discount_value:
                      type: integer
                      description: Value of the discount for this order.
                    discount_description:
                      type: string
                      description: Description of the discount for this order.
                    discount_program_name:
                      type: string
                      description: Discount program name for this order.
                    items:
                      type: array
                      description: The items list for this order.
                      items:
                        type: object
                        required:
                          - retailer_id
                          - name
                          - amount_value
                          - quantity
                        properties:
                          retailer_id:
                            type: string
                            description: Unique ID of the retailer.
                          name:
                            type: string
                            description: Item's name as displayed to the user.
                          amount_value:
                            type: integer
                            description: Price per item.
                          quantity:
                            type: integer
                            description: Number of items in this order.
                          sale_amount_value:
                            type: integer
                            description: Discounted price per item.
    PaymentOrderStatusChannelSpecificMessage:
      allOf:
        - $ref: '#/components/schemas/ChannelSpecificCommonProps'
        - type: object
          title: Payment Order Status channel specific message.
          description: A message type for sending WhatsApp Payment Status Requests.
          required:
            - payment
          properties:
            payment:
              type: object
              description: The payment order status message content
              required:
                - reference_id
                - order
              properties:
                reference_id:
                  type: string
                  description: Unique ID used to query the current payment status.
                order:
                  type: object
                  description: The payment order.
                  required:
                    - status
                  properties:
                    status:
                      type: string
                      description: The new payment message status.
                      enum:
                        - pending
                        - processing
                        - partially-shipped
                        - shipped
                        - completed
                        - canceled
                      x-enumDescriptions:
                        pending: The order is pending.
                        processing: The order is processing.
                        partially-shipped: A portion of the order has been shipped.
                        shipped: The order has been shipped.
                        completed: The order is complete.
                        canceled: The order was canceled.
                    description:
                      type: string
                      description: >-
                        The description of payment message status update (120
                        characters maximum).
    ChannelSpecificMessage:
      type: object
      title: Channel specific message
      description: >-
        A message containing a channel specific message (not supported by OMNI
        types).
      required:
        - message_type
        - message
      properties:
        message_type:
          type: string
          x-enumDescriptions:
            FLOWS: The WhatsApp Flows message type.
            ORDER_DETAILS: The WhatsApp order details message type.
            ORDER_STATUS: The WhatsApp order status message type.
          description: The type of the channel specific message.
          enum:
            - FLOWS
            - ORDER_DETAILS
            - ORDER_STATUS
        message:
          oneOf:
            - $ref: '#/components/schemas/FlowChannelSpecificMessage'
            - $ref: '#/components/schemas/PaymentOrderDetailsChannelSpecificMessage'
            - $ref: '#/components/schemas/PaymentOrderStatusChannelSpecificMessage'
    AgentType:
      description: Agent's classification. It can be UNKNOWN_AGENT_TYPE, HUMAN or BOT.
      enum:
        - UNKNOWN_AGENT_TYPE
        - HUMAN
        - BOT
      x-enumDescriptions:
        UNKNOWN_AGENT_TYPE: The default AgentType. When the agent type is unknown.
        HUMAN: Human agent.
        BOT: Bot agent.
      type: string
      default: UNKNOWN_AGENT_TYPE
    Agent:
      description: Represents an agent that is involved in a conversation.
      type: object
      title: Agent
      properties:
        display_name:
          description: Agent's display name
          type: string
        type:
          $ref: '#/components/schemas/AgentType'
        picture_url:
          description: The Agent's picture url.
          type: string
    AppMessageCommonProps:
      type: object
      properties:
        explicit_channel_message:
          description: >-
            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
            `ConversationChannel`. 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)).
          type: object
          additionalProperties:
            type: string
        explicit_channel_omni_message:
          description: >-
            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 `ConversationChannel`. The content defined under the specified
            channel will be sent on that channel.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OmniMessageOverride'
        channel_specific_message:
          description: >-
            Channel specific messages, overriding any transcoding. The structure
            of this property is more well-defined than the open structure of the
            `explicit_channel_message` property, and may be easier to use.

            The key in the map must point to a valid conversation channel as
            defined in the enum `ConversationChannel`.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ChannelSpecificMessage'
        agent:
          $ref: '#/components/schemas/Agent'
    AppMessage:
      type: object
      title: Message originating from app
      description: A message originating from a Conversation API app
      allOf:
        - $ref: '#/components/schemas/AppMessageTypes'
        - $ref: '#/components/schemas/AppMessageCommonProps'
    ProcessingStrategy:
      description: >-
        Overrides the app's [Processing
        Mode](https://developers.sinch.com/docs/conversation/processing-modes/).
        Default value is `DEFAULT`.
      enum:
        - DEFAULT
        - DISPATCH_ONLY
      x-enumDescriptions:
        DEFAULT: The request will inherit the app's configured processing mode.
        DISPATCH_ONLY: >-
          Forces the request to be processed in dispatch mode (without storing
          contacts and conversations), regardless of the app's configured
          processing mode. Please note that user replies will still be processed
          in the app's default processing mode and that the
          `conversation_metadata` and `correlation_id` fields are not supported
          when using this option with an app in `CONVERSATION` mode.
      type: string
      default: DEFAULT
    ContactIDField:
      type: object
      title: Contact ID
      properties:
        contact_id:
          title: Contact ID string
          description: The ID of the contact.
          type: string
          example: '{CONTACT_ID}'
    ConversationChannel:
      type: string
      title: Channel Identifier
      description: >-
        The identifier of the channel you want to include. Must be one of the
        enum values.
      example: WHATSAPP
      x-enumDescriptions:
        WHATSAPP: The WhatsApp channel.
        RCS: The RCS channel.
        SMS: The SMS channel.
        MESSENGER: The Facebook Messenger channel.
        VIBERBM: The Viber Business Messages channel.
        MMS: The MMS channel.
        INSTAGRAM: The Instagram channel.
        TELEGRAM: The Telegram channel.
        KAKAOTALK: The KakaoTalk channel.
        KAKAOTALKCHAT: The KakaoTalk chat channel (used primarily in ConsultationTalk).
        LINE: The LINE channel.
        SINCH_CHAT: The Sinch Chat channel.
        WECHAT: The WeChat channel.
        APPLEBC: The Apple Messages for Business channel.
      enum:
        - WHATSAPP
        - RCS
        - SMS
        - MESSENGER
        - VIBERBM
        - MMS
        - INSTAGRAM
        - TELEGRAM
        - KAKAOTALK
        - KAKAOTALKCHAT
        - LINE
        - SINCH_CHAT
        - WECHAT
        - APPLEBC
    ChannelRecipientIdentity:
      type: object
      required:
        - identity
        - channel
      properties:
        channel:
          $ref: '#/components/schemas/ConversationChannel'
        identity:
          description: The channel recipient identity.
          type: string
    ChannelIdentities:
      required:
        - channel_identities
      type: object
      properties:
        channel_identities:
          description: |-
            A list of specific channel identities.
            The API will use these identities when sending to specific channels.
          type: array
          items:
            $ref: '#/components/schemas/ChannelRecipientIdentity'
    IdentifiedByField:
      type: object
      title: Channel Identities
      properties:
        identified_by:
          title: Channel Identity List
          type: object
          description: The identity as specified by the channel.
          allOf:
            - $ref: '#/components/schemas/ChannelIdentities'
    RecipientBase:
      type: object
      oneOf:
        - $ref: '#/components/schemas/ContactIDField'
        - $ref: '#/components/schemas/IdentifiedByField'
    RecipientRequest:
      description: >-
        Identifies the recipient. If [Dispatch
        Mode](https://developers.sinch.com/docs/conversation/processing-modes/)
        is used, you must use the `identified_by` field.
      allOf:
        - $ref: '#/components/schemas/RecipientBase'
    ChannelIdentity:
      description: >-
        A unique identity of message recipient on a particular channel.

        For example, the channel identity on SMS, WHATSAPP or VIBERBM is a
        MSISDN phone number.
      type: object
      title: Channel Identity
      required:
        - identity
        - channel
      properties:
        app_id:
          description: >-
            Required if using a channel that uses app-scoped channel identities.
            Currently, FB Messenger, Instagram, LINE, and WeChat use app-scoped
            channel identities, which means contacts will have different channel
            identities on different Conversation API apps. These can be thought
            of as virtual identities that are app-specific and, therefore, the
            app_id must be included in the API call.
          type: string
        channel:
          $ref: '#/components/schemas/ConversationChannel'
        identity:
          description: >-
            The channel identity. This will differ from channel to channel. For
            example, a phone number for SMS, WhatsApp, and Viber Business.
          type: string
    ContactLanguage:
      type: string
      enum:
        - AF
        - SQ
        - AR
        - AZ
        - BN
        - BG
        - CA
        - ZH
        - ZH_CN
        - ZH_HK
        - ZH_TW
        - HR
        - CS
        - DA
        - NL
        - EN
        - EN_GB
        - EN_US
        - ET
        - FIL
        - FI
        - FR
        - DE
        - EL
        - GU
        - HA
        - HE
        - HI
        - HU
        - ID
        - GA
        - IT
        - JA
        - KN
        - KK
        - KO
        - LO
        - LV
        - LT
        - MK
        - MS
        - ML
        - MR
        - NB
        - FA
        - PL
        - PT
        - PT_BR
        - PT_PT
        - PA
        - RO
        - RU
        - SR
        - SK
        - SL
        - ES
        - ES_AR
        - ES_ES
        - ES_MX
        - SW
        - SV
        - TA
        - TE
        - TH
        - TR
        - UK
        - UR
        - UZ
        - VI
        - ZU
      x-enumDescriptions:
        AF: Afrikaans
        SQ: Albanian
        AR: Arabic
        AZ: Azerbaijani
        BN: Bengali
        BG: Bulgarian
        CA: Catalan
        ZH: Chinese
        ZH_CN: Chinese (CHN)
        ZH_HK: Chinese (HKG)
        ZH_TW: Chinese (TAI)
        HR: Croatian
        CS: Czech
        DA: Danish
        NL: Dutch
        EN: English
        EN_GB: English (UK)
        EN_US: English (US)
        ET: Estonian
        FIL: Filipino
        FI: Finnish
        FR: French
        DE: German
        EL: Greek
        GU: Gujarati
        HA: Hausa
        HE: Hebrew
        HI: Hindi
        HU: Hungarian
        ID: Indonesian
        GA: Irish
        IT: Italian
        JA: Japanese
        KN: Kannada
        KK: Kazakh
        KO: Korean
        LO: Lao
        LV: Latvian
        LT: Lithuanian
        MK: Macedonian
        MS: Malay
        ML: Malayalam
        MR: Marathi
        NB: Norwegian
        FA: Persian
        PL: Polish
        PT: Portuguese
        PT_BR: Portuguese (BR)
        PT_PT: Portuguese (PT)
        PA: Punjabi
        RO: Romanian
        RU: Russian
        SR: Serbian
        SK: Slovak
        SL: Slovenian
        ES: Spanish
        ES_AR: Spanish (ARG)
        ES_ES: Spanish (SPA)
        ES_MX: Spanish (MEX)
        SW: Swahili
        SV: Swedish
        TA: Tamil
        TE: Telugu
        TH: Thai
        TR: Turkish
        UK: Ukrainian
        UR: Urdu
        UZ: Uzbek
        VI: Vietnamese
        ZU: Zulu
    ContactCreateRequest:
      description: >-
        A participant in a conversation typically representing a person. It is
        associated with a collection of channel identities.
      type: object
      title: Contact creation request
      required:
        - channel_identities
        - language
      properties:
        channel_identities:
          description: List of channel identities. Array must contain at least one item.
          type: array
          items:
            $ref: '#/components/schemas/ChannelIdentity'
        channel_priority:
          description: >-
            List of channels defining the channel priority. The channel at the
            top of the list is tried first.
          type: array
          items:
            $ref: '#/components/schemas/ConversationChannel'
        display_name:
          type: string
          description: >-
            The display name. A default 'Unknown' will be assigned if left
            empty.
        email:
          description: Email of the contact.
          type: string
        external_id:
          description: Contact identifier in an external system.
          type: string
        language:
          $ref: '#/components/schemas/ContactLanguage'
        metadata:
          description: Metadata associated with the contact. Up to 1024 characters long.
          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).
