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

# Propose an automation rule

> First half of creating a rule. Validates the rule exactly as the confirm will save it and **writes nothing**: the response previews the rule, lists the `warnings` it raises, and returns a single-use `proposal_token` for `confirmAutomationRuleCreate`. **Administrator only — an agent token gets a 403.**

The rule is always created **off** (`active: false`) and placed after the last rule of its event. `active` in the payload is refused: turning the rule on is done by a person in the Cloud Chat automations screen.

## The propose → confirm flow

Every write to an automation rule goes through two calls: a **propose** that
validates the change, previews it and returns a single-use `proposal_token`,
and a **confirm** that sends the token back and applies exactly what was
previewed, nothing else. The propose call writes nothing. This section walks
through one round trip for a new rule; the edit pair
([propose](https://docs.cloudhumans.com/api-reference/cloudchat/endpoints/propose-automation-rule-edits.md),
[confirm](https://docs.cloudhumans.com/api-reference/cloudchat/endpoints/confirm-automation-rule-edits.md))
and the reorder pair
([propose](https://docs.cloudhumans.com/api-reference/cloudchat/endpoints/propose-a-new-rule-order.md),
[confirm](https://docs.cloudhumans.com/api-reference/cloudchat/endpoints/confirm-a-new-rule-order.md))
follow the same shape. Every call in this group needs an administrator token.

**A person turns rules on and off.** A rule created through the API is always
created **off**, and `active` in a payload is refused with a 422. Turning a
rule on, or off, is done by someone in the Cloud Chat automations screen. The
same idea covers edits: only a rule that is off can be edited through the API.
To change a rule that is running, propose a new rule with the change, and let
a person turn the new one on and the old one off.

Rules with a non-null `managed_by` are kept in sync by the ClaudIA integration.
They can be read, but the API refuses to edit them (403) and a new order must
keep them where they are.

### 1. Propose

Send the rule under `automation_rule`. `name`, `event_name`, `conditions` and
`actions` are required, in the same shape
[getAutomationRule](https://docs.cloudhumans.com/api-reference/cloudchat/endpoints/get-an-automation-rule.md)
returns them.

```json Request theme={null}
POST /cloudchat/v1/accounts/<YOUR_ACCOUNT_ID>/automation-rules/propose-create
{
  "automation_rule": {
    "name": "Tag billing conversations",
    "event_name": "conversation_created",
    "conditions": [
      { "attribute_key": "inbox_id", "filter_operator": "equal_to", "values": [12], "query_operator": null }
    ],
    "actions": [
      { "action_name": "add_label", "action_params": ["billing"] }
    ]
  }
}
```

The response previews the rule as it will be saved, and nothing is written yet:

```json Response theme={null}
{
  "proposal_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJqdGkiOiI0YjEw...",
  "expires_at": "2026-11-12T14:20:00Z",
  "kind": "create",
  "automation_rule": {
    "name": "Tag billing conversations",
    "description": null,
    "event_name": "conversation_created",
    "conditions": [
      { "attribute_key": "inbox_id", "filter_operator": "equal_to", "values": [12], "query_operator": null }
    ],
    "actions": [
      { "action_name": "add_label", "action_params": ["billing"] }
    ],
    "execution_delay": null,
    "delay_trigger": null,
    "active": false,
    "order_id": 4
  },
  "warnings": [
    {
      "code": "same_event_conflict",
      "severity": "medium",
      "message": "The active rule \"Route billing\" (#27) also changes labels on this event and can match the same conversations. When both match, the one that runs last prevails: \"Tag billing conversations\".",
      "rule_ids": [27]
    }
  ]
}
```

### 2. Review the warnings

`warnings` lists risks the change carries, so whoever confirms does it
knowingly. They never block the confirm. Each one has a stable `code`, a
`severity` (`high` or `medium`), a localized `message`, and the `rule_ids` of
the other rules involved.

| Code | Severity | What it means |
| - | - | - |
| `external_loop` | high | On `message_created`, the rule sends a webhook or a message without being limited to incoming messages. If the receiving system answers through the API, its answer triggers the rule again, in a loop. |
| `own_platform_webhook` | high | The webhook points back to this platform, so the call it makes can trigger rules again. |
| `claudia_inbox` | high | The rule changes status, assignee or team in inboxes where ClaudIA answers, which can take the conversation away from her. |
| `broad_scope` | medium | The rule is not limited to an inbox, so it applies to the whole account. |
| `same_event_conflict` | medium | An active rule on the same event changes the same thing and can match the same conversations. The one that runs last prevails. |
| `same_event_conflict_delayed` | medium | The same conflict, but one of the two rules waits before running (`execution_delay`), so the order does not decide which value stays and no winner is named. |
| `cross_event_oscillation` | medium | An active rule on another event changes the same thing, and one of the two reads it in its conditions, so the conversation can swing back and forth. |
| `dispute_winner_changed` | medium | Reorder only: the new order changes which of two conflicting active rules prevails. Rules that wait before running are left out of this check. |

Branch on `code`, never on `message`. If the preview or a warning shows
something you did not intend, discard the token and propose again.

### 3. Confirm

Send back **only** the `proposal_token`, before `expires_at`. No other body
field is read: the server applies the proposal it stored.

```json Request theme={null}
POST /cloudchat/v1/accounts/<YOUR_ACCOUNT_ID>/automation-rules/confirm-create
{
  "proposal_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJqdGkiOiI0YjEw..."
}
```

The 201 response carries the saved rule, still off, in the same shape
`getAutomationRule` returns.

The token works once, only for the user who proposed, and only on the account
it was issued for. A reused, expired or foreign token answers 400
`invalid_proposal`. A confirm also answers 409 `stale_proposal` when the rules
it depends on changed after the proposal: for a create or a reorder, any rule
of the same event; for an edit, the rule itself, for example someone edited it
in the screen. Nothing is written in either case: read the
rules again and propose again.


## OpenAPI

````yaml api-reference/specs/cloudchat/v1.json POST /v1/accounts/{accountId}/automation-rules/propose-create
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}/automation-rules/propose-create:
    parameters:
      - $ref: '#/components/parameters/CloudChatInstance'
      - $ref: '#/components/parameters/AccountId'
    post:
      tags:
        - Automation Rules
      summary: Propose an automation rule
      description: >-
        First half of creating a rule. Validates the rule exactly as the confirm
        will save it and **writes nothing**: the response previews the rule,
        lists the `warnings` it raises, and returns a single-use
        `proposal_token` for `confirmAutomationRuleCreate`. **Administrator only
        — an agent token gets a 403.**


        The rule is always created **off** (`active: false`) and placed after
        the last rule of its event. `active` in the payload is refused: turning
        the rule on is done by a person in the Cloud Chat automations screen.
      operationId: proposeAutomationRuleCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationRuleProposeCreateRequest'
      responses:
        '200':
          description: The proposal. Nothing was written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationRuleCreateProposal'
        '400':
          description: >-
            The request shape is wrong, before any value is validated.
            `details[].code` says why: `invalid_payload` when `automation_rule`
            is missing, is not an object, or `conditions`/`actions` are not
            lists of objects; `not_allowed` (one entry per field) when the
            payload carries a field the API does not write, such as `managed_by`
            or `folder_id`. Also covers the malformed-request cases every
            endpoint shares.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_payload:
                  summary: invalid_payload
                  value:
                    error:
                      code: bad_request
                      message: The request is malformed.
                      details:
                        - field: base
                          code: invalid_payload
                          message: >-
                            Send the rule as an object under automation_rule.
                            conditions and actions must be lists of objects.
                unknown_field:
                  summary: unknown_field
                  value:
                    error:
                      code: bad_request
                      message: The request is malformed.
                      details:
                        - field: managed_by
                          code: not_allowed
                          message: >-
                            These fields cannot be set through the API:
                            managed_by. Accepted fields: name, description,
                            event_name, conditions, actions, execution_delay,
                            delay_trigger.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Two situations answer with this code: the account is suspended (the
            reason every endpoint shares), or your token is not an administrator
            — this operation requires one.
          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'
        '422':
          description: >-
            The payload was understood but a value is not acceptable.
            `details[].field` names it: `active` with code `not_allowed` when
            the payload tries to turn the rule on; a required field (`name`,
            `event_name`, `conditions`, `actions`) with code `blank`;
            `inclusion` on field `event_name` for an event the API does not
            accept (the message lists the accepted ones), `inclusion` on field
            `actions` for an `action_name` outside the supported set (the
            message lists both), and `invalid` on field `conditions` when a
            condition uses an unknown attribute, an operator the attribute does
            not accept, or a custom attribute the account does not have; or the
            field another rule validation refused, such as a `delay_trigger`
            that does not fit the event. For those other refusals, `code`
            carries the same text as `message` rather than a short token, so
            branch on `field`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                active_not_allowed:
                  summary: active_not_allowed
                  value:
                    error:
                      code: validation_failed
                      message: The request payload is invalid.
                      details:
                        - field: active
                          code: not_allowed
                          message: >-
                            Rules are turned on and off by a person in the
                            automations screen. Remove active from the payload.
                blank:
                  summary: blank
                  value:
                    error:
                      code: validation_failed
                      message: The request payload is invalid.
                      details:
                        - field: event_name
                          code: blank
                          message: This field is required.
                model_validation:
                  summary: model_validation
                  value:
                    error:
                      code: validation_failed
                      message: The request payload is invalid.
                      details:
                        - field: conditions
                          code: Automation conditions not_a_condition not supported.
                          message: Automation conditions not_a_condition not supported.
                invalid_event:
                  summary: invalid_event
                  value:
                    error:
                      code: validation_failed
                      message: The request payload is invalid.
                      details:
                        - field: event_name
                          code: inclusion
                          message: >-
                            The value must be one of: conversation_created,
                            conversation_updated, message_created,
                            conversation_opened, conversation_csat_submitted.
                unsupported_actions:
                  summary: unsupported_actions
                  value:
                    error:
                      code: validation_failed
                      message: The request payload is invalid.
                      details:
                        - field: actions
                          code: inclusion
                          message: >-
                            Unsupported actions: delete_conversation. Supported
                            actions: send_message, add_label, remove_label,
                            add_contact_label, remove_contact_label,
                            send_email_to_team, assign_team, assign_agent,
                            send_webhook_event, mute_conversation,
                            change_status, resolve_conversation,
                            snooze_conversation, mark_conversation_as_pending,
                            change_priority, send_email_transcript,
                            update_conversation_custom_attrs,
                            update_contact_custom_attrs, add_sla,
                            send_csat_survey, send_whatsapp_template,
                            add_private_note, open_conversation,
                            remove_assigned_team.
                invalid_conditions:
                  summary: invalid_conditions
                  value:
                    error:
                      code: validation_failed
                      message: The request payload is invalid.
                      details:
                        - field: conditions
                          code: invalid
                          message: >-
                            One or more conditions use an unknown attribute, an
                            operator the attribute does not accept, or a custom
                            attribute that does not exist in this account.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
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:
    AutomationRuleProposeCreateRequest:
      type: object
      required:
        - automation_rule
      properties:
        automation_rule:
          allOf:
            - $ref: '#/components/schemas/AutomationRuleWriteInput'
          description: >-
            The new rule. `name`, `event_name`, `conditions` and `actions` are
            required.
      example:
        automation_rule:
          name: Tag billing conversations
          event_name: conversation_created
          conditions:
            - attribute_key: inbox_id
              filter_operator: equal_to
              values:
                - 12
              query_operator: null
          actions:
            - action_name: add_label
              action_params:
                - billing
    AutomationRuleCreateProposal:
      type: object
      required:
        - proposal_token
        - expires_at
        - kind
        - automation_rule
        - warnings
      properties:
        proposal_token:
          type: string
          description: >-
            Single-use token for the matching confirm call. It is tied to this
            account and to the user who proposed, and it stops working at
            `expires_at`.
          example: eyJfcmFpbHMiOnsiZGF0YSI6eyJqdGkiOiI0YjEw...
        expires_at:
          type: string
          format: date-time
          description: >-
            When the token stops working. Read it from here instead of assuming
            a fixed lifetime.
          example: '2026-11-12T14:20:00Z'
        kind:
          type: string
          enum:
            - create
          example: create
        automation_rule:
          $ref: '#/components/schemas/AutomationRuleProposedRule'
        warnings:
          type: array
          description: Risks detected in the proposal. Empty when nothing was found.
          items:
            $ref: '#/components/schemas/AutomationRuleWarning'
    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.
    AutomationRuleWriteInput:
      type: object
      description: >-
        The fields of a rule the API writes. Any other key is refused with a 400
        that lists the accepted ones. `active` is refused with a 422: a rule is
        turned on and off by a person in the automations screen.
      properties:
        name:
          type: string
          example: Tag billing conversations
        description:
          type: string
          nullable: true
          example: Adds the billing label to new conversations of the billing inbox.
        event_name:
          type: string
          description: >-
            The event that triggers evaluation, e.g. `conversation_created`,
            `conversation_updated`, `message_created`.
          example: conversation_created
        conditions:
          type: array
          description: >-
            The rule's condition set, in the same shape `getAutomationRule`
            returns. Must be a list of objects.
          items:
            type: object
          example:
            - attribute_key: inbox_id
              filter_operator: equal_to
              values:
                - 12
              query_operator: null
        actions:
          type: array
          description: >-
            The rule's action set, in the same shape `getAutomationRule`
            returns. Must be a list of objects.
          items:
            type: object
          example:
            - action_name: add_label
              action_params:
                - billing
        execution_delay:
          type: integer
          nullable: true
          description: >-
            Minutes to wait before the rule runs. Send it together with
            `delay_trigger`, or leave both out. A value outside the accepted
            range is refused with a 422 whose message gives the range.
        delay_trigger:
          type: string
          nullable: true
          description: >-
            What the wait measures: `customer_unresponsive` or
            `agent_unresponsive` (event `message_created`), or `status_idle`
            (event `conversation_updated`).
          enum:
            - customer_unresponsive
            - agent_unresponsive
            - status_idle
            - null
    AutomationRuleProposedRule:
      type: object
      description: The rule as it will be created. It has no `id` yet.
      required:
        - name
        - description
        - event_name
        - conditions
        - actions
        - execution_delay
        - delay_trigger
        - active
        - order_id
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
        event_name:
          type: string
          description: >-
            The event that triggers evaluation, e.g. `conversation_created`,
            `conversation_updated`, `message_created`.
        conditions:
          type: array
          description: >-
            The rule's condition set, in the same shape `getAutomationRule`
            returns. Must be a list of objects.
          items:
            type: object
        actions:
          type: array
          description: >-
            The rule's action set, in the same shape `getAutomationRule`
            returns. Must be a list of objects.
          items:
            type: object
        execution_delay:
          type: integer
          nullable: true
          description: >-
            Minutes to wait before the rule runs. Send it together with
            `delay_trigger`, or leave both out. A value outside the accepted
            range is refused with a 422 whose message gives the range.
        delay_trigger:
          type: string
          nullable: true
          description: >-
            What the wait measures: `customer_unresponsive` or
            `agent_unresponsive` (event `message_created`), or `status_idle`
            (event `conversation_updated`).
          enum:
            - customer_unresponsive
            - agent_unresponsive
            - status_idle
            - null
        active:
          type: boolean
          description: 'Always `false`: the rule is created off.'
          example: false
        order_id:
          type: integer
          description: 'The position the rule will take: after the last rule of its event.'
          example: 4
    AutomationRuleWarning:
      type: object
      description: >-
        A risk the proposal carries. Warnings never block the confirm: they are
        there for whoever decides to confirm.
      required:
        - code
        - severity
        - message
        - rule_ids
      properties:
        code:
          type: string
          description: >-
            What was detected. Branch on this, never on `message`.


            - `external_loop` — on `message_created`, the rule sends a webhook
            or a message without being limited to incoming messages, so an
            answer from the receiving system can trigger it again.

            - `own_platform_webhook` — the webhook points back to this platform.

            - `claudia_inbox` — the rule changes status, assignee or team in
            inboxes where ClaudIA answers.

            - `broad_scope` — the rule is not limited to an inbox, so it applies
            to the whole account.

            - `same_event_conflict` — an active rule on the same event changes
            the same thing and can match the same conversations; the one that
            runs last prevails.

            - `same_event_conflict_delayed` — the same conflict, but one of the
            two rules waits before running (`execution_delay`), so the order
            does not decide which value stays and no winner is named.

            - `cross_event_oscillation` — an active rule on another event
            changes the same thing, and one of the two reads it in its
            conditions.

            - `dispute_winner_changed` — reorder only: the new order changes
            which of two conflicting active rules prevails. Rules that wait
            before running are left out of this check.
          enum:
            - external_loop
            - own_platform_webhook
            - claudia_inbox
            - broad_scope
            - same_event_conflict
            - same_event_conflict_delayed
            - cross_event_oscillation
            - dispute_winner_changed
          example: same_event_conflict
        severity:
          type: string
          enum:
            - high
            - medium
          example: medium
        message:
          type: string
          description: The risk in words, localized to the account's language.
          example: >-
            The active rule "Route billing" (#27) also changes team_id on this
            event and can match the same conversations. When both match, the one
            that runs last prevails: "Tag billing conversations".
        rule_ids:
          type: array
          description: >-
            The other rules involved, when there are any. Empty for a warning
            about the proposed rule alone.
          items:
            type: integer
          example:
            - 27
    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.