> ## 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.

# Change the status of a conversation

> Move a conversation to an explicit status: `open` (also how a resolved conversation is reopened), `resolved`, `pending` or `snoozed`. There is no toggle — you say the status you want, and asking for the status the conversation already has succeeds without changing anything, the assignee included.

For `snoozed`, `snoozed_until` is an optional ISO 8601 instant in the future when the conversation should come back. Omit it to snooze until the customer's next reply (snoozing again without it clears a wake-up time set earlier); sending it with any other status is a 422.

The dashboard rules apply, and each refusal says how to fix it:

- a conversation **merged into another one** is read-only — a 409;
- a parent conversation cannot be **resolved while its parallel conversations are still open** — a 409 whose message lists them;
- an account that **requires fields before a conversation can be resolved** answers 422 with one entry in `error.details` per missing field.

Reopening a conversation that was not open (resolved, pending or snoozed) with an agent token assigns it to that agent, as the dashboard does; tokens of other roles are not assigned, and a conversation that is already open keeps its assignee. When ClaudIA holds the conversation, that assignment follows the account's takeover permissions, like the assign endpoint: a role that may not take over gets a 403 and nothing changes, and when ClaudIA cannot be reached the answer is a 503 (409 if a transfer is already in progress) and the conversation stays reopened but not reassigned, so retry the handover with the assign endpoint. Resolving can make Cloud Chat send the customer the satisfaction survey when the inbox has it enabled, and that message cannot be undone. Visibility follows the same rule as the list: an administrator token reaches every inbox of the account, an agent token only its own inbox memberships. A conversation outside that reach answers 404, indistinguishable from an id that does not exist. A conversation mirrored from another helpdesk is read-only here and answers 409.



## OpenAPI

