> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Open a conversation

> **This call sends an e-mail to your customer, and it cannot be taken back.** It opens a new conversation on one of your e-mail inboxes and sends `content` as its first message, with `subject` as the mail subject. Use it for one contact per call; to write to many contacts at once, use [Create a campaign](/api-reference/cloudchat/endpoints/create-a-campaign).

**The inbox.** It has to be an e-mail inbox your token reaches: every inbox of the account for an administrator, only the inboxes the agent is a member of otherwise. Any other `inbox_id` is a 422 `inbox_not_assigned`, whether or not the inbox exists. [List inboxes](/api-reference/cloudchat/endpoints/list-inboxes) shows each inbox's `channel_type`, which has to be `Channel::Email`, and `lock_to_single_conversation`. The message leaves through the inbox's own mail account, so the sender, signature and domain are the ones already configured there.

Only e-mail works today: an inbox of any other channel is a 422 `unsupported_channel`. An inbox with single-conversation mode on is a 422 `inbox_locked_to_single_conversation`, because the message would join the contact's earlier thread and your subject would be dropped.

**The recipient.** Send exactly one of `email` or `contact_id`. With `email`, the contact is created when your account has none with that address; `name` only matters then. With `contact_id`, the contact has to be in your account and have an e-mail address, and the message goes to it. [List contacts](/api-reference/cloudchat/endpoints/list-contacts) and [Get a contact](/api-reference/cloudchat/endpoints/get-a-contact) read contacts, and are for administrators; any member can send `email`.

**Retries.** Send an `idempotency_key` on every call: one value per message you mean to send, such as an order id plus the purpose. If a call times out or you lose the answer, repeat it with the same key and exactly the same content. You get the original conversation back with `dispatch_status` `duplicate` and the same `message_id`, and nothing is sent again. Without a key, a repeat opens a second conversation and sends a second e-mail. The same key with a different body, recipients, attachments or contact is a 409 and nothing is sent; use a new key for a new message. A key is remembered for a limited time and counts per inbox, so it protects retries, not a message you send again days later.

**What a 201 means.** The conversation and its first message exist and the e-mail is queued. Delivery happens afterwards: a later bounce does not come back through this call. An address that already hard bounced, was reported as spam, or bounced on this inbox is refused up front with 422 `recipient_suppressed`, and nothing is created. A 201 is also the answer to a `duplicate`.

**Rate limit.** Don't hardcode it. Two ceilings apply: the gateway limits each credential, and Cloud Chat limits e-mail dispatch per account, shared by every credential of the account. `Retry-After` and the `ratelimit-*` headers carry the current values.



## OpenAPI

````yaml api-reference/specs/cloudchat/v1.json POST /v1/accounts/{accountId}/conversations
openapi: 3.0.1
info:
  title: Cloud Chat API
  version: v1
  description: >-
    The curated public surface of Cloud Chat. Every call needs two things: the
    Bearer token from `POST /auth/v1/signin`, and the `cloudchat-instance`
    header that says which Cloud Chat instance your company lives on.


    If you don't know your instance value, the [Find your
    credentials](/api-reference/cloudchat/credentials) page reads it out of your
    own token in the browser.
