openapi: 3.0.3
info:
  title: Collaboration API
  description: API v2 for side conversations
  version: 2.0.0
tags:
  - name: Side Conversation Attachment
  - name: Side Conversation Event
  - name: Side Conversation
paths:
  /api/v2/tickets/{ticket_id}/side_conversations:
    parameters:
      - $ref: '#/components/parameters/TicketId'
    get:
      operationId: ListSideConversations
      tags:
        - Side Conversation
      summary: List Side Conversations
      description: |
        Returns a list of side conversations on the given ticket. If a side
        conversation is a child ticket, the `external_ids` object's `targetTicketId`
        property contains the child ticket's id.

        You can sideload [side conversation events](/api-reference/ticketing/side_conversation/side_conversation_event/).

        #### Allowed for

        * Agents
      responses:
        "200":
          description: OK response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideConversationsResponse'
              examples:
                default:
                  $ref: '#/components/examples/SideConversationsResponseExample'
    post:
      operationId: CreateSideConversation
      tags:
        - Side Conversation
      summary: Create Side Conversation
      description: |
        Creates a side conversation on the ticket.

        #### Allowed for

        * Agents

        #### Request Body

        Takes a `message` object that specifies the initial message of the side
        conversation. See
        [Messages](/api-reference/ticketing/side_conversation/side_conversation_event/#messages).

        Example:

        ```json
        {
          "message": {
            "subject": "My printer is on fire!",
            "body": "The smoke is very colorful.",
            "to": [
              { "email": "someone@example.com" }
            ],
            "external_ids": { "message-external": "xyz" },
            "attachment_ids": ["s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d"]
          },
          "external_ids": { "conversation-external": "zyx" }
        }
        ```

        #### Participants

        To create a side conversation, the `message` object's `to` property must
        contain an array of one or more participant objects.

        Participant objects support the following properties:

        | Name               | Type    | Mandatory | Description                                                           |
        | ------------------ | ------- | --------- | --------------------------------------------------------------------- |
        | user_id            | integer | false     | If the participant is an agent, the agent's user id                   |
        | name               | string  | false     | The name of the participant                                           |
        | email              | string  | false     | The email address of the participant                                  |
        | slack_workspace_id | string  | false     | If the participant is a Slack user or channel, the Slack workspace id |
        | slack_channel_id   | string  | false     | If the participant is a Slack channel, the Slack channel id           |
        | support_group_id   | string  | false     | If the participant is a Support ticket, the support group id          |
        | support_agent_id   | string  | false     | If the participant is a Support ticket, the support agent id          |
        | msteams_channel_id | string  | false     | If the participant is a Microsoft teams channel, the Teams channel id |

        #### Side conversation types

        The participant object's properties determine the side conversation's type.
        The following table lists the supported participant properties for each side
        conversation type.

        | Side conversation type | Participant object properties        | Description                                                                           |
        | ---------------------- | ------------------------------------ | ------------------------------------------------------------------------------------- |
        | email                  | user_id                              | Create an email side conversation using an existing user's id                         |
        | email                  | email                                | Create an email side conversation to an external user's email                         |
        | email                  | email, name                          | Create an email side conversation specifying both email and name of an external user  |
        | slack                  | slack_workspace_id, slack_channel_id | Create a Slack side conversation in a specified channel of a Slack workspace          |
        | child ticket           | support_group_id                     | Create a child ticket assigned to a support group                                     |
        | child ticket           | support_group_id, support_agent_id   | Create a child ticket assigned to a support agent belonging to a specific group       |
        | msteams                | msteams_channel_id                   | Create a Microsoft Teams side conversation in a specified Teams channel               |

        You can't mix participant properties from different side conversation types
        in the `message` object. For example, an email side conversation can't
        contain participant objects with the `slack_workspace_id` or
        `support_group_id` properties.

        #### Creating an email side conversation

        To create an email side conversation, use participant objects with the
        `user_id` property.

        ```json {"highlightLines": [7]}
        {
          "message": {
            "subject": "My printer is on fire!",
            "body": "The smoke is very colorful.",
            "to": [
              {
                "user_id": 123
              }
            ]
          }
        }
        ```

        Alternatively, use participant objects with following properties:

        - `email`<br>
          OR<br>
          `email` and `name`

        ```json {"highlightLines": [7, 8]}
        {
          "message": {
            "subject": "My printer is on fire!",
            "body": "The smoke is very colorful.",
            "to": [
              {
                "email": "john.doe@example.com",
                "name": "John Doe"
              }
            ]
          }
        }
        ```

        #### Creating a Slack side conversation

        To create a Slack side conversation, use participant objects with the
        `slack_workspace_id` and `slack_channel_id` properties. This creates a Slack
        side conversation in the specified channel of the Slack workspace.

        **Note:** Slack side conversations are only available if an admin has
        [installed](https://support.zendesk.com/hc/en-us/articles/4408833756698) the
        latest version of [Slack for Zendesk
        Support](https://www.zendesk.com/apps/support/slack/) and [enabled side
        conversations](https://support.zendesk.com/hc/en-us/articles/4408832279962-Enabling-and-disabling-side-conversations).

        ```json {"highlightLines": [7, 8]}
        {
          "message": {
            "subject": "My printer is on fire!",
            "body": "The smoke is very colorful.",
            "to": [
              {
                "slack_workspace_id": "T123ABC",
                "slack_channel_id": "C456DEF"
              }
            ]
          }
        }
        ```

        #### Creating a child ticket side conversation

        To create a child ticket side conversation, use participant objects with the
        `support_group_id` property. This creates a child ticket assigned to the specified
        Support group.

        ```json {"highlightLines": [7]}
        {
          "message": {
            "subject": "My printer is on fire!",
            "body": "The smoke is very colorful.",
            "to": [
              {
                "support_group_id": 123
              }
            ]
          }
        }
        ```

        Alternatively, use participant objects with the `support_group_id` and
        `support_agent_id` properties. This creates a child ticket assigned to the
        specified agent in the Support group.

        ```json {"highlightLines": [7, 8]}
        {
          "message": {
            "subject": "My printer is on fire!",
            "body": "The smoke is very colorful.",
            "to": [
              {
                "support_group_id": 123,
                "support_agent_id": 456
              }
            ]
          }
        }
        ```

        #### Creating a Microsoft Teams side conversation

        To create a Microsoft Teams side conversation, use participant objects with
        the `msteams_channel_id` property. This creates a Teams side conversation
        in the specified channel.

        **Note:** Microsoft Teams side conversations are only available if a
        Zendesk admin has [installed](https://zendeskforteams.com/installation-guide)
        the latest version of [Microsoft Teams for
        Support](https://www.zendesk.com/marketplace/apps/support/767198/microsoft-teams-for-support/)
        and [enabled side
        conversations](https://support.zendesk.com/hc/en-us/articles/4408832279962-Enabling-and-disabling-side-conversations).

        ```json {"highlightLines": [7, 8]}
        {
          "message": {
            "subject": "My printer is on fire!",
            "body": "The smoke is very colorful.",
            "to": [
              {
                "msteams_channel_id": "19:xu2NZbPlloNMrbo_Z-6ksGSJ6LYauiQEP1xuBjJUXMU1@thread.tacv2"
              }
            ]
          }
        }
        ```
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SideConversationsRequest'
            examples:
              default:
                $ref: '#/components/examples/SideConversationsRequestExample'
      responses:
        "201":
          description: Created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideConversationCreatedResponse'
              examples:
                default:
                  $ref: '#/components/examples/SideConversationCreatedResponseExample'
  /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}:
    parameters:
      - $ref: '#/components/parameters/TicketId'
      - $ref: '#/components/parameters/SideConversationId'
    get:
      operationId: ShowSideConversation
      tags:
        - Side Conversation
      summary: Show Side Conversation
      description: |
        Returns a side conversation. If the side conversation is a child ticket, the
        `external_ids` object's `targetTicketId` property contains the child
        ticket's id.

        You can sideload [side conversation events](/api-reference/ticketing/side_conversation/side_conversation_event/).

        #### Allowed for

        * Agents
      responses:
        "200":
          description: OK response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideConversationThreadResponse'
              examples:
                default:
                  $ref: '#/components/examples/SideConversationThreadResponseExample'
    put:
      operationId: UpdateSideConversation
      tags:
        - Side Conversation
      summary: Update Side Conversation
      description: |
        Updates the state or subject of the side conversation.

        #### Allowed for

        * Agents

        #### Request Body

        The request takes one parameter, a `side_conversation` object that lists the values to update. All properties are optional.

        | Name    | Description                                                               |
        | ------- | ------------------------------------------------------------------------- |
        | state   | The new state of the side conversation. Possible values: "open", "closed"
        | subject | The subject of the side conversation

        Example:

        ```json
        {
           "side_conversation": {
             "state":  "closed"
           }
        }
          ```
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SideConversationThreadRequest'
            examples:
              default:
                $ref: '#/components/examples/SideConversationThreadResponseExample'
      responses:
        "200":
          description: OK response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideConversationThreadResponse'
              examples:
                default:
                  $ref: '#/components/examples/SideConversationThreadResponseExample'
  /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}/events:
    parameters:
      - $ref: '#/components/parameters/TicketId'
      - $ref: '#/components/parameters/SideConversationId'
    get:
      operationId: ListSideConversationEvents
      tags:
        - Side Conversation Event
      summary: List Side Conversation Events
      description: |
        Returns a list of side conversation events on the side conversation.

        You can sideload [side conversations](/api-reference/ticketing/side_conversation/side_conversation/).

        #### Allowed For

        * Agents
      responses:
        "200":
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideConversationEventsResponse'
              examples:
                default:
                  $ref: '#/components/examples/SideConversationEventsResponseExample'
  /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}/events/import:
    parameters:
      - $ref: '#/components/parameters/TicketId'
      - $ref: '#/components/parameters/SideConversationId'
    post:
      operationId: ImportSideConversationEvents
      tags:
        - Side Conversation
      summary: Import Side Conversation Events
      description: |
        Imports events to an existing side conversation.

        #### Allowed for

        * Agents

        #### Request Body

        Takes an `events` array of [side conversation events](/api-reference/ticketing/side_conversation/side_conversation_event/).

        Example:

        ```json
        {
          "events": [
            {
              "message": {
                "subject": "My printer is on fire!",
                "body": "The smoke is very colorful.",
                "to": [
                  { "email": "someone@example.com" }
                ],
                "from": { "email": "someone-else@example.com" },
                "external_ids": { "message-external": "xyz" },
                "attachment_ids": ["s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d"]
              },
              "created_at": "2022-10-05T20:47:02.230Z"
            }
          ]
        }
        ```
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SideConversationEventsImportRequest'
            examples:
              default:
                $ref: '#/components/examples/SideConversationEventsImportRequestExample'
      responses:
        "201":
          description: Imported response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideConversationCreatedResponse'
              examples:
                default:
                  $ref: '#/components/examples/SideConversationCreatedResponseExample'
  /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}/reply:
    parameters:
      - $ref: '#/components/parameters/TicketId'
      - $ref: '#/components/parameters/SideConversationId'
    post:
      operationId: ReplyToSideConversation
      tags:
        - Side Conversation
      summary: Reply to Side Conversation
      description: |
        Replies to a side conversation.

        #### Allowed For

        * Agents

        #### Request Body

        Takes a `message` object that specifies the message to add to the side conversation. See [Messages](/api-reference/ticketing/side_conversation/side_conversation_event/#messages).

        Example:

        ```json
        {
            "message": {
            "subject": "My printer is on fire!",
            "body":    "The smoke is very colorful.",
            "to": [
              { "email": "someone@example.com" }
            ]
          }
        }
        ```
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SideConversationsRequest'
            examples:
              default:
                $ref: '#/components/examples/SideConversationsRequestExample'
      responses:
        "200":
          description: OK response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideConversationThreadResponse'
              examples:
                default:
                  $ref: '#/components/examples/SideConversationThreadResponseExample'
  /api/v2/tickets/{ticket_id}/side_conversations/import:
    parameters:
      - $ref: '#/components/parameters/TicketId'
    post:
      operationId: ImportSideConversation
      tags:
        - Side Conversation
      summary: Import Side Conversation
      description: |
        Imports a side conversation on the ticket.

        #### Allowed for

        * Agents

        #### Request Body

        Takes a `side_conversation` object and an `events` array of [side conversation events](/api-reference/ticketing/side_conversation/side_conversation_event/).

        Example:

        ```json
        {
          "side_conversation": {
            "subject": "I have problems",
            "state": "open",
            "external_ids": {
              "threadExternalId": "thread-external"
            }
          },
          "events": [
            {
              "created_at": "2022-10-05T20:47:02.230Z",
              "message": {
                "subject": "My printer is on fire!",
                "body": "The smoke is very colorful.",
                "to": [
                  { "email": "someone@example.com" }
                ],
                "from": { "email": "someone-else@example.com" },
                "external_ids": { "message-external": "xyz" },
                "attachment_ids": ["s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d"]
              }
            }
          ]
        }
        ```
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SideConversationImportRequest'
            examples:
              default:
                $ref: '#/components/examples/SideConversationImportRequestExample'
      responses:
        "201":
          description: Imported response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideConversationCreatedResponse'
              examples:
                default:
                  $ref: '#/components/examples/SideConversationCreatedResponseExample'
  /api/v2/tickets/side_conversations/attachments:
    post:
      operationId: CreateSideConversationAttachments
      tags:
        - Side Conversation Attachment
      summary: Create Side Conversation Attachments
      description: |
        Creates a new side conversation attachment.

        #### Allowed For

         * Agents

        #### Request Body

        Takes a file object as multipart/form-data for the uploaded attachment.
      responses:
        "201":
          description: Created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideConversationAttachmentResponse'
              examples:
                default:
                  $ref: '#/components/examples/SideConversationAttachmentResponseExample'
  /api/v2/tickets/side_conversations/events:
    parameters:
      - $ref: '#/components/parameters/IncrementalTimeQueryParameter'
    get:
      operationId: IncrementalSideConversationEvents
      tags:
        - Side Conversation Event
      summary: Incremental Side Conversation Event Export
      description: |
        Returns the side conversation events created since the start time. See [start_time](/api-reference/ticketing/ticket-management/incremental_exports/#start_time).

        #### Allowed for

        * Admins
      responses:
        "200":
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncrementalSideConversationEventResponse'
              examples:
                default:
                  $ref: '#/components/examples/IncrementalSideConversationEventResponseExample'
components:
  schemas:
    ConversationUserObject:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
          nullable: true
        user_id:
          type: integer
          nullable: true
    ImportEventsArray:
      type: array
      items:
        type: object
        properties:
          created_at:
            type: string
            description: The time the side conversation was created
          message:
            $ref: '#/components/schemas/MessageObject'
    IncrementalSideConversationEventResponse:
      type: object
      properties:
        count:
          type: integer
          description: The number of events returned
        end_time:
          type: integer
          description: The unix time of the last event
          nullable: true
        events:
          type: array
          description: An array of side conversation events
          items:
            $ref: '#/components/schemas/SideConversationEventResponse'
        next_page:
          type: string
          description: The next page of paginated results
      example:
        count: 1
        end_time: 1383685952
        events:
          - actor:
              email: johnny@example.com
              name: Johnny Agent
              user_id: 35436
            created_at: "2018-11-20T16:58:36.453+00:00"
            id: 8566255a-ece5-11e8-857d-493066fa7b17
            message:
              body: I was trying to print an email when the printer suddenly started burning
              from:
                email: johnny@example.com
                name: Johnny Agent
                user_id: 35436
              html_body: I was trying to print an email when the printer suddenly started <strong>burning</strong>
              preview_text: I was trying to print an email when the printer suddenly
              subject: Help, my printer is on fire!
              to:
                - email: bob@example.com
                  name: null
                  user_id: null
              via: support
            side_conversation_id: 8566255a-ece5-11e8-857d-493066fa7b17
            type: reply
            via: support
        next_page: https://{subdomain}.zendesk.com/api/v2/tickets/side_conversations/events.json?start_time=1383685952
    MessageObject:
      type: object
      properties:
        body:
          type: string
        from:
          type: object
          properties:
            email:
              type: string
            name:
              type: string
            user_id:
              type: number
          additionalProperties: true
        html_body:
          type: string
        preview_text:
          type: string
        subject:
          type: string
        to:
          type: array
      required:
        - to
    SideConversationAttachmentResponse:
      title: Side Conversation Attachments
      type: object
      properties:
        content_type:
          type: string
          description: The content type of the attachment
          readOnly: true
        height:
          type: integer
          description: The height of the attachment image
          readOnly: true
        id:
          type: string
          description: The id of the side conversation attachment
          readOnly: true
        name:
          type: string
          description: The name of the attachment
        size:
          type: integer
          description: The size of the attachment
          readOnly: true
        width:
          type: integer
          description: The width of the attachment image
          readOnly: true
      example:
        content_type: image/png
        height: 214
        id: s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d
        name: image.png
        size: 50645
        width: 406
    SideConversationCreatedResponse:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/SideConversationEvent'
        side_conversation:
          $ref: '#/components/schemas/SideConversationResponse'
        updates:
          type: object
          nullable: true
    SideConversationEvent:
      type: object
      properties:
        actor:
          type: object
          properties:
            email:
              type: string
            name:
              type: string
            user_id:
              type: integer
        created_at:
          type: string
        error:
          type: string
          nullable: true
        id:
          type: string
        message:
          type: object
          properties:
            attachments:
              type: array
              items:
                type: object
                properties:
                  content_type:
                    type: string
                  content_url:
                    type: string
                  file_name:
                    type: string
                  height:
                    type: integer
                  id:
                    type: string
                  inline:
                    type: boolean
                  size:
                    type: integer
                  width:
                    type: integer
            body:
              type: string
            external_ids:
              type: object
              properties:
                message-external:
                  type: string
            from:
              type: object
              properties:
                email:
                  type: string
                name:
                  type: string
                user_id:
                  type: integer
            html_body:
              type: string
            preview_text:
              type: string
            subject:
              type: string
            to:
              type: array
              items:
                type: object
                properties:
                  email:
                    type: string
                  name:
                    type: string
                    nullable: true
                  user_id:
                    type: integer
                    nullable: true
        side_conversation_id:
          type: string
        ticket_id:
          type: integer
        type:
          type: string
        updates:
          type: object
        via:
          type: string
    SideConversationEventResponse:
      title: Side Conversation Events
      type: object
      properties:
        actor:
          type: object
          description: The participant who created the event. See [Participants](/api-reference/ticketing/side_conversation/side_conversation/#participants)
          additionalProperties: true
          readOnly: true
        created_at:
          type: string
          description: The time the side converation event was created
          readOnly: true
        id:
          type: string
          description: Automatically assigned when the event is created
          readOnly: true
        message:
          type: object
          description: Events of type "create" and "reply" have a message. See [Messages](#messages)
          additionalProperties: true
          nullable: true
          readOnly: true
        side_conversation_id:
          type: string
          description: The id of the side conversation the event belongs to
          readOnly: true
        ticket_id:
          type: integer
          description: The parent ticket id of the side conversation
          nullable: true
          readOnly: true
        type:
          type: string
          description: The type of event
          readOnly: true
        updates:
          type: object
          description: Events of type "update" have fields here. See [Updates](#updates)
          additionalProperties: true
          readOnly: true
        url:
          type: string
          description: The API url of the side conversation
          readOnly: true
        via:
          type: string
          description: The channel used when creating the event. See the [Via object reference](/documentation/ticketing/reference-guides/via-object-reference/)
          readOnly: true
      example:
        actor:
          email: johnny@example.com
          name: Johnny Agent
          user_id: 35436
        created_at: "2018-11-20T16:58:36.453+00:00"
        id: 8566255a-ece5-11e8-857d-493066fa7b17
        message:
          body: I was trying to print an email when the printer suddenly started burning
          from:
            email: johnny@example.com
            name: Johnny Agent
            user_id: 35436
          html_body: I was trying to print an email when the printer suddenly started <strong>burning</strong>
          preview_text: I was trying to print an email when the printer suddenly
          subject: Help, my printer is on fire!
          to:
            - email: bob@example.com
              name: null
              user_id: null
          via: support
        side_conversation_id: 8566255a-ece5-11e8-857d-493066fa7b17
        type: reply
        via: support
    SideConversationEventsImportRequest:
      type: object
      properties:
        events:
          $ref: '#/components/schemas/ImportEventsArray'
    SideConversationEventsResponse:
      type: object
      properties:
        count:
          type: integer
        events:
          type: array
          items:
            $ref: '#/components/schemas/SideConversationEventResponse'
        next_page:
          type: string
          nullable: true
        previous_page:
          type: string
          nullable: true
    SideConversationImportRequest:
      type: object
      properties:
        events:
          $ref: '#/components/schemas/ImportEventsArray'
        side_conversation:
          type: object
          properties:
            external_ids:
              type: object
              description: A key-value store of metadata. All values must be strings
              additionalProperties: true
            state:
              type: string
              description: The state of the side conversation
            subject:
              type: string
              description: The subject of the side conversation
    SideConversationResponse:
      type: object
      properties:
        created_at:
          type: string
          description: The time the side conversation was created
          readOnly: true
        external_ids:
          type: object
          description: A key-value store of metadata. All values must be strings
          properties:
            my_system_id:
              type: string
        id:
          type: string
          description: Automatically assigned when the side conversation is created
          readOnly: true
        message_added_at:
          type: string
          description: The time of the last message on the side conversation
          readOnly: true
        participants:
          type: array
          description: An array of participants in the side conversation. See [Participants](/api-reference/ticketing/side_conversation/side_conversation/#participants)
          items:
            $ref: '#/components/schemas/ConversationUserObject'
          readOnly: true
        preview_text:
          type: string
          description: A plain text text describing the side conversation
          readOnly: true
        state:
          type: string
          description: The state of the side conversation
        state_updated_at:
          type: string
          description: The time of the update of the state of the side conversation
          readOnly: true
        subject:
          type: string
          description: The subject of the side conversation
        ticket_id:
          type: integer
          description: The parent ticket id of the side conversation
          nullable: true
          readOnly: true
        updated_at:
          type: string
          description: The time of the last update of the side conversation
          readOnly: true
        url:
          type: string
          description: The API url of the side conversation
          readOnly: true
      example:
        created_at: "2018-11-20T16:58:36.453+00:00"
        external_ids:
          my_system_id: abc-123-xyz
        id: 8566255a-ece5-11e8-857d-493066fa7b17
        message_added_at: "2018-11-20T16:58:36.453+00:00"
        participants:
          - email: johnny@example.com
            name: Johnny Agent
            user_id: 35436
          - email: bob@example.com
            name: null
            user_id: null
        preview_text: I was trying to print an email when the printer suddenly started burning
        state: open
        state_updated_at: "2018-11-20T16:58:36.453+00:00"
        subject: Help, my printer is on fire!
        ticket_id: 12345
        updated_at: "2018-11-20T16:58:36.453+00:00"
        url: https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17
    SideConversationThreadRequest:
      type: object
      properties:
        side_conversation:
          $ref: '#/components/schemas/SideConversationResponse'
    SideConversationThreadResponse:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/SideConversationEventResponse'
        side_conversation:
          $ref: '#/components/schemas/SideConversationResponse'
    SideConversationsRequest:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/MessageObject'
    SideConversationsResponse:
      type: object
      properties:
        count:
          type: integer
        next_page:
          type: string
          nullable: true
        previous_page:
          type: string
          nullable: true
        side_conversations:
          type: array
          items:
            $ref: '#/components/schemas/SideConversationResponse'
  parameters:
    IncrementalTimeQueryParameter:
      name: start_time
      in: query
      description: A query start time for incremental exports
      required: true
      schema:
        type: integer
      example: 1383685952
    SideConversationId:
      name: side_conversation_id
      in: path
      description: The id of the side conversation
      required: true
      schema:
        type: string
      examples:
        default:
          value: e9ad3991-35e8-445e-a8cc-3d56862cb1f7
        fixture/context=default:
          externalValue: zoas-cache:/CreateSideConversation/201/application/json#/side_conversation/id
    TicketId:
      name: ticket_id
      in: path
      description: The id of the ticket
      required: true
      schema:
        type: integer
      example: 1
  examples:
    IncrementalSideConversationEventResponseExample:
      value:
        count: 1
        end_time: 1383685952
        events:
          - actor:
              email: johnny@example.com
              name: Johnny Agent
              user_id: 35436
            created_at: "2018-11-20T16:58:36.453+00:00"
            id: 8566255a-ece5-11e8-857d-493066fa7b17
            message:
              body: I was trying to print an email when the printer suddenly started burning
              from:
                email: johnny@example.com
                name: Johnny Agent
                user_id: 35436
              html_body: I was trying to print an email when the printer suddenly started <strong>burning</strong>
              preview_text: I was trying to print an email when the printer suddenly
              subject: Help, my printer is on fire!
              to:
                - email: bob@example.com
                  name: null
                  user_id: null
              via: support
            side_conversation_id: 8566255a-ece5-11e8-857d-493066fa7b17
            type: reply
            via: support
        next_page: https://{subdomain}.zendesk.com/api/v2/tickets/side_conversations/events.json?start_time=1383685952
    SideConversationAttachmentResponseExample:
      value:
        content_type: image/png
        height: 214
        id: s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d
        name: image.png
        size: 50645
        width: 406
    SideConversationCreatedResponseExample:
      value:
        event:
          actor:
            email: sally@company.com
            name: Agent Sally
            user_id: 2
          created_at: "2017-10-27T17:56:16.678Z"
          id: 9e19e100-abd5-11e8-b66e-af698c6d193c
          message:
            attachments:
              - content_type: image/png
                content_url: http://www.example.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17/attachments/s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d/download/image.png
                file_name: image.png
                height: 214
                id: s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d
                inline: false
                size: 50645
                width: 406
            body: The smoke is very colorful.
            external_ids:
              message-external: xyz
            from:
              email: sally@company.com
              name: Agent Sally
              user_id: 2
            html_body: <div class="zd-comment"><p>The smoke is very colorful.</p></div>
            preview_text: My printer is on fire!
            subject: My printer is on fire!
            to:
              - email: someone@example.com
                name: null
                user_id: null
          side_conversation_id: 8566255a-ece5-11e8-857d-493066fa7b17
          type: create
          via: api
        side_conversation:
          created_at: "2018-11-20T16:58:36.453+00:00"
          external_ids:
            my_system_id: abc-123-xyz
          id: 8566255a-ece5-11e8-857d-493066fa7b17
          message_added_at: "2018-11-20T16:58:36.453+00:00"
          participants:
            - email: johnny@example.com
              name: Johnny Agent
              user_id: 35436
            - email: bob@example.com
              name: null
              user_id: null
          preview_text: I was trying to print an email when the printer suddenly started burning
          state: open
          state_updated_at: "2018-11-20T16:58:36.453+00:00"
          subject: Help, my printer is on fire!
          updated_at: "2018-11-20T16:58:36.453+00:00"
          url: https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17
        updates: {}
    SideConversationEventResponseExample:
      value:
        actor:
          email: johnny@example.com
          name: Johnny Agent
          user_id: 35436
        created_at: "2018-11-20T16:58:36.453+00:00"
        id: 8566255a-ece5-11e8-857d-493066fa7b17
        message:
          body: I was trying to print an email when the printer suddenly started burning
          from:
            email: johnny@example.com
            name: Johnny Agent
            user_id: 35436
          html_body: I was trying to print an email when the printer suddenly started <strong>burning</strong>
          preview_text: I was trying to print an email when the printer suddenly
          subject: Help, my printer is on fire!
          to:
            - email: bob@example.com
              name: null
              user_id: null
          via: support
        side_conversation_id: 8566255a-ece5-11e8-857d-493066fa7b17
        type: reply
        via: support
    SideConversationEventsImportRequestExample:
      value:
        events:
          - created_at: "2022-10-05T20:47:02.230Z"
            message:
              body: The smoke is very colorful.
              from:
                email: someone-else@example.com
              subject: My printer is on fire!
              to:
                - email: someone@example.com
    SideConversationEventsResponseExample:
      value:
        count: 1
        events:
          - actor:
              email: johnny@example.com
              name: Johnny Agent
              user_id: 35436
            created_at: "2018-11-20T16:58:36.453+00:00"
            id: 8566255a-ece5-11e8-857d-493066fa7b17
            message:
              body: I was trying to print an email when the printer suddenly started burning
              from:
                email: johnny@example.com
                name: Johnny Agent
                user_id: 35436
              html_body: I was trying to print an email when the printer suddenly started <strong>burning</strong>
              preview_text: I was trying to print an email when the printer suddenly
              subject: Help, my printer is on fire!
              to:
                - email: bob@example.com
                  name: null
                  user_id: null
              via: support
            side_conversation_id: 8566255a-ece5-11e8-857d-493066fa7b17
            type: reply
            via: support
        next_page: null
        previous_page: null
    SideConversationImportRequestExample:
      value:
        events:
          - created_at: "2022-10-05T20:47:02.23Z"
            message:
              body: The smoke is very colorful.
              from:
                email: someone-else@example.com
              subject: My printer is on fire!
              to:
                - email: someone@example.com
        side_conversation:
          external_ids:
            threadExternalId: thread-external
          state: open
          subject: I have problems
    SideConversationResponseExample:
      value:
        created_at: "2018-11-20T16:58:36.453+00:00"
        external_ids:
          my_system_id: abc-123-xyz
        id: 8566255a-ece5-11e8-857d-493066fa7b17
        message_added_at: "2018-11-20T16:58:36.453+00:00"
        participants:
          - email: johnny@example.com
            name: Johnny Agent
            user_id: 35436
          - email: bob@example.com
            name: null
            user_id: null
        preview_text: I was trying to print an email when the printer suddenly started burning
        state: open
        state_updated_at: "2018-11-20T16:58:36.453+00:00"
        subject: Help, my printer is on fire!
        updated_at: "2018-11-20T16:58:36.453+00:00"
        url: https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17
    SideConversationThreadResponseExample:
      value:
        side_conversation:
          created_at: "2018-11-20T16:58:36.453+00:00"
          external_ids:
            my_system_id: abc-123-xyz
          id: 8566255a-ece5-11e8-857d-493066fa7b17
          message_added_at: "2018-11-20T16:58:36.453+00:00"
          participants:
            - email: johnny@example.com
              name: Johnny Agent
              user_id: 35436
            - email: bob@example.com
              name: null
              user_id: null
          preview_text: I was trying to print an email when the printer suddenly started burning
          state: open
          state_updated_at: "2018-11-20T16:58:36.453+00:00"
          subject: Help, my printer is on fire!
          updated_at: "2018-11-20T16:58:36.453+00:00"
          url: https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17
    SideConversationsRequestExample:
      value:
        message:
          body: The smoke is very colorful.
          subject: My printer is on fire!
          to:
            - email: someone@example.com
    SideConversationsResponseExample:
      value:
        count: 1
        next_page: null
        previous_page: null
        side_conversations:
          - created_at: "2018-11-20T16:58:36.453+00:00"
            external_ids:
              my_system_id: abc-123-xyz
            id: 8566255a-ece5-11e8-857d-493066fa7b17
            message_added_at: "2018-11-20T16:58:36.453+00:00"
            participants:
              - email: johnny@example.com
                name: Johnny Agent
                user_id: 35436
              - email: bob@example.com
                name: null
                user_id: null
            preview_text: I was trying to print an email when the printer suddenly started burning
            state: open
            state_updated_at: "2018-11-20T16:58:36.453+00:00"
            subject: Help, my printer is on fire!
            updated_at: "2018-11-20T16:58:36.453+00:00"
            url: https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
