openapi: "3.0.1"
info:
  title: "Conversations API"
  version: "1.0"
paths:
  /api/v1/conversation-items:
    post:
      tags:
        - Conversations
      summary: "Create item"
      description: |
        To add items to the timeline for a customer specified by identifying information. If the customer doesn't exist, a new customer profile is created.

        Any items created using this API will not be considered part of a conversation, and are **non-routable** and **non-searchable** aside from the mobile phone number or email address specified as part of the payload.
      operationId: createItem
      requestBody:
        description: "Conversation Item to create"
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/ConversationItemRequestContentWithCustomer"
            examples:
              Customer Activity:
                $ref: "#/components/examples/CustomerActivityWithCustomer"
        required: true
      responses:
        200:
          description: "The created item"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/CreatableConversationItem"
        400:
          description: "Invalid field(s) in request body"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
        409:
          description: "Specified id is in use"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
              example:
                errors:
                  - attr: "newConversationItems"
                    code: "taken"
                    detail: "conversation item already exists"

  /api/v1/conversation-items/{itemId}:
    get:
      tags:
        - Conversations
      summary: "Get item"
      description: |
        Returns the conversation item with the provided id.
      operationId: getItem
      parameters:
        - in: path
          name: itemId
          description: |
            id of the conversation item
          schema:
            type: string
            example: "pOVVdzweSumI4bFxjlT8LA"
          required: true
      responses:
        200:
          description: "conversation item"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ConversationItem"
        400:
          description: "An item exists but is not supported by the API"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
              example:
                errors:
                  - code: "invalid"
                    detail: "Conversation item with id [pOVVdzweSumI4bFxjlT8LA] exists but is not supported by the API."
        404:
          description: "An item with the given id could not be found"

    delete:
      tags:
        - Conversations
      summary: "Delete item"
      description: |
        To delete an item.

        Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by this API.
      operationId: deleteItem
      parameters:
        - in: path
          name: itemId
          schema:
            type: string
          required: true
          description: |
            Id of the item to be deleted.
      responses:
        204:
          description: "The item was deleted"
        404:
          description: "An item with the given id could not be found"

  /api/v1/conversation-items/{itemId}/attachments/{attachmentId}:
    get:
      tags:
        - Conversations
      summary: "Get attachment"
      description: |
        Returns a redirect to the URL of the specified attachment on a conversation item.

        The response is a `303 See Other` redirect. Follow the redirect to download the attachment content.

        Attachments are available on conversation items with content types that support them, such as emails, chat messages, SMS messages, and custom channel messages.
      operationId: getAttachment
      parameters:
        - in: path
          name: itemId
          schema:
            type: string
            example: "pOVVdzweSumI4bFxjlT8LA"
          required: true
          description: |
            Id of the conversation item that contains the attachment.
        - in: path
          name: attachmentId
          schema:
            type: string
            example: "dGhpcyBpcyBhbiBhdHRhY2htZW50"
          required: true
          description: |
            Id of the attachment to retrieve.
      responses:
        303:
          description: "Redirect to the attachment URL"
          headers:
            Location:
              schema:
                type: string
              description: |
                URL to download the attachment content.
        400:
          description: "The conversation item content does not contain attachments"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
              example:
                errors:
                  - code: "invalid"
                    detail: "conversation item content does not contain attachments"
        404:
          description: "The conversation item or attachment could not be found"

  /api/v1/conversations/{conversationId}/topics:
    post:
      tags:
        - Conversations
      summary: "Add Topics to Conversation"
      description: |
        Adds a list of topics to the conversation. If a topic being added already exists on the conversation, that topic is ignored.
      operationId: addTopicToConversation
      parameters:
        - in: path
          name: conversationId
          schema:
            type: string
          required: true
          description: |
            Id of the conversation.
      requestBody:
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/ConversationTopicAdd"
            examples:
              Conversation Topic:
                $ref: "#/components/examples/ConversationTopic"

        required: true
      responses:
        204:
          description: "The topic was added successfully"
        400:
          description: "Invalid field(s) in request body"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
        404:
          description: "A conversation with the given Id could not be found"
        410:
          description: "The conversation id no longer exists because the conversation was merged into another conversation"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/ErrorsWithMeta"
              examples:
                Merged conversation:
                  $ref: "#/components/examples/ConversationMovedErr"

  /api/v1/conversations/{conversationId}/topics/{topicId}:
    delete:
      tags:
        - Conversations
      summary: "Delete Topic from Conversation"
      description: |
        Delete a topic from a conversation.
      operationId: deleteTopicFromConversation
      parameters:
        - in: path
          name: conversationId
          schema:
            type: string
          required: true
          description: |
            Id of the conversation.
        - in: path
          name: topicId
          schema:
            type: string
          required: true
          description: |
            Id of topic to be deleted from conversation.
      responses:
        204:
          description: "The topic was deleted from the conversation successfully"
        404:
          description: "A conversation with the given id could not be found"
        410:
          description: "The conversation id no longer exists because the conversation was merged into another conversation"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/ErrorsWithMeta"
              examples:
                Merged conversation:
                  $ref: "#/components/examples/ConversationMovedErr"

  /api/v1/customer-history/{customerId}/conversations/{conversationId}/custom-attributes:
    post:
      tags:
        - Conversations
      summary: "Add or Remove Freeform topic"
      description: |
        Adds or removes a list of freeform topics to the conversation. If the freeform topic being added already exists on the conversation, that topic is ignored.
      parameters:
        - in: path
          name: customerId
          schema:
            type: string
          required: true
          description: |
            Id of the customer.
        - in: path
          name: conversationId
          schema:
            type: string
          required: true
          description: |
            Id of the conversation.
      requestBody:
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/ConversationFreeformTopicAddOrRemove"
            examples:
              Custom Attributes:
                $ref: "#/components/examples/ConversationFreeformTopicAddOrRemove"

        required: true
      responses:
        204:
          description: "The freeform topic was added successfully"
        400:
          description: "Invalid field(s) in request body"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/NotFoundErrors"
        404:
          description: "A conversation with the given Id could not be found"
        410:
          description: "The conversation id no longer exists because the conversation was merged into another conversation"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/ErrorsWithMeta"
              examples:
                Merged conversation:
                  $ref: "#/components/examples/ConversationMovedErr"

  /api/v1/conversation-items/{itemId}/reply:
    post:
      tags:
        - Conversations
      summary: "Reply to message"
      description: Sends a response to a conversation item. If no agent is assigned to the conversation, the conversation is assigned to the API User who made this call.
      operationId: replyToMessage
      parameters:
        - in: path
          name: itemId
          description: |
            id of the conversation item
          schema:
            type: string
            example: "pOVVdzweSumI4bFxjlT8LA"
          required: true
      requestBody:
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/Message"
            examples:
              Reply with email:
                $ref: "#/components/examples/EmailReplyMessage"
              Reply with chat message:
                $ref: "#/components/examples/ChatMessageReplyMessage"
              Reply with chat quick reply:
                $ref: "#/components/examples/ChatQuickReplyReplyMessage"
              Reply with facebook message:
                $ref: "#/components/examples/FacebookReplyMessage"
              Reply with instagram direct message:
                $ref: "#/components/examples/InstagramDirectReplyMessage"
              Reply with sms message:
                $ref: "#/components/examples/SmsReplyMessage"
              Reply with twitter direct message (decommissioned as of 04/20/2023):
                $ref: "#/components/examples/TwitterReplyMessage"
              Reply with whatsapp message:
                $ref: "#/components/examples/WhatsAppReplyMessage"
      responses:
        201:
          description: "The reply was created successfully. Note that creation doesn't guarantee delivery"
          headers:
            Location:
              schema:
                description: "Relative URL of the created message"
                example: "/api/v1/conversation-items/HVFDjpu1SCKJlDR7rRKkCQ"
        400:
          description: "Invalid field(s) in request body"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
              examples:
                Closed conversation:
                  $ref: "#/components/examples/ReplyClosedConversationErr"
                Empty type:
                  $ref: "#/components/examples/ReplyEmptyTypeErr"
                Wrong type:
                  $ref: "#/components/examples/ReplyWrongTypeErr"
                Body too long:
                  $ref: "#/components/examples/ReplyTooLongErr"
                Not a customer message:
                  $ref: "#/components/examples/NotACustomerErr"


        404:
          description: "A conversation item with the given id could not be found"

  /api/v1/conversation-items/{itemId}/redact:
    post:
      tags:
        - Conversations
      summary: "Redact conversation item"
      description: |
        For supported items, the item's content will be removed but the item will
        remain in the conversation timeline. Supported types are Chat Message,
        SMS Message, Email, Twitter (decommissioned as of 04/20/23, but can still be redacted), WhatsApp, Voicemail, Phone Call.
      operationId: redactContent
      parameters:
        - in: path
          name: itemId
          description: |
            id of the conversation item
          schema:
            type: string
            example: "pOVVdzweSumI4bFxjlT8LA"
          required: true
      requestBody:
        content:
          "application/json":
            schema:
              description: The request body should be empty
      responses:
        201:
          description: "The redaction was successful."
          headers:
            Location:
              schema:
                description: "Relative URL of the redacted item"
                example: "/api/v1/conversation-items/HVFDjpu1SCKJlDR7rRKkCQ"
        404:
          description: "A conversation item with the given id could not be found"

  /api/v1/conversations/{conversationId}/notes:
    post:
      tags:
        - Conversations
      summary: "Add note"
      description:
        Adds note to an existing conversation.
      operationId: addNoteToConversation
      parameters:
        - in: path
          name: conversationId
          schema:
            type: string
          required: true
          description: |
            Id of the conversation.
      requestBody:
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/ConversationNoteAdd"
            examples:
              Conversation Note:
                $ref: "#/components/examples/ConversationNote"
      responses:
        201:
          description: "The note was added successfully"
          headers:
            Location:
              schema:
                description: "Relative URL of the created note"
                example: "/api/v1/conversations/cHBetnP5QYiwg-rvfaVDAQ/notes/HVFDjpu1SCKJlDR7rRKkCQ"
        400:
          description: "Invalid field(s) in request body"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
        404:
          description: "A conversation with the given Id could not be found"
        410:
          description: "The conversation id no longer exists because the conversation was merged into another conversation"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/ErrorsWithMeta"
              examples:
                Merged conversation:
                  $ref: "#/components/examples/ConversationMovedErr"


  /api/v1/conversations/{conversationId}/notes/{noteId}:
    get:
      tags:
        - Conversations
      summary: "Get note"
      description: |
        Returns the note with the provided conversation and note id.
      operationId: getNoteFromConversation
      parameters:
        - in: path
          name: conversationId
          description: |
            id of the conversation
          schema:
            type: string
            example: "pOVVdzweSumI4bFxjlT8LA"
          required: true
        - in: path
          name: noteId
          description: |
            id of the note
          schema:
            type: string
            example: "aOVVdzweSumI4bFxjlT8LA"
          required: true

      responses:
        200:
          description: "Conversation note"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ConversationNote"
        404:
          description: "An item with the given id could not be found"


  /api/v1/conversation-items/{itemId}/media/recording:
    get:
      tags:
        - Conversations
      summary: "Get media"
      description: |
        Returns the media file associated with the conversation item
      operationId: getMedia
      parameters:
        - in: path
          name: itemId
          description: |
            id of the conversation item
          schema:
            type: string
            example: "pOVVdzweSumI4bFxjlT8LA"
          required: true
      responses:
        200:
          description: "The media file associated with the conversation item"
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
                description: "Single channel 32-kbps MP3 audio file"
        404:
          description: "An item with the given id could not be found"

  /api/v1/conversation-items/{itemId}/voice-transcript:
    get:
      tags:
        - Conversations
      summary: "Get voice transcript"
      description: |
        Returns a transcript of a phone call or a voicemail
      operationId: getVoiceTranscript
      parameters:
        - in: path
          name: itemId
          description: |
            id of the conversation item
          schema:
            type: string
            example: "pOVVdzweSumI4bFxjlT8LA"
          required: true
      responses:
        200:
          description: "The voice transcript of a phone call or a voicemail"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/VoiceTranscript"
        404:
          description: "A transcript with the given id could not be found"

  /api/v1/customers/{customerId}/conversation-items:
    post:
      tags:
        - Conversations
      summary: "Create item for customer"
      description: |
        To add items to a customer's timeline.

        Any items created using this API will not be considered part of a conversation, and are **non-routable** and **non-searchable** aside from the mobile phone number or email address specified as part of the payload.
      operationId: createCustomerItem
      parameters:
        - in: path
          name: customerId
          schema:
            type: string
          required: true
          description: |
            Id of the customer associated with this item.

            You can look up the id using the [Find customers](index.html#tag/Customers) API.
      requestBody:
        description: "Conversation Item to create"
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/ConversationItemRequestContent"
            examples:
              Customer Activity:
                $ref: "#/components/examples/CustomerActivity"

      responses:
        200:
          description: "The created item"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/CreatableConversationItem"
        410:
          description: "The customer id no longer exists because the customer was merged into another customer"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/ErrorsWithMeta"
              examples:
                Merged customer:
                  $ref: "../openapi.yaml#/components/examples/CustomerMovedErr"
        400:
          description: "Invalid field(s) in request body"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
        404:
          description: "Customer with customerId does not exist"
        409:
          description: "Specified id is in use"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
              example:
                errors:
                  - attr: "newConversationItems"
                    code: "taken"
                    detail: "conversation item already exists"

  /api/v1/customers/{customerId}/conversation-items/{itemId}:
    delete:
      tags:
        - Conversations
      summary: "Delete item for customer"
      description: |
        To delete an item.

        Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by this API.
      operationId: deleteCustomerItem
      parameters:
        - in: path
          name: customerId
          schema:
            type: string
          required: true
          description: |
            Id of the customer associated with this item.

            You can look up the id using the [Find customers](index.html#tag/Customers) API.
        - in: path
          name: itemId
          schema:
            type: string
          required: true
          description: |
            Id of the item to be deleted.
      responses:
        204:
          description: "The item was deleted"
        404:
          description: "An item with the given id, for the given customer id, could not be found"

  /api/v1/customers/{customerId}/conversations:
    get:
      tags:
        - Conversations
      summary: "Get conversations for customer"
      description: |
        Get the list of conversations for a customer.
        The list is not paginated and will return at most 100 conversations.
        The conversations are returned in ascending order by timestamp.
        The `Gladly-Limited-Data` header flag in the response will indicate if the customer has more conversations than returned.
      operationId: getConversations
      parameters:
        - in: path
          name: customerId
          schema:
            type: string
          required: true
          description: "Id of the customer to get all conversations for"
          example: "gHufx-U3QqOmhvFuViceTw"
      responses:
        200:
          description: "The conversations for the customer"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Conversations"
              examples:
                Conversations:
                  $ref: "#/components/examples/Conversations"

  /api/v1/conversations/{conversationId}:
    get:
      tags:
        - Conversations
      summary: "Get conversation"
      description: |
        Get conversation metadata such as it's assignee, topics, inbox, etc.

        If the conversation has been merged into another conversation, `301 Moved Permanently` is returned instead. The `Location` header points at the surviving conversation, so clients that follow redirects receive it transparently — note that its `id` differs from the one requested. Clients that do not follow redirects can read the surviving id from `meta.new` in the response body.
      operationId: getConversation
      parameters:
        - in: path
          name: conversationId
          schema:
            type: string
          required: true
          description: "Id of the conversation to get"
          example: "9BcE2O0DQ2ynGHRmk9FeoA"
      responses:
        200:
          description: "Conversation metadata"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Conversation"
              examples:
                Conversation:
                  $ref: "#/components/examples/Conversation"
        301:
          description: "The conversation id no longer exists because the conversation was merged into another conversation"
          headers:
            Location:
              description: "Relative URL of the surviving conversation"
              schema:
                type: string
                example: "/api/v1/conversations/rVamfZHvQuORFnsk-3mNuw"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/ErrorsWithMeta"
              examples:
                Merged conversation:
                  $ref: "#/components/examples/ConversationMovedErr"
        404:
          description: "A conversation with the given id does not exist"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
              example:
                errors:
                  - code: not_exist
                    detail: conversation does not exist
    patch:
      tags:
        - Conversations
      summary: "Update conversation"
      description: |
        Update conversation assignee, status or both.

        If the conversation has been merged into another conversation, `410 Gone` is returned and the response body carries the id of the surviving conversation. Reissue the update against that id.
      operationId: patchConversation
      parameters:
        - in: path
          name: conversationId
          schema:
            type: string
          required: true
          description: "Id of the conversation"
          example: "9BcE2O0DQ2ynGHRmk9FeoA"
      requestBody:
        required: true
        description: "JSON representation of conversation updates"
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/ConversationUpdate"
            example:
              assignee:
                inboxId: "E1nArq1uQAees_DogHB0MA"
                agentId: "sHuXx-U3QqOmhvFusJGeBw"
              status:
                value: CLOSED
                force: true
      responses:
        204:
          description: "updated conversation"
        404:
          description: "A conversation with the given id does not exist"
          content:
            application/json:
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
              example:
                errors:
                  - code: not_exist
                    detail: conversation does not exist
        410:
          description: "The conversation id no longer exists because the conversation was merged into another conversation"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/ErrorsWithMeta"
              examples:
                Merged conversation:
                  $ref: "#/components/examples/ConversationMovedErr"
        400:
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "../openapi.yaml#/components/schemas/Errors"
              examples:
                "some required fields are blank":
                  value:
                    errors:
                      - attr: assignee.inboxId
                        code: blank
                        detail: "'inboxId' cannot be blank when updating assignee"
                      - attr: status.value
                        code: blank
                        detail: "'value' cannot be blank when updating status"
                "agent does not belong to inbox":
                  value:
                    errors:
                      - attr: assignee.agentId
                        code: invalid_state
                        detail: agent does not belong to inbox
                "reassigning closed conversation":
                  value:
                    errors:
                      - code: invalid_state
                        detail: closed conversation cannot be reassigned
                "topics required before closing conversation":
                  value:
                    errors:
                      - code: invalid_state
                        detail: topics are required before closing of conversation
                "customer waiting for response":
                  value:
                    errors:
                      - code: invalid_state
                        detail: cannot close conversation, customer waiting for response, set 'status.force' to true to override


  /api/v1/conversations/{conversationId}/items:
    get:
      tags:
        - Conversations
      summary: "List items in conversation"
      description: |
        Get the list of items in the timeline of a conversation.
        The conversation represents a period of related interactions between a customer and your organization.
        The list is not paginated and will return at most 1000 items. The items are returned in ascending order by timestamp.
        The `Gladly-Limited-Data` header flag in the response will indicate if the conversation has more items than returned.

        The response can be filtered by session using the optional `sessionId` query parameter.
      operationId: getConversationItems
      parameters:
        - in: path
          name: conversationId
          schema:
            type: string
          required: true
          description: "Id of the conversation to get the timeline for"
          example: "9BcE2O0DQ2ynGHRmk9FeoA"
        - in: query
          name: sessionId
          schema:
            type: string
          required: false
          description: "Return only items whose `sessionId` matches the given value."
          example: "5k04bYuTRGqyT6uoSQfWVA"
      responses:
        200:
          description: "The items on the conversation timeline"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ConversationItems"
              examples:
                Conversation Items:
                  $ref: "#/components/examples/ConversationItems"
        404:
          description: "A conversation with the given id does not exist"
        410:
          description: "The conversation id no longer exists because the conversation was merged into another conversation"
          content:
            "application/json":
              schema:
                $ref: "../openapi.yaml#/components/schemas/ErrorsWithMeta"
              examples:
                Merged conversation:
                  $ref: "#/components/examples/ConversationMovedErr"

components:
  schemas:
    Conversations:
      title: "Conversations"
      type: array
      items:
        $ref: "#/components/schemas/Conversation"
    Conversation:
      title: "Conversation"
      type: object
      required:
        - id
        - customerId
        - createdAt
        - inboxId
        - status
      properties:
        id:
          type: string
          description: "The id of the conversation"
          example: pOVVdzweSumI4bFxjlT8LA
        customerId:
          type: string
          description: "The id of the profile that this conversation belongs to"
          example: "gHufx-U3QqOmhvFuViceTw"
        agentId:
          type: string
          description: "The id of the agent who is assigned to the conversation"
          example: "sHuXx-U3QqOmhvFusJGeBw"
        inboxId:
          type: string
          description: "The id of the inbox to which the conversation belongs to"
          example: "E1nArq1uQAees_DogHB0MA"
        customAttributes:
          type: array
          description: "Custom attributes assigned to the conversation"
          items:
              $ref: '#/components/schemas/ConversationCustomAttribute'
        topicIds:
          type: array
          description: "Ids of topics assigned to the conversation"
          items:
            type: string
        createdAt:
          type: string
          format: "RFC3339 with millis"
          description: "Time the conversation was created"
          example: "2016-04-11T14:09:23.000Z"
        closedAt:
          type: string
          format: "RFC3339 with millis"
          description: "Time the conversation was closed. Only present if conversation is closed"
          example: "2016-05-10T13:49:23.000Z"
        status:
          $ref: '#/components/schemas/ConversationStatus'

    ConversationStatus:
      title: "Conversation Status"
      type: string
      enum:
        - OPEN
        - WAITING
        - CLOSED
      description: >
        Status of the conversation:
          * `OPEN` - conversation requires further action
          * `WAITING` - no further action from an agent required. Waiting for response from the customer
          * `CLOSED` - resolved and requiring no further action. It can be changed back to OPEN if customer needs further assistance
      example: OPEN

    ConversationUpdate:
      title: "Conversation Update"
      type: object
      properties:
        assignee:
          type: object
          title: "Assignee Update"
          required:
            - inboxId
          properties:
            agentId:
              type: string
              description: "The id of the agent who is assigned to the conversation"
              example: "sHuXx-U3QqOmhvFusJGeBw"
            inboxId:
              type: string
              description: "The id of the inbox to which the conversation belongs to"
              example: "E1nArq1uQAees_DogHB0MA"
        status:
          type: object
          title: "Conversation Status"
          required:
            - value
          properties:
            value:
              type: string
              description: "Value of the status to change to"
              enum:
                - CLOSED
                - OPEN
            force:
              type: boolean
              description: "Determines whether to override the value if conversation still needs a response"
              default: false

    ConversationItems:
      title: "Conversation Items"
      type: array
      items:
        $ref: "#/components/schemas/ConversationItem"

    ConversationItem:
      title: "Conversation Item"
      type: object
      required:
        - id
        - customerId
        - content
        - timestamp
      properties:
        id:
          type: string
          description: "the id of the item"
          example: pOVVdzweSumI4bFxjlT8LA
        customerId:
          type: string
          description: "the id of the profile that this item belongs to"
          example: "gHufx-U3QqOmhvFuViceTw"
        conversationId:
          type: string
          description: "id of the conversation the item is part of if it is within one"
          example: "PmDVUfWfRjKuwb4VgA2zEA"
        sessionId:
          type: string
          description: "session ID of the conversation"
          example: "8K2mX9nRTyWv4bQzLpH5jA"
        timestamp:
          type: string
          format: "RFC3339"
          description: "Time the item occurred"
          example: "2019-07-03T04:30:12.07Z"
        initiator:
          $ref: "#/components/schemas/CommunicatorWithExample"
        responder:
          $ref: "#/components/schemas/Communicator"
        content:
          $ref: "#/components/schemas/ConversationItemContent"

    CommunicatorWithExample:
      allOf:
        - $ref: "#/components/schemas/Communicator"
        - example:
            id: "gHufx-U3QqOmhvFuViceTw"
            type: CUSTOMER
    Communicator:
      title: "Describes the communicator initiating or responding to the item"
      type: object
      properties:
        id:
          type: string
          description: "id of the communicator"
          example: "zGaHXjD4SR-moMR9LbULDa"
        type:
          type: string
          description: |
            type of communicator which can be an agent, customer, a person related to customer, rule, or application

            If an email response comes from a third-party recipient who was previously included in an email exchange with the customer (TO, CC, or BCC), the reply's initiator type will be either 'INTERNAL' or 'EXTERNAL' depending on the sender's email address domain. 'INTERNAL' types are sent from email addresses that share domain with the agent's organization. 'EXTERNAL' types are sent from other domains.

            initiator.id=SIDEKICK_V2 and initiator.type=SYSTEM are set when the responder is Gladly AI. Note that Structured Threads (legacy) responses will still have initiator.type=API and initiator.id=API user ID associated with this token.
          enum:
            - AGENT
            - API
            - AUTOMATION
            - CUSTOMER
            - INTERNAL
            - EXTERNAL
            - SYSTEM
          example: AGENT

    ConversationItemContent:
      title: "Conversation Item Content"
      oneOf:
        - $ref: "#/components/schemas/ChatMessageContent"
        - $ref: "#/components/schemas/ConversationStatusChange"
        - $ref: "#/components/schemas/CustomerActivityContent"
        - $ref: "#/components/schemas/EmailContent"
        - $ref: "#/components/schemas/FBMessageContent"
        - $ref: "#/components/schemas/ConversationNoteContent"
        - $ref: "#/components/schemas/PhoneCallContent"
        - $ref: "#/components/schemas/SMSContent"
        - $ref: "#/components/schemas/TopicChangeContent"
        - $ref: "#/components/schemas/VoiceAIMessageContent"
        - $ref: "#/components/schemas/VoicemailContent"
        - $ref: "#/components/schemas/WhatsAppContent"
        - $ref: "#/components/schemas/InstagramDirectContent"
        - $ref: "#/components/schemas/TwitterContent"

    CreatableConversationItem:
      title: "Conversation Item To Create"
      type: object
      required:
        - content
        - timestamp
      properties:
        id:
          type: string
          description: "the id of the item"
          example: pOVVdzweSumI4bFxjlT8LA
        customerId:
          type: string
          description: "the id of the profile that this item belongs to"
          example: "gHufx-U3QqOmhvFuViceTw"
        timestamp:
          type: string
          format: "RFC3339"
          description: "Time the item occurred"
          example: "2019-07-03T04:30:12.07Z"
        initiator:
          $ref: "#/components/schemas/CommunicatorWithExample"
        responder:
          $ref: "#/components/schemas/Communicator"
        content:
          $ref: "#/components/schemas/CreatableConversationItemContent"

    CreatableConversationItemContent:
      title: "Conversation Item Content To Create"
      oneOf:
        - $ref: "#/components/schemas/CustomerActivityContent"
        - $ref: "#/components/schemas/TaskContent"

    ConversationTopicAdd:
      title: "List of Conversation Topics to Add"
      required:
        - topicIDs
      type: object
      properties:
        topicIds:
          type: array
          example: ["pOVVdzweSumI4bFxjlT8LA"]
          items:
            type: string
          description: "Topic Ids to be added to the conversation."

    ConversationFreeformTopicAddOrRemove:
      title: "List of Conversation Freeform Topics to Add or Remove"
      required:
        - content
      type: object
      properties:
        body:
          type: string
          items:
            type: object
          description: "Freeform topics that need to be added or removed from a conversation"

    ConversationNoteAdd:
      title: "Content of note to add"
      required:
        - content
      type: object
      properties:
        body:
          type: string
          description: "Plain text or [rich content ](#tag/Rich-Content) of the note."
          example: "<h1>Customer has requested more information about our loyalty program.</h1>"

    ConversationNote:
      title: "Conversation Note"
      type: object
      required:
        - id
        - customerId
        - content
        - timestamp
      properties:
        id:
          type: string
          description: "the id of the item"
          example: pOVVdzweSumI4bFxjlT8LA
        customerId:
          type: string
          description: "the id of the customer profile that this item belongs to"
          example: "gHufx-U3QqOmhvFuViceTw"
        conversationId:
          type: string
          description: "id of the conversation the item is part of if it is within one"
          example: "PmDVUfWfRjKuwb4VgA2zEA"
        timestamp:
          type: string
          format: "RFC3339"
          description: "Time the item occurred"
          example: "2019-07-03T04:30:12.07Z"
        initiator:
          $ref: "#/components/schemas/CommunicatorWithExample"
        responder:
          $ref: "#/components/schemas/Communicator"
        content:
          $ref: "#/components/schemas/ConversationNoteContent"


    ConversationItemRequestContent:
      title: "Conversation Item To Create"
      required:
        - content
      type: object
      properties:
        id:
          maxLength: 50
          type: string
          description: "Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included."
          example: pOVVdzweSumI4bFxjlT8LA
        content:
          $ref: "#/components/schemas/CreatableConversationItemContent"

    ConversationItemRequestContentWithCustomer:
      title: "Conversation Item To Create with Customer"
      required:
        - content
        - customer
      type: object
      properties:
        id:
          maxLength: 50
          type: string
          description: "Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included."
          example: pOVVdzweSumI4bFxjlT8LA
        customer:
          $ref: "#/components/schemas/CustomerSpec"
        content:
          $ref: "#/components/schemas/CreatableConversationItemContent"

    ConversationCustomAttribute:
      title: "Custom Attribute"
      description: "Specifies a custom attribute"
      type: object
      properties:
        id:
          type: string
          description: "id of the custom attribute"
          example: pOVVdzweSumI4bFxjlT8LA
        value:
          type: string
          description: "value of the custom attribute"
          example: "1234567890"

    CustomerSpec:
      title: "Customer Specification"
      description: "Specifies the customer this belongs to. You must provide exactly one of the values."
      type: object
      properties:
        emailAddress:
          type: string
          example: "michelle.smith@example.org"
        mobilePhone:
          type: string
          example: "+16505551987"

    ChatMessageContent:
      title: "Chat Message"
      oneOf:
        - $ref: "#/components/schemas/ChatTextMessageContent"
        - $ref: "#/components/schemas/ChatQuickReplyRequestMessageContent"
        - $ref: "#/components/schemas/ChatQuickReplyResponseMessageContent"

    ChatTextMessageContent:
      title: "Chat Message"
      description: "A text message sent during a Gladly chat session."
      type: object
      required:
        - type
        - sessionId
        - content
        - messageType
      properties:
        type:
          type: string
          enum:
            - CHAT_MESSAGE
        messageType:
          type: string
          enum:
            - TEXT
        sessionId:
          type: string
          description: "id of the chat session the message is part of"
          example: "5k04bYuTRGqyT6uoSQfWVA"
        content:
          type: string
          description: "text of the message sent"
          example: "HI! Can you help me with my order?"
        attachments:
          type: array
          description: "attachments to the message"
          items:
            $ref: "#/components/schemas/Attachment"

    ChatQuickReplyResponseMessageContent:
      title: "Chat QuickReply response"
      description: "A response to a QuickReply request"
      type: object
      required:
        - type
        - sessionId
        - content
        - messageType
        - messageData
      properties:
        type:
          type: string
          enum:
            - CHAT_MESSAGE
        messageType:
          type: string
          enum:
            - QUICK_REPLY_RESPONSE
        sessionId:
          type: string
          description: "id of the chat session the message is part of"
          example: "5k04bYuTRGqyT6uoSQfWVA"
        content:
          type: string
          description: "The label of the selected option"
          example: "Furniture"
        attachments:
          type: array
          description: "attachments to the message"
          items:
            $ref: "#/components/schemas/Attachment"
        messageData:
          type: object
          title: QuickReplyResponse data
          description: Data that describes the users option selection
          properties:
            quickReplyRequest:
              type: object
              title: QuickReply Request
              description: The QuickReply request that this is a response to, for additional context.
              properties:
                options:
                  $ref: "#/components/schemas/QuickReplyOptions"
            selectedOptionId:
              type: string
              title: Selected option id
              description: The Id of the option the user selected
            requestMessageId:
              type: string
              title: message Id
              description: The id of the QuickReply request message that this is a response to

    ChatQuickReplyRequestMessageContent:
      title: "Chat QuickReply Request"
      description: "A QuickReply request sent to a user during a Gladly chat session."
      type: object
      required:
        - type
        - sessionId
        - content
        - messageType
        - messageData
      properties:
        type:
          type: string
          enum:
            - CHAT_MESSAGE
        messageType:
          type: string
          enum:
            - QUICK_REPLY_REQUEST
        sessionId:
          type: string
          description: "id of the chat session the message is part of"
          example: "5k04bYuTRGqyT6uoSQfWVA"
        content:
          type: string
          description: "text of the message sent"
          example: "What can I help with?"
        attachments:
          type: array
          description: "attachments to the message"
          items:
            $ref: "#/components/schemas/Attachment"
        messageData:
          type: object
          title: QuickReply request data
          description: Data that describes the QuickReply request options presented to the user
          properties:
            options:
              $ref: "#/components/schemas/QuickReplyOptions"

    ConversationStatusChange:
      title: "Conversation Status Change"
      description: "Record of a change in the status of a conversation"
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - CONVERSATION_STATUS_CHANGE
        status:
          type: string
          description: "Status of the conversation, where “OPEN” means conversation is assigned to an agent and “CLOSED” means the problem reported by the customer has been solved and the conversation requires no further action. Note that a conversation can be reopened, setting the status back to “OPEN”, if a customer responds to a closed conversation within a configurable time window."
          enum:
            - OPEN
            - CLOSED

    CustomerActivityContent:
      title: "Customer Activity"
      description: "An event such as consumer interaction outside Gladly that agents will see in the customer timeline."
      required:
        - activityType
        - type
      type: object
      properties:
        type:
          type: string
          example: CUSTOMER_ACTIVITY
          enum:
            - CUSTOMER_ACTIVITY
        title:
          maxLength: 100
          type: string
          description: "First line of highlighted text for the item in the customer timeline"
          example: "Welcome to Gladly!"
        body:
          maxLength: 25000
          type: string
          description: "Plain text or rich content ([see here for supported markup](#tag/Rich-Content)) of the activity that will appear as the main content."
          example: "At Gladly we set out to reinvent customer service. Why? Because 21st century consumers are different. They are from 18 to 80 years old, expect the brands they love to recognize them, and to be able to communicate with your agents over all channels – all the time."
        activityType:
          type: string
          description: "Type of this activity. This will determine the icon displayed in the customer timeline."
          example: EMAIL
          enum:
            - EMAIL
            - ISSUE
            - SMS
            - SURVEY
        sourceName:
          maxLength: 50
          type: string
          description: "Name of the source system generating this activity"
          example: HubSpot
        link:
          $ref: "#/components/schemas/Link"
        expandByDefault:
          type: boolean
          description: "Whether the activity should be expanded by default in the customer timeline"
          example: true
          default: false
        occurredAt:
          type: string
          description: "Time when this activity occurred. Will determine where in the customer timeline this item appears. Limited to events no older than 1 year. Note if this value is not set, it will be ommitted from the GET Item API call, and ordering on the timeline will default to the `receivedAt` time (i.e.: `current_time`)."
          format: "RFC3339 with millis"
          example: "2016-04-11T14:09:23.000Z"
        receivedAt:
          type: string
          description: "The time when this item was first sent to Gladly"
          format: "RFC3339 with millis"
          readOnly: true
          example: "2019-01-11T20:49:55.000Z"

    EmailContent:
      title: "Email"
      description: ""
      type: object
      required:
        - type
        - from
        - to
        - subject
        - content
      properties:
        type:
          type: string
          enum:
            - EMAIL
        from:
          type: string
          description: "email address the message was from"
          example: "martha.williams@gmail.com"
        to:
          type: array
          description: "email addresses the message was sent to"
          example: ["martha.williams@gmail.com"]
          items:
            type: string
        cc:
          type: array
          description: "email addresses the message was carbon copied to"
          example: ["billing@company.com"]
          items:
            type: string
        bcc:
          type: array
          description: "email addresses the message was blind carbon copied to"
          example: ["supervisor@company.com"]
          items:
            type: string
        subject:
          type: string
          description: "subject text of the email"
          example: "My order"
        content:
          type: string
          description: "plain text body of the email"
          example: "Part of my order was damaged. May I get a refund for those items?"
        attachments:
          type: array
          description: "attachments to the email"
          items:
            $ref: "#/components/schemas/Attachment"

    FBMessageContent:
      title: "Facebook Messenger Message"
      description: ""
      type: object
      required:
        - type
        - pageId
        - userId
        - content
      properties:
        type:
          type: string
          enum:
            - FACEBOOK_MESSAGE
        pageId:
          type: string
          description: "Facebook page id"
        userId:
          type: string
          description: "Facebook user id for the communication"
        content:
          type: string
          description: "text of the message"
          example: "I love your brand! Do you have a loyalty program?"
        attachments:
          type: array
          description: "attachments to the message"
          items:
            $ref: "#/components/schemas/Attachment"

    WhatsAppContent:
      title: "WhatsApp Message"
      description: ""
      type: object
      required:
        - type
        - content
      properties:
        type:
          type: string
          enum:
            - WHATSAPP
        content:
          type: string
          description: "text of the message"
          example: "I love your brand! Do you have a loyalty program?"
        attachments:
          type: array
          description: "attachments to the message"
          items:
            $ref: "#/components/schemas/Attachment"

    InstagramDirectContent:
      title: "Instagram Message"
      description: ""
      type: object
      required:
        - type
        - content
      properties:
        type:
          type: string
          enum:
            - INSTAGRAM_DIRECT
        content:
          type: string
          description: "text of the message"
          example: "I love your brand! Do you have a loyalty program?"
        attachments:
          type: array
          description: "attachments to the message"
          items:
            $ref: "#/components/schemas/Attachment"

    TwitterContent:
      title: "Twitter Message (decommissioned as of 04/20/23 but can still be retrieved)"
      description: ""
      type: object
      required:
        - type
        - content
      properties:
        type:
          type: string
          enum:
            - TWITTER
        content:
          type: string
          description: "text of the message"
          example: "I love your brand! Do you have a loyalty program?"

    ConversationNoteContent:
      title: "Note"
      description: ""
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - CONVERSATION_NOTE
        body:
          type: string
          description: "text of the note"
          example: "Customer has requested more information about our loyalty program."
        attachments:
          type: array
          description: "attachments to the message"
          items:
            $ref: "#/components/schemas/Attachment"

    PhoneCallContent:
      title: "Phone Call"
      description: "Record of a phone call between a customer and an agent"
      type: object
      required:
        - type
        - from
        - to
        - startedAt
      properties:
        type:
          type: string
          enum:
            - PHONE_CALL
        from:
          type: string
          format: "E.164"
          description: "phone number of the caller"
          example: "+14153335555"
        to:
          type: string
          format: "E.164"
          description: "phone number call was to"
          example: "+12149897676"
        startedAt:
          type: string
          format: "RFC3339"
          description: "time the phone call started"
          example: "2019-07-02T08:05:00.10Z"
        answeredAt:
          type: string
          format: "RFC3339"
          description: "time the phone call was answered"
          example: "2019-07-02T08:05:09.41Z"
        completedAt:
          type: string
          format: "RFC3339"
          description: "time the phone call ended"
          example: "2019-07-02T08:11:15.03Z"
        recordingStatus:
          type: string
          description: "Status of the phone call recording.<br>
                        AVAILABLE : Recording is available for download<br>
                        DELETED   : Recording was deleted by the user<br>
                        ERROR     : An error occurred while recording. Please contact Gladly Support Team"
          enum:
            - AVAILABLE
            - DELETED
            - ERROR
        recordingUrl:
          type: string
          description: "URL to retrieve media for the phone call recording in single-channel 32-kbps MP3 format. Present if recording is “AVAILABLE”"
        recordingDuration:
          type: integer
          description: "Duration of the phone call recording in seconds. Present if recording is “AVAILABLE”"
          example: 44
        recordingSummary:
          $ref: "#/components/schemas/RecordingSummary"

    RecordingSummary:
      title: "Recording Summary"
      description: "Summary of the voice recording"
      type: object
      properties:
        status:
          type: string
          description: "Status of the voice recoding summary.<br>
                        FAILED   : An error occurred while trying to summarize a voice recording<br>
                        READY    : Recording summary is available<br>
                        PENDING  : Trying to summarize a voice recording<br>
                        REDACTED : An associated recording has been deleted"
          enum:
            - FAILED
            - READY
            - PENDING
            - REDACTED
          example: READY

        summary:
          type: string
          description: "Voice recording summary text"
          example: "The customer calls to exchange an item. The representative asks for the customer's details and explains 
          that the return process is different for each situation. The customer decides to reorder the correct size and 
          thanks the representative for their help."
        language:
          type: string
          description: "Language"
          example: "en"

    VoiceTranscript:
      title: "Voice Transcript"
      description: "Transcript of a voice recording"
      type: object
      properties:
        paragraphs:
          type: array
          description: "Paragraphs"
          items:
            $ref: "#/components/schemas/VoiceTranscriptParagraph"
        customerId:
          type: string
          description: "Customer associated with the voice transcript"
          example: "AloLvEkzQlqc7c4kyYQY1A"
        numberOfSpeakers:
          type: integer
          description: "Number of speakers"
          example: 1
        language:
          type: string
          description: "Language"
        createdAt:
          type: string
          format: "RFC3339 with millis"
          description: "Time the voice transcript was created"
          example: "2024-05-15T14:09:23.000Z"
        updatedAt:
          type: string
          format: "RFC3339 with millis"
          description: "Time the voice transcript was updated"
          example: "2024-05-15T14:19:23.000Z"

    VoiceTranscriptParagraph:
      description: "Paragraph"
      type: object
      properties:
        transcript:
          type: string
          description: "Transcript text"
          example: "Hello! How are you doing today?"
        speaker:
          type: integer
          description: "Speaker number"
          example: 0
        startTime:
          type: number
          description: "Start time of the paragraph (in seconds from the beginning of the recording)"
          example: 2.48
        endTime:
          type: number
          description: "End time of the paragraph (in seconds from the beginning of the recording)"
          example: 6.1

    VoiceAIMessageContent:
      title: "Voice AI Message"
      description: "A spoken message exchanged between a customer and Gladly's voice AI during a voice AI session. The item's `sessionId` identifies the voice AI session."
      type: object
      required:
        - type
        - companyNumber
        - body
      properties:
        type:
          type: string
          enum:
            - VOICE_AI_MESSAGE
        customerNumber:
          type: string
          format: "E.164"
          description: "Phone number of the customer participating in the voice AI session"
          example: "+14153335555"
        companyNumber:
          type: string
          format: "E.164"
          description: "Phone number the customer dialed to reach the voice AI session"
          example: "+12149897676"
        body:
          type: string
          description: "Text of the spoken message"
          example: "Thanks for calling. How can I help you today?"
        status:
          type: string
          description: |
            Delivery status of a voice AI message spoken to the customer:
              * `PLAYED` - the message was played to the customer in full
              * `INTERRUPTED` - the customer interrupted the message before it finished playing
          enum:
            - PLAYED
            - INTERRUPTED
          example: PLAYED

    SMSContent:
      title: "SMS Message"
      description: "A message sent via SMS"
      type: object
      required:
        - type
        - from
        - to
        - content
      properties:
        type:
          type: string
          enum:
            - SMS
        from:
          type: string
          format: "E.164"
          description: "phone number of SMS sender"
          example: "+14153335555"
        to:
          type: string
          format: "E.164"
          description: "phone number of SMS receiver"
          example: "+12149897676"
        content:
          type: string
          description: "text of the SMS message"
          example: "I haven't received my order yet. Can you check on the status?"
        attachments:
          type: array
          description: "attachments to the message"
          items:
            $ref: "#/components/schemas/Attachment"

    TaskContent:
      title: "Task (deprecated)"
      required:
        - body
        - dueAt
        - type
        - assignee
      type: object
      properties:
        type:
          type: string
          example: TASK
          enum:
            - TASK
        assignee:
          $ref: "#/components/schemas/Assignee"
        body:
          maxLength: 10000
          type: string
          description: "Text to describe what task to complete. Constrained HTML [Rich Content](#tag/Rich-Content) is supported."
          example: "Call customer back with information about booking"
        dueAt:
          description: "Time when the task will be due. This must be set to a time in the future."
          type: string
          format: "RFC3339"
          example: "2020-03-15T06:13:00.125Z"
        attachments:
          type: array
          description: "attachments to the task"
          items:
            $ref: "#/components/schemas/Attachment"
    Assignee:
      title: "Assignee"
      description: "Inbox and Agent assignee for a Task"
      required:
        - inboxId
      properties:
        inboxId:
          type: string
          description: "Id of the inbox the task should be assigned to. You can look up the id in the Gladly UI."
          example: "NFpDZtfqhk2pI6fjaVDlFf"
        agentId:
          type: string
          description: "Id of the agent the task should be assigned to. You can look up the id in the Gladly UI."
          example: "zGaHXjD4SR-moMR9LbULDa"
    
    Attachment:
      type: object
      properties:
        id:
          type: string
          description: "ID of the attachment"
          example: "pOVVdzweSumI4bFxjlT8LA"
        contentType:
          type: string
          description: "Content type of the attachment"
          example: "image/png"
        filename:
          type: string
          description: "Filename of the attachment"
          example: "attachment-1.png"
        fileSize:
          type: integer
          description: "File size of the attachment in bytes"
          example: 1024
    
    Link:
      type: object
      properties:
        url:
          type: string
          description: "URL for a clickable link that this item should go to"
          example: "https://www.gladly.com/product/"
        text:
          maxLength: 50
          type: string
          description: "Text label for the link"
          example: "View Details"
      description: "Clickable reference to appear at the bottom portion of the customer activity card in the customer timeline "

    Message:
      title: "Message"
      description: "Message that can be sent in Gladly"
      type: object
      required:
        - content
      properties:
        content:
          $ref: "#/components/schemas/MessageContent"

    MessageContent:
      title: "Message content"
      oneOf:
        - $ref: '#/components/schemas/EmailReplyMessageContent'
        - $ref: '#/components/schemas/ChatReplyMessageContent'
        - $ref: '#/components/schemas/FacebookReplyMessageContent'
        - $ref: '#/components/schemas/InstagramDirectReplyMessageContent'
        - $ref: '#/components/schemas/SMSReplyMessageContent'
        - $ref: '#/components/schemas/TwitterReplyMessageContent'
        - $ref: '#/components/schemas/WhatsAppReplyMessageContent'

    EmailReplyMessageContent:
      title: "Email Message Content"
      description: "The content of the email message"
      type: object
      required:
        - type
        - body
      properties:
        type:
          type: string
          enum:
            - EMAIL
        body:
          type: string
          description: HTML message that can be added to an email
          example: "<h1>Customer service is being reinvented by Gladly</h1>"
        bodyPlain:
          type: string
          description: Plain text message that can be added to an email
          example: "Customer service is being reinvented by Gladly"

    ChatReplyMessageContent:
      title: "Chat Message Content"
      oneOf:
        - $ref: "#/components/schemas/ChatTextReplyMessageContent"
        - $ref: "#/components/schemas/ChatQuickReplyRequestReplyMessageContent"

    ChatTextReplyMessageContent:
      title: "Message Content"
      description: "The content of the chat message"
      type: object
      required:
        - type
        - body
      properties:
        type:
          type: string
          enum:
            - CHAT_MESSAGE
        messageType:
          type: string
          enum:
            - TEXT
        body:
          type: string
          description: Plain text message
          example: "Customer service is being reinvented by Gladly"

    ChatQuickReplyRequestReplyMessageContent:
      title: "QuickReply Request Content"
      description: "The content of chat QuickReply request"
      type: object
      required:
        - type
        - body
        - messageType
        - messageData
      properties:
        type:
          type: string
          enum:
            - CHAT_MESSAGE
        messageType:
          type: string
          enum:
            - QUICK_REPLY_REQUEST
        body:
          type: string
          description: Plain text message
          example: "What can I help you with?"
        messageData:
          type: object
          description: QuickReply request data
          required:
            - options
          properties:
            options:
              $ref: "#/components/schemas/QuickReplyOptions"

    InstagramDirectReplyMessageContent:
      title: 'Instagram Direct Message Content'
      description: 'The content of the Instagram Direct message'
      type: object
      required:
        - type
        - body
      properties:
        type:
          type: string
          enum:
            - INSTAGRAM_DIRECT
        body:
          type: string
          description: Plain text message
          example: 'Customer service is being reinvented by Gladly'

    QuickReplyOptions:
      type: array
      title: Options
      description: The options the user can choose from, the number of options must be greater or equal to one and less or equal to 10.
      items:
        type: object
        title: Option
        required:
          - id
          - label
        properties:
          id:
            type: string
            title: Id
            description: Id of this option, must be unique in the request and only contain alphanumeric characters (a-z, A-Z, 0-9), hyphen or underscore
          label:
            type: string
            title: Label
            description: Text label of the option that will be presented to the user (max length 50 characters)

    FacebookReplyMessageContent:
      title: "Facebook Message Content"
      description: "The content of the facebook message"
      type: object
      required:
        - type
        - body
      properties:
        type:
          type: string
          enum:
            - FACEBOOK_MESSAGE
        body:
          type: string
          description: Plain text message
          example: "Customer service is being reinvented by Gladly"

    SMSReplyMessageContent:
      title: "SMS Message Content"
      description: "The content of the sms message"
      type: object
      required:
        - type
        - body
      properties:
        type:
          type: string
          enum:
            - SMS
        body:
          type: string
          description: Plain text message
          example: "Customer service is being reinvented by Gladly"

    TwitterReplyMessageContent:
      title: 'Twitter Direct Message Content (decommissioned as of 04/20/2023)'
      description: 'The content of the twitter direct message'
      type: object
      required:
        - type
        - body
      properties:
        type:
          type: string
          enum:
            - TWITTER
        body:
          type: string
          description: Plain text message
          example: 'Customer service is being reinvented by Gladly'

    WhatsAppReplyMessageContent:
      title: 'WhatsApp Message Content'
      description: 'The content of the WhatsApp message'
      type: object
      required:
        - type
        - body
      properties:
        type:
          type: string
          enum:
            - WHATSAPP
        body:
          type: string
          description: Plain text message
          example: 'Customer service is being reinvented by Gladly'

    TopicChangeContent:
      title: "Topic Change"
      description: "Record of an agent applying or removing a topic from the conversation"
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - TOPIC_CHANGE
        addedTopicIds:
          type: array
          description: "ids of topics added to the conversation"
          items:
            type: string
            example: "uu4t00vITaKQ3bVjU2UrGQ"
        removedTopicIds:
          type: array
          description: "ids of topics removed from the conversation"
          items:
            type: string
            example: "uu4t00vITaKQ3bVjU2UrGQ"

    VoicemailContent:
      title: "Voicemail"
      description: "Record of a voicemail left by customer in Gladly"
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - VOICEMAIL
        startedAt:
          description: "Start time of the voicemail"
          type: string
          format: "RFC3339"
          example: "2020-03-15T06:13:00.125Z"
        recordingStatus:
          type: string
          description: "Status of the voicemail recording<br>
                        AVAILABLE : Recording is available for download<br>
                        DELETED   : Recording was deleted by the user<br>
                        ERROR     : An error occurred while recording. Please contact Gladly Support Team"
          enum:
            - AVAILABLE
            - DELETED
            - ERROR
        recordingUrl:
          type: string
          description: "URL to retrieve media for the voicemail in single-channel 32-kbps MP3 format. Present if recording status is “AVAILABLE”"
        recordingDuration:
          type: integer
          description: "Duration of the voicemail in seconds. Present if recording status is “AVAILABLE”"
          example: 44
        recordingSummary:
            $ref: "#/components/schemas/RecordingSummary"


  examples:
    CustomerActivity:
      summary: "Example of a Customer Activity"
      value:
        content:
          type: "CUSTOMER_ACTIVITY"
          title: "Welcome to Gladly!"
          body: "At Gladly we set out to reinvent customer service. Why? Because 21st century consumers are different. They are from 18 to 80 years old, expect the brands they love to recognize them, and to be able to communicate with your agents over all channels – all the time."
          activityType: "EMAIL"
          sourceName: "HubSpot"
          link:
            url: "https://www.gladly.com/product/"
            text: "View Details"

    CustomerActivityWithCustomer:
      summary: "Example of a Customer Activity"
      value:
        id: "pOVVdzweSumI4bFxjlT8LA"
        customer:
          emailAddress: "michelle.smith@example.org"
        content:
          type: "CUSTOMER_ACTIVITY"
          title: "Welcome to Gladly!"
          body: "At Gladly we set out to reinvent customer service. Why? Because 21st century consumers are different. They are from 18 to 80 years old, expect the brands they love to recognize them, and to be able to communicate with your agents over all channels – all the time."
          activityType: "EMAIL"
          sourceName: "HubSpot"
          link:
            url: "https://www.gladly.com/product/"
            text: "View Details"

    ConversationTopic:
      summary: "Example of a Conversation Topic"
      value:
        topicIds: ["pOVVdzweSumI4bFxjlT8LA", "pOVVdzweSumI4bFxjlT8LB"]

    ConversationFreeformTopicAddOrRemove:
      summary: "Example of a Conversation Freeform Topic Add or Remove"
      value:
        add:
          - { "key": "ORDER_ID", "value": "ORD_3" }
          - { "key": "ORDER_ID", "value": "ORD_4" }
        remove:
          - { "key": "ORDER_ID", "value": "ORD_1" }
          - { "key": "ORDER_ID", "value": "ORD_2" }

    ConversationNote:
      summary: "Example of a Conversation Note"
      value:
        content:
          body: "Customer has requested more information about our loyalty program."

    Conversations:
      summary: "Example of conversations response"
      value:
        - id: "HXRqKC5GSV-jAlq0-sxYTA"
          topicIds: ["_DZTz4I0Qsq9YXxeXwufMg", "tYVmwhIVQe-2tflRIszQ3g"]
          customAttributes:
            - { "id": "UCeBpdBVSNyaP54jhd8CZw", "value": "1234556777" }
            - { "id": "UCeBpdBVSNyaP54jhd8CZw", "value": "883399334403" }
            - { "id": "cEBkE90eQHObfcsnrm60Tg", "value": "UPS" }
          customerId: "o2sg-TMTSD2rTwMuxzewbA"
          createdAt: "2016-01-02T00:10:00Z"
          agentId: "sHuXx-U3QqOmhvFusJGeBw"
          inboxId: "E1nArq1uQAees_DogHB0MA"
          status: "OPEN"
        - id: "UMTZxwzJRyejwOj4NDfjeg"
          topicIds: ["tYVmwhIVQe-2tflRIszQ3g"]
          customAttributes:
            - { "id": "UCeBpdBVSNyaP54jhd8CZw", "value": "1234556777" }
            - { "id": "UCeBpdBVSNyaP54jhd8CZw", "value": "883399334403" }
            - { "id": "cEBkE90eQHObfcsnrm60Tg", "value": "UPS" }
          customerId: "o2sg-TMTSD2rTwMuxzewbA"
          createdAt: "2016-01-02T00:10:00Z"
          closedAt: "2016-01-03T08:10:00Z"
          agentId: "sHuXx-U3QqOmhvFusJGeBw"
          inboxId: "E1nArq1uQAees_DogHB0MA"
          status: "CLOSED"

    Conversation:
      summary: "Example of a conversation response"
      value:
        id: "HXRqKC5GSV-jAlq0-sxYTA"
        topicIds: ["_DZTz4I0Qsq9YXxeXwufMg", "tYVmwhIVQe-2tflRIszQ3g"]
        customAttributes:
          - { "id": "UCeBpdBVSNyaP54jhd8CZw", "value": "1234556777" }
          - { "id": "UCeBpdBVSNyaP54jhd8CZw", "value": "883399334403" }
          - { "id": "cEBkE90eQHObfcsnrm60Tg", "value": "UPS" }
        customerId: "o2sg-TMTSD2rTwMuxzewbA"
        createdAt: "2016-01-02T00:10:00Z"
        closedAt: "2016-01-03T08:10:00Z"
        agentId: "sHuXx-U3QqOmhvFusJGeBw"
        inboxId: "E1nArq1uQAees_DogHB0MA"
        status: "CLOSED"

    ConversationItems:
      summary: "Example of conversation items response"
      value:
        - id: "ybP4szYCSy6LdV4DNwEd6g"
          conversationId: "9BcE2O0DQ2ynGHRmk9FeoA"
          customerId: "OOrlNMXeS72gs_WEX2TtMg"
          timestamp: "2019-07-01T11:46:45.01Z"
          initiator:
            id: "OOrlNMXeS72gs_WEX2TtMg"
            type: CUSTOMER
          content:
            type: CHAT_MESSAGE
            sessionId: "5k04bYuTRGqyT6uoSQfWVA"
            content: "Hi! I know it's after hours but can someone help upgrade my account?"
        - id: "Rk7dLm2xTXqNwZp8vB3YeA"
          conversationId: "9BcE2O0DQ2ynGHRmk9FeoA"
          customerId: "OOrlNMXeS72gs_WEX2TtMg"
          timestamp: "2019-07-01T11:46:50.01Z"
          initiator:
            id: "SIDEKICK_V2"
            type: SYSTEM
          content:
            type: CHAT_MESSAGE
            sessionId: "5k04bYuTRGqyT6uoSQfWVA"
            content: "Hello! I can help you with upgrading your account. What plan are you interested in?"
        - id: "9lQDrx-HTz-JMoP2T4CtZA"
          conversationId: "9BcE2O0DQ2ynGHRmk9FeoA"
          customerId: "OOrlNMXeS72gs_WEX2TtMg"
          timestamp: "2019-07-02T06:30:12.07Z"
          initiator:
            id: "WmeA3Y51Q5ayCAaZ1AotIA"
            type: AGENT
          content:
            type: EMAIL
            from: "amy.agent@company.com"
            to: ["martha.williams@gmail.com"]
            subject: "Account upgrade"
            content: "I would be happy to help you! We need a few details, so please give us a call this morning."
        - id: "S6pMkJ78QMmkVf9qPP_SeQ"
          conversationId: "9BcE2O0DQ2ynGHRmk9FeoA"
          customerId: "OOrlNMXeS72gs_WEX2TtMg"
          timestamp: "2019-07-02T08:05:00.10Z"
          initiator:
            id: "OOrlNMXeS72gs_WEX2TtMg"
            type: CUSTOMER
          responder:
            id: "WmeA3Y51Q5ayCAaZ1AotIA"
            type: AGENT
          content:
            type: PHONE_CALL
            from: "+14153335555"
            to: "+12149897676"
            startedAt: "2019-07-02T08:05:00.10Z"
            answeredAt: "2019-07-02T08:05:09.41Z"
            completedAt: "2019-07-02T08:11:15.03Z"
            recordingStatus: "AVAILABLE"
            recordingUrl: "/api/v1/conversation-items/S6pMkJ78QMmkVf9qPP_SeQ/media/recording"
            recordingDuration: "100"
        - id: "K0UGL3n6S4uPpvtMvItqHA"
          conversationId: "9BcE2O0DQ2ynGHRmk9FeoA"
          customerId: "OOrlNMXeS72gs_WEX2TtMg"
          timestamp: "2019-07-02T08:12:55.870Z"
          initiator:
            id: "WmeA3Y51Q5ayCAaZ1AotIA"
            type: AGENT
          content:
            type: TOPIC_CHANGE
            addedTopicIds: ["uu4t00vITaKQ3bVjU2UrGQ"]
        - id: "zwo9AtljSfaGjWb4Aq-aDQ"
          conversationId: "WmeA3Y51Q5ayCAaZ1AotIA"
          customerId: "o2sg-TMTSD2rTwMuxzewbA"
          timestamp: "2019-07-02T08:12:55.870Z"
          initiator:
            id": "zGaHXjD4SR-moMR9LbULDA"
            type": AGENT
          content:
            type: "CONVERSATION_STATUS_CHANGE"
            status:  CLOSED
        - id: "azwo9AtljSfaGjWb4Aq-aDQ"
          conversationId: "WmeA3Y51Q5ayCAaZ1AotIA"
          customerId: "o2sg-TMTSD2rTwMuxzewbA"
          timestamp: "2019-07-02T08:12:55.870Z"
          initiator:
            id": "zGaHXjD4SR-moMR9LbULDA"
            type": AGENT
          content:
            type: "VOICEMAIL"
            startedAt: "2019-07-04T08:12:55.870Z"
            recordingUrl: "/api/v1/conversation-items/azwo9AtljSfaGjWb4Aq-aDQ/media/recording"
            recordingStatus: "AVAILABLE"
            recordingDuration: 200
        - id: "VnL3kQ8zSPmW9rXpA2fYbA"
          conversationId: "9BcE2O0DQ2ynGHRmk9FeoA"
          customerId: "OOrlNMXeS72gs_WEX2TtMg"
          sessionId: "8K2mX9nRTyWv4bQzLpH5jA"
          timestamp: "2019-07-02T08:13:02.450Z"
          initiator:
            id: "SIDEKICK_V2"
            type: SYSTEM
          content:
            type: "VOICE_AI_MESSAGE"
            customerNumber: "+14153335555"
            companyNumber: "+12149897676"
            body: "Thanks for calling. How can I help you today?"
            status: "PLAYED"
        - id: "DnaU23pZSIqOixATlII1vA"
          conversationId: "HXRqKC5GSV-jAlq0-sxYTA"
          customerId: "o2sg-TMTSD2rTwMuxzewbA"
          timestamp: "2019-07-04T23:42:57.780Z"
          initiator:
            type: "AGENT"
            id: "zGaHXjD4SR-moMR9LbULDA"
          content:
            type: "CONVERSATION_NOTE"
            body: "Customer has requested more information about our loyalty program."

    EmailReplyMessage:
      summary: "Example of an email reply message"
      value:
        content:
          type: EMAIL
          body: "<h>Hi!</h><br>Of course we can help with your issue!"
          bodyPlain: "Hi!\n We can definitely help you with that!"

    ChatMessageReplyMessage:
      summary: "Example of a chat message reply message"
      value:
        content:
          type: CHAT_MESSAGE
          messageType: TEXT
          body: "Hi from chat!"

    ChatQuickReplyReplyMessage:
      summary: "Example of a chat quick reply message"
      value:
        content:
          type: CHAT_MESSAGE
          messageType: QUICK_REPLY_REQUEST
          body: "Hi from chat! Please select an option!"
          messageData:
            options:
              [{
                id: option-1,
                label: option one
              },
              {
                id: option-2,
                label: option two
              }]

    FacebookReplyMessage:
      summary: "Example of a Facebook reply message"
      value:
        content:
          type: FACEBOOK_MESSAGE
          body: "Hi from Facebook Messenger!"

    InstagramDirectReplyMessage:
      summary: "Example of an Instagram Direct reply message"
      value:
        content:
          type: INSTAGRAM_DIRECT
          body: "Hi from Instagram Direct!"

    SmsReplyMessage:
      summary: "Example of an SMS reply message"
      value:
        content:
          type: SMS
          body: "Hi from SMS!"

    TwitterReplyMessage:
      summary: "Example of a Twitter reply message"
      value:
        content:
          type: TWITTER
          body: "Hi from Twitter Direct Messages!"

    WhatsAppReplyMessage:
      summary: "Example of a WhatsApp reply message"
      value:
        content:
          type: WHATSAPP
          body: "Hi from WhatsApp!"

    ReplyClosedConversationErr:
      summary: "Error trying to act on closed conversation"
      value:
        errors: [{ "code": "invalid", "detail": "you cannot reply to items in closed conversations" }]


    ReplyEmptyTypeErr:
      summary: "Error trying to send a message with an empty type"
      value:
        errors: [{ "code": "blank","attr": "content.type" }]

    ReplyWrongTypeErr:
      summary: "Error trying to send a reply message to unsupported type"
      value:
        errors: [{ "code": "invalid", "detail": "type [VOICEMAIL] is not supported" }]


    ReplyTooLongErr:
      summary: "Error trying to send a message with too long content"
      value:
        errors: [{ "code": "too_long", "attr": "content.body", "detail": "content.body cannot be larger than 2048 characters" }]


    NotACustomerErr:
      summary: "Error trying to send reply to a message that was not from the customer"
      value:
        errors: [{ "code": "invalid", "detail": "you can only reply to customer messages" }]


    ConversationMovedErr:
      summary: "Error acting on a conversation id that was merged into another conversation"
      value:
        errors:
          - attr: "conversationId"
            code: "moved"
            detail: "conversation id has changed"
            meta:
              old: "9BcE2O0DQ2ynGHRmk9FeoA"
              new: "rVamfZHvQuORFnsk-3mNuw"