servers:
  - url: https://api.cloudhumans.com/cloudchat
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Canned Responses
    description: >-
      Canned responses — the shortcuts agents expand while replying. Each one
      belongs to a single account and is identified by its short code.
  - name: Conversations
    description: >-
      The conversations of an account: read them, change their priority and
      status, assign them, leave internal notes, and block or unblock the
      contact of a conversation. Answering the customer, opening a conversation
      and deleting one are not part of this surface. What you can see and change
      follows the same rule as the dashboard: an administrator token reaches
      every inbox, an agent token only the inboxes it is a member of.
  - name: Contacts
    description: >-
      Customer contacts of the account, with their personal data. Administrators
      only.
  - name: Help Center
    description: >-
      Portals, categories and articles of the help center — the public FAQ your
      customers read.
  - name: Uploads
    description: Store the images help center articles embed.
  - name: Labels
    description: >-
      The label definitions of an account: the tags conversations and contacts
      carry. Listing and reading are open to any member; creating and updating a
      label need an administrator or CX engineer token. Renaming a label retags
      the records that carry it. There is no delete: removing a label and
      creating another with the same title would bring the old tags back. The
      same group applies labels to a conversation or a contact and takes them
      off again.
  - name: Inboxes
    description: >-
      The inboxes a token can see — every inbox of the account for an
      administrator, only its memberships for an agent. Administrators can also
      change an inbox's name, greeting, working hours and CSAT toggle. Never
      includes the channel's credentials, and the channel itself is not editable
      here.
  - name: Agents
    description: >-
      Read-only access to the human and AI agents of an account. A hidden admin
      (the platform's own support user) never appears, on the list or by id.
  - name: Teams
    description: >-
      Teams group agents for assignment. Listing and reading are open to any
      member; creating and updating a team, and managing its membership, require
      an administrator token. A system-managed team (provisioned by the
      platform) can be read like any other but never updated.
  - name: Macros
    description: >-
      Macros bundle a sequence of actions an agent runs against a conversation
      from the dashboard. This surface lets you list, read and write macro
      definitions — running one is not part of the v1 contract. A macro is
      either `global` (visible to the whole account) or `personal` (visible only
      to its author); an agent token can only create personal macros.
  - name: Automation Rules
    description: >-
      The account's automation rules — administrator only. An agent token gets a
      403 on every operation in this group.


      Reading is direct. Writing goes through a propose → confirm pair: the
      propose call validates the change, writes nothing, and returns a
      single-use `proposal_token` with a preview and a list of `warnings`; the
      confirm call sends the token back and applies exactly what was previewed.
      Rules created through the API start off, and turning a rule on or off
      stays with a person in the Cloud Chat automations screen.
  - name: Availability Reasons
    description: >-
      The reasons an agent can go `busy` for, configured per account. Listing is
      open to any member; creating, updating and deleting require an
      administrator token. Deleting is a soft delete — the reason disappears
      from listings but agents' past availability history keeps referencing it.
  - name: Native Attribute Requirements
    description: >-
      Which native conversation attributes (priority, assignee, tag, team) the
      account requires agents to fill before resolving a conversation. Listing
      is open to any member; requiring and un-requiring need an administrator
      token. Deleting a requirement is reversible — require the same key again
      to restore it.
  - name: Custom Attributes
    description: >-
      The custom fields an account added to conversations, contacts and
      companies, and their definitions: key, type, model and options. Listing
      and reading are open to any member; creating and editing need an
      administrator token. Deleting a definition, conditional sub-lists and the
      AI fill settings stay in the Cloud Chat screen.
  - name: Campaigns
    description: Check who a campaign would reach, send it, and read the result back.
  - name: Reports
    description: The numbers of the Cloud Chat reporting dashboards, read through the API.
  - name: Companies
    description: >-
      Companies (the businesses your contacts work for) and the links between
      contacts and companies. Companies must be enabled for the account; when
      they are not, every operation in this group answers `403`. Any member of
      the account can read. Updating a company and linking or unlinking contacts
      is open to agents, supervisors, CX engineers and administrators; an
      assistant is read-only.
paths:
  /v1/accounts/{accountId}/conversations:
    parameters:
      - $ref: '#/components/parameters/CloudChatInstance'
      - $ref: '#/components/parameters/AccountId'
    post:
      tags:
        - Conversations
      summary: Open a conversation
      description: >-
        **This call sends an e-mail to your customer, and it cannot be taken
        back.** It opens a new conversation on one of your e-mail inboxes and
        sends `content` as its first message, with `subject` as the mail
        subject. Use it for one contact per call; to write to many contacts at
        once, use [Create a
        campaign](/api-reference/cloudchat/endpoints/create-a-campaign).


        **The inbox.** It has to be an e-mail inbox your token reaches: every
        inbox of the account for an administrator, only the inboxes the agent is
        a member of otherwise. Any other `inbox_id` is a 422
        `inbox_not_assigned`, whether or not the inbox exists. [List
        inboxes](/api-reference/cloudchat/endpoints/list-inboxes) shows each
        inbox's `channel_type`, which has to be `Channel::Email`, and
        `lock_to_single_conversation`. The message leaves through the inbox's
        own mail account, so the sender, signature and domain are the ones
        already configured there.


        Only e-mail works today: an inbox of any other channel is a 422
        `unsupported_channel`. An inbox with single-conversation mode on is a
        422 `inbox_locked_to_single_conversation`, because the message would
        join the contact's earlier thread and your subject would be dropped.


        **The recipient.** Send exactly one of `email` or `contact_id`. With
        `email`, the contact is created when your account has none with that
        address; `name` only matters then. With `contact_id`, the contact has to
        be in your account and have an e-mail address, and the message goes to
        it. [List contacts](/api-reference/cloudchat/endpoints/list-contacts)
        and [Get a contact](/api-reference/cloudchat/endpoints/get-a-contact)
        read contacts, and are for administrators; any member can send `email`.


        **Retries.** Send an `idempotency_key` on every call: one value per
        message you mean to send, such as an order id plus the purpose. If a
        call times out or you lose the answer, repeat it with the same key and
        exactly the same content. You get the original conversation back with
        `dispatch_status` `duplicate` and the same `message_id`, and nothing is
        sent again. Without a key, a repeat opens a second conversation and
        sends a second e-mail. The same key with a different body, recipients,
        attachments or contact is a 409 and nothing is sent; use a new key for a
        new message. A key is remembered for a limited time and counts per
        inbox, so it protects retries, not a message you send again days later.


        **What a 201 means.** The conversation and its first message exist and
        the e-mail is queued. Delivery happens afterwards: a later bounce does
        not come back through this call. An address that already hard bounced,
        was reported as spam, or bounced on this inbox is refused up front with
        422 `recipient_suppressed`, and nothing is created. A 201 is also the
        answer to a `duplicate`.


        **Rate limit.** Don't hardcode it. Two ceilings apply: the gateway
        limits each credential, and Cloud Chat limits e-mail dispatch per
        account, shared by every credential of the account. `Retry-After` and
        the `ratelimit-*` headers carry the current values.
      operationId: createConversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreateRequest'
            example:
              inbox_id: 12
              email: maria.silva@example.com
              name: Maria Silva
              subject: Your order 1042 has shipped
              content: >-
                Hello Maria, your order left our warehouse today and should
                arrive on Thursday.
              idempotency_key: order-1042-shipped
      responses:
        '201':
          description: >-
            The conversation is open and the e-mail is queued, not yet
            delivered. A repeat with the same `idempotency_key` also answers
            201, with `dispatch_status` `duplicate`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDispatch'
              example:
                id: 1043
                uuid: 9c1d5e0e-6a0c-4f0b-9a54-0d3a5c2f7b11
                status: open
                priority: null
                assignee_id: null
                inbox_id: 12
                team_id: null
                contact:
                  id: 815
                  name: Maria Silva
                labels: []
                custom_attributes: {}
                snoozed_until: null
                waiting_since: null
                created_at: '2026-11-09T19:12:03.114Z'
                updated_at: '2026-11-09T19:12:03.114Z'
                last_activity_at: '2026-11-09T19:12:03.114Z'
                dispatch_status: created
                message_id: 90871
        '400':
          description: >-
            The request itself is malformed: a body that is not valid JSON, or
            `inbox_id`, `email`, `contact_id`, `name`, `subject`, `content` or
            `idempotency_key` sent as an array or an object instead of a plain
            value. The `details` array names each offender. A non-numeric
            `accountId`, such as the literal `{accountId}` some clients send
            when the argument is unset, also lands here, with `details` naming
            `accountId`. The missing `cloudchat-instance` case has its own
            envelope: see [the API
            overview](/api-reference/cloudchat/overview#two-headers-every-call).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: bad_request
                  message: The request is malformed.
                  details:
                    - field: inbox_id
                      code: invalid
                      message: >-
                        The value must be a single scalar, not an array or
                        object.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            The account is suspended. A suspended account is closed even to its
            own members, and nothing is sent. Any member of an active account
            may call this operation, whatever the role.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: forbidden
                  message: This account is suspended.
        '404':
          description: >-
            The account is not there for you (an account that does not exist and
            one you are not a member of are deliberately indistinguishable), or,
            with `contact_id`, the contact is not in your account:
            `details[0].code` is `contact_not_found`. Nothing was sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: Resource could not be found.
        '409':
          description: >-
            A collision, and **nothing was sent**. `details[0].code` says which:
            `idempotency_key_payload_mismatch` when the key was already used
            with different content (repeat the original payload to get the
            original conversation back, or use a new key for a new message),
            `idempotency_key_contact_mismatch` when it was used for another
            contact, and `email_claimed_by_another_contact` when the address is
            already linked to a different contact on this inbox: merge the two
            contacts, or send with the `contact_id` that owns it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationConflict'
              example:
                error:
                  code: conflict
                  message: >-
                    The request conflicts with the current state of the
                    resource.
                  details:
                    - field: idempotency_key
                      code: idempotency_key_payload_mismatch
                      message: >-
                        This idempotency_key was already used for a different
                        payload, so the new message was not sent. Send it with a
                        new key, or resend the original payload to get the
                        original conversation back.
        '422':
          description: >-
            Refused, and **nothing was sent**. `details[0].field` and
            `details[0].code` say what to fix. Codes: `inbox_not_assigned`,
            `unsupported_channel`, `inbox_locked_to_single_conversation`,
            `subject_required`, `content_required`, `identification_required`,
            `ambiguous_identification`, `invalid_email`, `contact_has_no_email`,
            `invalid_recipient`, `too_many_recipients`, `recipient_suppressed`,
            `attachment_not_found`, `too_many_attachments`,
            `attachment_url_unsafe`, `attachment_url_too_large`,
            `attachment_url_wrong_type`, `attachment_url_invalid`,
            `attachment_url_rejected` and `idempotency_key_too_long`. A rule of
            the contact record is reported on `email` or `name`, or on `base`
            for any other rule. The texts are localized to the account's
            language: match on `code` and `field`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: validation_failed
                  message: The request payload is invalid.
                  details:
                    - field: subject
                      code: subject_required
                      message: >-
                        subject is required: it opens the mail thread and
                        becomes the ticket title.
        '429':
          description: >-
            Rate limited, and nothing was sent. The gateway stops the request
            before it reaches Cloud Chat and answers `{ "message": ... }`, while
            Cloud Chat's own per-account ceiling answers the usual `{ "error":
            ... }` envelope with code `rate_limited`. Don't hardcode either
            limit: `Retry-After` says how many seconds to wait. Repeat the same
            call, with the same `idempotency_key`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/GatewayError'
                  - $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limited
                  message: Too many requests. Wait a minute and try again.
        '500':
          description: >-
            Something failed on our side. A failure while the message is built
            leaves no conversation behind, but a 500 does not prove the e-mail
            was not queued, so repeat the call with the same `idempotency_key`:
            if it was, you get the original back instead of a second send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: internal_error
                  message: An unexpected error occurred. Please try again later.
components:
  parameters:
    CloudChatInstance:
      name: cloudchat-instance
      in: header
      required: true
      description: >-
        Your Cloud Chat instance ID — an integer, fixed for your company, told
        at onboarding. [The API
        overview](/api-reference/cloudchat/overview#two-headers-every-call)
        explains how instances work, how to find yours, and the errors a wrong
        or missing value produces.
      schema:
        type: integer
        example: 1
    AccountId:
      name: accountId
      in: path
      required: true
      description: >-
        Your Cloud Chat account. It has to be an account your token grants
        membership on, and it has to live on the instance in the
        `cloudchat-instance` header — the two travel together. Account numbers
        are only unique **within** an instance, so the same number is a
        different company on another instance. Usually a mismatched pair fails
        closed with a 401, because your user does not exist on the other
        instance — but if your identity happens to exist on both, the call
        succeeds against the other company's data, silently. Read it and you are
        looking at the wrong help center; write it and you have stored into the
        wrong account. Send the two values that were given to you together, and
        never try a number to see what answers.
      schema:
        type: integer
        example: 1
  schemas:
    ConversationCreateRequest:
      type: object
      required:
        - inbox_id
        - subject
        - content
      description: >-
        Who receives the e-mail, what it says, and the key that makes a retry
        safe. Send exactly one of `email` or `contact_id`.
      properties:
        inbox_id:
          type: integer
          example: 12
          description: >-
            The e-mail inbox the message leaves from: an `id` from [List
            inboxes](/api-reference/cloudchat/endpoints/list-inboxes) whose
            `channel_type` is `Channel::Email`.
        email:
          type: string
          example: maria.silva@example.com
          description: >-
            Address that receives the message. The contact is created when your
            account has none with this address. Send this or `contact_id`, never
            both.
        contact_id:
          type: integer
          example: 815
          description: >-
            The id of an existing contact of your account, the same `contact.id`
            the conversation endpoints return. The message goes to the e-mail
            address stored on that contact. Send this or `email`, never both.
        name:
          type: string
          example: Maria Silva
          description: >-
            Display name for the contact. Used only when `email` creates a new
            contact: for an existing contact, or with `contact_id`, it changes
            nothing. Left out, the part of the address before the `@` is used.
        subject:
          type: string
          example: Your order 1042 has shipped
          description: >-
            Subject of the e-mail. It also names the conversation for your
            agents.
        content:
          type: string
          example: >-
            Hello Maria, your order left our warehouse today and should arrive
            on Thursday.
          description: Body of the e-mail, as text.
        cc_emails:
          type: array
          items:
            type: string
          example:
            - finance@example.com
          description: >-
            Addresses in copy, visible to the recipient. A single
            comma-separated string is accepted too. Together with `bcc_emails`
            the call takes a limited number of addresses; over it the answer is
            422 `too_many_recipients` and the message names the maximum. A
            malformed address is a 422 `invalid_recipient`.
        bcc_emails:
          type: array
          items:
            type: string
          description: >-
            Addresses in blind copy, with the same rules and the same shared
            limit as `cc_emails`.
        attachment_blob_ids:
          type: array
          items:
            type: integer
          example:
            - 5120
          description: >-
            Images already stored with [Upload an
            image](/api-reference/cloudchat/endpoints/upload-an-image), by the
            `blob_id` it returned (PNG, JPEG or WEBP, up to 10 MB). An id that
            is not a file of your account is a 422 `attachment_not_found` naming
            it.
        attachment_urls:
          type: array
          items:
            type: string
            format: uri
          example:
            - https://files.example.com/invoices/1042.pdf
          description: >-
            Public https links that Cloud Chat downloads and attaches, for the
            documents the upload endpoint does not take: PDF, DOC, DOCX, XLS,
            XLSX, PPT, PPTX, TXT and CSV, up to 25 MB each. The download happens
            inside the call. A link that is private, too big or of another type
            is a 422 with `attachment_url_unsafe`, `attachment_url_too_large`,
            `attachment_url_wrong_type`, `attachment_url_invalid` or
            `attachment_url_rejected`. Together with `attachment_blob_ids` the
            call takes a limited number of attachments, and the answer when you
            go over is 422 `too_many_attachments`.
        idempotency_key:
          type: string
          example: order-1042-shipped
          description: >-
            Your own token for this message, up to 128 characters. Repeating a
            call with the same key and the same content returns the original
            conversation and sends nothing again. Send it on every call.
    ConversationDispatch:
      description: >-
        The conversation that was opened, in the same projection [Get a
        conversation](/api-reference/cloudchat/endpoints/get-a-conversation)
        returns, plus the outcome of the dispatch.
      allOf:
        - $ref: '#/components/schemas/Conversation'
        - type: object
          required:
            - dispatch_status
            - message_id
          properties:
            dispatch_status:
              type: string
              enum:
                - created
                - duplicate
              example: created
              description: >-
                What this call did: `created` when it opened the conversation
                and queued the e-mail, `duplicate` when the `idempotency_key`
                had already opened one and this is the original answer, with
                nothing sent again. The conversation's own state is in `status`.
            message_id:
              type: integer
              nullable: true
              example: 90871
              description: >-
                The id of the first message of the conversation, the e-mail that
                was queued. On a `duplicate`, the one sent the first time. It is
                filled on every normal answer and `null` only when that message
                cannot be found.
    Error:
      type: object
      description: The error envelope every Cloud Chat API response uses.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: >-
                The stable, machine-readable reason. Branch on this, never on
                `message`.
              enum:
                - unauthorized
                - forbidden
                - not_found
                - validation_failed
                - conflict
                - bad_request
                - internal_error
                - rate_limited
                - service_unavailable
              example: not_found
            message:
              type: string
              description: >-
                The reason in words, localized to your account's language
                (English, Spanish or Brazilian Portuguese; English when the
                account is set to anything else). Wording changes with the
                account and between releases, so never match on it.


                Two cases stay in English whatever the account is set to:
                `unauthorized`, decided before any account is known, and the
                account-level `not_found`, which must not reveal the account's
                language.
              example: Resource could not be found.
            details:
              type: array
              description: >-
                Present on some rejections — a 400 for a refused query parameter
                or upload mode, for example. One entry per offending field,
                localized to the account's language like `message` — match on
                `code` and `field`, never on the text.
              items:
                type: object
                required:
                  - field
                  - code
                  - message
                properties:
                  field:
                    type: string
                    description: Which request field the rule was about.
                  code:
                    type: string
                    description: Stable, machine-readable reason.
                  message:
                    type: string
                    description: The rule in words.
    ConversationConflict:
      type: object
      description: A `conflict` error. Nothing was sent.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - details
          properties:
            code:
              type: string
              enum:
                - conflict
              example: conflict
              description: Always `conflict`.
            message:
              type: string
              description: >-
                Localized to the account's language, like every envelope
                message.
              example: The request conflicts with the current state of the resource.
            details:
              type: array
              description: What collides. Match on `code`, never on the text.
              items:
                type: object
                required:
                  - field
                  - code
                  - message
                properties:
                  field:
                    type: string
                    enum:
                      - idempotency_key
                      - email
                      - contact_id
                    description: The request field in conflict.
                  code:
                    type: string
                    enum:
                      - idempotency_key_payload_mismatch
                      - idempotency_key_contact_mismatch
                      - email_claimed_by_another_contact
                    description: >-
                      `idempotency_key_payload_mismatch`: the key was already
                      used with another subject, body, recipients or
                      attachments. `idempotency_key_contact_mismatch`: the key
                      was already used for another contact.
                      `email_claimed_by_another_contact`: the address is already
                      linked to a different contact on this inbox.
                  message:
                    type: string
                    description: The conflict in words.
    GatewayError:
      type: object
      description: >-
        Rejected by the gateway before Cloud Chat saw it, so it does not use the
        `error` envelope.
      required:
        - message
      properties:
        message:
          type: string
          example: API rate limit exceeded
        request_id:
          type: string
          description: Gateway request id. Quote it when reporting a problem.
          example: f3f7567638d4b65a8003057d0c77d275
    Conversation:
      type: object
      required:
        - id
        - uuid
        - status
        - priority
        - assignee_id
        - inbox_id
        - team_id
        - contact
        - labels
        - custom_attributes
        - snoozed_until
        - waiting_since
        - created_at
        - updated_at
        - last_activity_at
      properties:
        id:
          type: integer
          description: >-
            The conversation number — the same one shown in the dashboard URL
            and delivered in webhooks, unique within the account.
          example: 1042
        uuid:
          type: string
          description: >-
            The conversation's canonical id, globally unique and never null —
            the same `cloudChatId` the ClaudIA API takes in [Get a conversation
            summary](/api-reference/claudia/endpoints/get-conversation-summary)
            and [Get a message
            trace](/api-reference/claudia/endpoints/get-message-trace).
          example: 495fd1e4-dbbb-46c6-8463-55cbf7b1d085
        status:
          type: string
          enum:
            - open
            - resolved
            - pending
            - snoozed
            - proactive
          description: Where the conversation is in its lifecycle.
          example: open
        priority:
          type: string
          nullable: true
          description: >-
            The conversation's priority, `null` when none is set. One of the
            four levels the dashboard offers, in ascending urgency.
          example: high
          enum:
            - low
            - medium
            - high
            - urgent
        assignee_id:
          type: integer
          nullable: true
          description: The agent currently assigned, `null` while unassigned.
          example: 7
        inbox_id:
          type: integer
          description: The inbox the conversation lives in.
          example: 3
        team_id:
          type: integer
          nullable: true
          description: The team it is assigned to, `null` when none.
          example: 2
        contact:
          allOf:
            - $ref: '#/components/schemas/ConversationContact'
          nullable: true
          description: The customer, `null` on the rare conversation without one.
        labels:
          type: array
          description: Labels applied to the conversation. Empty when it has none.
          items:
            type: string
            description: One label, exactly as it appears in the dashboard.
            example: vip
        created_at:
          type: string
          format: date-time
          description: When it was created. ISO 8601, always UTC, milliseconds included.
          example: '2026-08-13T19:09:51.482Z'
        updated_at:
          type: string
          format: date-time
          description: >-
            When it last changed, in the same format. This is what
            `updated_after` / `updated_before` filter on.
          example: '2026-08-13T19:42:07.115Z'
        last_activity_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the last message or activity happened. The list is ordered by
            this, newest first.
          example: '2026-08-13T19:42:07.115Z'
        custom_attributes:
          type: object
          description: >-
            The account's custom conversation attributes, as configured in the
            dashboard. Keys and value types vary per account; an account with
            none defined answers `{}`.
          example:
            order_id: A-1029
          nullable: true
        snoozed_until:
          type: string
          format: date-time
          nullable: true
          description: >-
            When a snoozed conversation is scheduled to reopen. `null` outside
            the `snoozed` status.
          example: null
        waiting_since:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the conversation started waiting on the customer's or the
            agent's next move — the field SLA and wait-time reports are built
            on. `null` when nothing is being waited on.
          example: null
    ConversationContact:
      type: object
      description: The customer on the other side of the conversation.
      required:
        - id
        - name
      properties:
        id:
          type: integer
          description: The contact id, stable within the instance.
          example: 815
        name:
          type: string
          nullable: true
          description: The contact display name, when known.
          example: Jane
  responses:
    Unauthorized:
      description: >-
        No Bearer token, or one that is expired, malformed, or not a Cognito
        token. Sign in again for a fresh `id_token`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: >-
                Authentication is required. Send a valid Bearer token in the
                Authorization header.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        The `id_token` from `POST /auth/v1/signin`, sent as `Authorization:
        Bearer <id_token>`. Not the `access_token` — that one does not carry the
        identity Cloud Chat authorizes on.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.