````yaml api-reference/specs/cloudchat/v1.json PATCH /v1/accounts/{accountId}/conversations/{conversationId}/status
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/{conversationId}/status:
    parameters:
      - $ref: '#/components/parameters/CloudChatInstance'
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/ConversationId'
    patch:
      tags:
        - Conversations
      summary: Change the status of a conversation
      description: >-
        Move a conversation to an explicit status: `open` (also how a resolved
        conversation is reopened), `resolved`, `pending` or `snoozed`. There is
        no toggle — you say the status you want, and asking for the status the
        conversation already has succeeds without changing anything, the
        assignee included.


        For `snoozed`, `snoozed_until` is an optional ISO 8601 instant in the
        future when the conversation should come back. Omit it to snooze until
        the customer's next reply (snoozing again without it clears a wake-up
        time set earlier); sending it with any other status is a 422.


        The dashboard rules apply, and each refusal says how to fix it:


        - a conversation **merged into another one** is read-only — a 409;

        - a parent conversation cannot be **resolved while its parallel
        conversations are still open** — a 409 whose message lists them;

        - an account that **requires fields before a conversation can be
        resolved** answers 422 with one entry in `error.details` per missing
        field.


        Reopening a conversation that was not open (resolved, pending or
        snoozed) with an agent token assigns it to that agent, as the dashboard
        does; tokens of other roles are not assigned, and a conversation that is
        already open keeps its assignee. When ClaudIA holds the conversation,
        that assignment follows the account's takeover permissions, like the
        assign endpoint: a role that may not take over gets a 403 and nothing
        changes, and when ClaudIA cannot be reached the answer is a 503 (409 if
        a transfer is already in progress) and the conversation stays reopened
        but not reassigned, so retry the handover with the assign endpoint.
        Resolving can make Cloud Chat send the customer the satisfaction survey
        when the inbox has it enabled, and that message cannot be undone.
        Visibility follows the same rule as the list: an administrator token
        reaches every inbox of the account, an agent token only its own inbox
        memberships. A conversation outside that reach answers 404,
        indistinguishable from an id that does not exist. A conversation
        mirrored from another helpdesk is read-only here and answers 409.
      operationId: updateConversationStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationStatusUpdateRequest'
            example:
              status: snoozed
              snoozed_until: '2026-12-01T09:00:00Z'
      responses:
        '200':
          description: The conversation after the change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: >-
            Malformed request: `status` or `snoozed_until` sent as an array or a
            nested object instead of a plain value. `details` names the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                error:
                  code: bad_request
                  message: The request is malformed.
                  details:
                    - field: status
                      code: invalid
                      message: >-
                        The value must be a single scalar, not an array or
                        object.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Two situations answer with this code: the account is suspended, or
            reopening would take the conversation over from ClaudIA and your
            role may not do that. In both the status is not changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: forbidden
                  message: You are not allowed to perform this action.
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            The conversation cannot change status in its current state.
            `error.details[0].code` says why — `merged` (it was merged into
            another conversation), `external_read_only` (it is mirrored from
            another helpdesk) or `parallel_resolution_blocked` (its parallel
            conversations are still open, listed in the message) or
            `handoff_failed` (a ClaudIA transfer is already in progress; wait a
            few seconds and retry) — and the message says what to do.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                error:
                  code: conflict
                  message: >-
                    The request conflicts with the current state of the
                    resource.
                  details:
                    - field: conversation
                      code: merged
                      message: >-
                        This conversation was merged into another one and is
                        read-only. Work on the conversation it was merged into.
        '422':
          description: >-
            The change was refused. `details` names the field at fault: a
            missing `status` or one outside `open`, `resolved`, `pending`,
            `snoozed`; a `snoozed_until` that is not an ISO 8601 instant in the
            future, or that comes with a status other than `snoozed`; or, when
            resolving, one entry per field the account requires first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                error:
                  code: validation_failed
                  message: >-
                    This account requires fields to be filled before a
                    conversation can be resolved. The details list each missing
                    field.
                  details:
                    - field: priority
                      code: required
                      message: >-
                        Set a priority with the update conversation endpoint,
                        then resolve again.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: >-
            Reopening needed ClaudIA to hand the conversation over and it could
            not be reached. The conversation was reopened but not reassigned;
            retry the handover with the assign endpoint in a few minutes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                error:
                  code: service_unavailable
                  message: >-
                    The reporting service is temporarily unavailable. Try again
                    in a few minutes.
                  details:
                    - field: conversation
                      code: handoff_failed
                      message: >-
                        The conversation could not be taken over from ClaudIA
                        right now and was not reassigned. Try again in a few
                        minutes.
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
    ConversationId:
      name: conversationId
      in: path
      required: true
      description: >-
        The conversation's **display_id** — the number shown in the dashboard
        URL and delivered in webhooks. It is never the internal database id, and
        it is never the conversation's `uuid`: when all you have is a uuid or a
        helpdesk ticket id, resolve it to a display_id with [Find a
        conversation](/api-reference/cloudchat/endpoints/find-a-conversation)
        first.
      schema:
        type: integer
        example: 1042
  schemas:
    ConversationStatusUpdateRequest:
      type: object
      description: The status to move the conversation to.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - open
            - resolved
            - pending
            - snoozed
          description: >-
            Status to move the conversation to. `open` also reopens a resolved,
            pending or snoozed conversation and, for an agent token, assigns it
            to that agent; on a conversation that is already open it changes
            nothing. There is no toggle: the conversation ends up in exactly
            this status.
          example: resolved
        snoozed_until:
          type: string
          format: date-time
          description: >-
            Only with `status` `snoozed`: the instant the conversation comes
            back, ISO 8601 and in the future. Omit it to snooze until the
            customer's next reply, which also clears a wake-up time set earlier;
            sending it with any other status is a 422.
          example: '2026-12-01T09:00:00Z'
    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
    ValidationError:
      type: object
      description: A `validation_failed` error, which carries `details`.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - details
          properties:
            code:
              type: string
              enum:
                - validation_failed
              example: validation_failed
            message:
              type: string
              description: >-
                Localized to the account's language, like every other envelope
                message.
              example: The request payload is invalid.
            details:
              type: array
              description: >-
                One entry per rejected field. Unlike the envelope message above,
                the texts come from the model layer and are in English in
                practice (the model layer ships no translations) — 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 — `short_code` or
                      `content`. A rule that is not tied to either is reported
                      as `base`, so treat `base` as "the payload as a whole"
                      rather than a field you can highlight.
                    enum:
                      - short_code
                      - content
                      - base
                    example: short_code
                  code:
                    type: string
                    description: >-
                      Which rule it broke — `blank` for a missing or empty
                      value, `taken` for a `short_code` already used on the
                      account.
                    example: taken
                  message:
                    type: string
                    example: has already been taken
    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.
    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
    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
  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.
    NotFound:
      description: >-
        The resource is not there for you. Three situations answer with this
        code, and the first two apply to **every** endpoint — the account is
        resolved before anything else runs, so a list or a create fails this way
        too:


        - the account does not exist on this instance,

        - the account exists but your token has no membership on it,

        - on an endpoint that names one, the resource it names (a canned
        response, a portal, an article) does not exist where the path says it
        does.


        The first two are deliberately indistinguishable — same status, same
        body, and the message stays in English in both, since translating it
        would reveal the account's configured language. So you cannot use this
        endpoint to find out which account ids exist. The third case is
        localized like every other error, which is safe because you only reach
        it once membership is established.


        Either way a 404 is not worth retrying. Check the `accountId`, the
        `cloudchat-instance` value, and that your user is a member of the
        account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Resource could not be found.
    TooManyRequests:
      description: >-
        Rate limited per credential. Note the envelope: this one is `{
        "message": ... }`, because the request never reached the API.


        Don't hardcode the limit — read it from the response. `Retry-After` says
        how many seconds to wait, and every response (not just this one) carries
        `ratelimit-limit`, `ratelimit-remaining` and `ratelimit-reset`, the last
        in seconds.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          example:
            message: API rate limit exceeded
    InternalError:
      description: >-
        Something failed on our side. The response never carries the underlying
        error, but it is reported to our monitoring automatically — no need to
        file anything for a one-off.


        Retrying is reasonable, with one caveat on `POST`: a 500 does not prove
        the write did not happen, so a retry can come back `422` with
        `short_code` already taken. That 422 means the first attempt succeeded —
        list the account and confirm before treating it as a failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: internal_error
              message: An unexpected error occurred. Please try again later.
  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.