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

# Update the satisfaction survey of an inbox

> Administrator only. Changes the language, the scale or the texts of the survey and answers with the survey as stored, read back. What is not sent stays untouched, including `content` keys you leave out. An object with none of `language`, `format` and `content` is a 400. An inbox with no survey yet needs `format` together with `language` and a complete `content`. A field or `content` key outside the writable ones is refused with 422 and code `not_editable`. On a WhatsApp Cloud inbox, saving with a language makes CloudChat publish the survey form and submit the message template for that language to Meta, unless it already exists there. Meta reviews it asynchronously, so the response can still say `pending`, and the survey is delivered only once `status` is `approved`. Only WhatsApp Cloud, web widget and email inboxes carry a satisfaction survey. Any other inbox answers 422 with code `unsupported_channel`.



## OpenAPI

````yaml api-reference/specs/cloudchat/v1.json PATCH /v1/accounts/{accountId}/inboxes/{inboxId}/csat-survey
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}/inboxes/{inboxId}/csat-survey:
    parameters:
      - $ref: '#/components/parameters/CloudChatInstance'
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/InboxId'
    patch:
      tags:
        - Inboxes
      summary: Update the satisfaction survey of an inbox
      description: >-
        Administrator only. Changes the language, the scale or the texts of the
        survey and answers with the survey as stored, read back. What is not
        sent stays untouched, including `content` keys you leave out. An object
        with none of `language`, `format` and `content` is a 400. An inbox with
        no survey yet needs `format` together with `language` and a complete
        `content`. A field or `content` key outside the writable ones is refused
        with 422 and code `not_editable`. On a WhatsApp Cloud inbox, saving with
        a language makes CloudChat publish the survey form and submit the
        message template for that language to Meta, unless it already exists
        there. Meta reviews it asynchronously, so the response can still say
        `pending`, and the survey is delivered only once `status` is `approved`.
        Only WhatsApp Cloud, web widget and email inboxes carry a satisfaction
        survey. Any other inbox answers 422 with code `unsupported_channel`.
      operationId: updateCsatSurvey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CsatSurveyUpdateRequest'
            example:
              csat_survey:
                language: pt_BR
                format: full_5
                content:
                  question: Como foi o atendimento?
                  option_labels:
                    - Excelente
                    - Bom
                    - Regular
                    - Ruim
                    - Péssimo
                  comment_prompt: Quer contar o motivo?
                  submit_label: Enviar
      responses:
        '200':
          description: The satisfaction survey after the update.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CsatSurvey'
              example:
                id: 3
                name: Support WhatsApp
                channel_type: Channel::Whatsapp
                requires_approval: true
                format: full_5
                language: pt_BR
                content:
                  question: Como foi o atendimento?
                  option_labels:
                    - Excelente
                    - Bom
                    - Regular
                    - Ruim
                    - Péssimo
                  comment_prompt: Quer contar o motivo?
                  submit_label: Enviar
                status: pending
                provisioning_error: null
        '400':
          description: >-
            A `csat_survey` payload that is not an object, or one with none of
            `language`, `format` and `content`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: bad_request
                  message: The request is malformed.
                  details:
                    - field: csat_survey
                      code: empty
                      message: >-
                        Provide at least one of language, format or content
                        inside csat_survey.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: >-
            Nothing was saved. `details` names the field at fault: a `language`
            or `format` outside the accepted values, a field or `content` key
            that is not editable (`not_editable`), a value of the wrong type, a
            text over its limit, `option_labels` without exactly five entries, a
            missing `format` on an inbox with no survey (`required`), or an
            inbox whose channel carries no survey (`unsupported_channel`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: validation_failed
                  message: The request payload is invalid.
                  details:
                    - field: language
                      code: invalid
                      message: 'The language must be one of: en, es, pt_BR.'
        '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
    InboxId:
      name: inboxId
      in: path
      required: true
      description: The `id` returned when the inbox was created or listed.
      schema:
        type: integer
        example: 3
  schemas:
    CsatSurveyUpdateRequest:
      type: object
      description: The fields to change go under `csat_survey`.
      required:
        - csat_survey
      properties:
        csat_survey:
          $ref: '#/components/schemas/CsatSurveyUpdate'
    CsatSurvey:
      type: object
      description: The satisfaction survey of one inbox.
      required:
        - id
        - name
        - channel_type
        - requires_approval
        - format
        - language
        - content
        - status
        - provisioning_error
      properties:
        id:
          type: integer
          description: The id of the inbox the survey belongs to.
          example: 3
        name:
          type: string
          description: Inbox name.
          example: Support WhatsApp
        channel_type:
          type: string
          description: '`Channel::WebWidget`, `Channel::Email` or `Channel::Whatsapp`.'
          nullable: true
          example: Channel::Whatsapp
        requires_approval:
          type: boolean
          description: >-
            True on a WhatsApp Cloud inbox, where the survey is a message
            template Meta has to approve before it is delivered.
          example: true
        format:
          type: string
          description: >-
            The scale: `full_5` is a rating from 1 to 5 followed by a comment
            step, `rating_5` is the rating only. Null while the inbox has no
            survey.
          nullable: true
          enum:
            - full_5
            - rating_5
          example: full_5
        language:
          type: string
          description: Language of the survey. Null while the inbox has no survey.
          nullable: true
          enum:
            - en
            - es
            - pt_BR
          example: pt_BR
        content:
          $ref: '#/components/schemas/CsatSurveyContent'
        status:
          type: string
          description: >-
            `unconfigured`: no survey yet. `ready`: web widget and email, the
            survey is live. `not_created`: WhatsApp, the template was not
            submitted yet. `pending`: Meta is reviewing it. `approved`: it is
            delivered. `rejected`: Meta refused it. `failed`: the submission to
            Meta failed, see `provisioning_error`.
          enum:
            - unconfigured
            - ready
            - not_created
            - pending
            - approved
            - rejected
            - failed
          example: pending
        provisioning_error:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CsatSurveyProvisioningError'
          description: >-
            Why the last submission to Meta failed. Null when there is none, and
            always null outside WhatsApp Cloud.
    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.
    CsatSurveyUpdate:
      type: object
      description: The fields to change, at least one of them.
      additionalProperties: false
      minProperties: 1
      properties:
        language:
          type: string
          description: >-
            Language of the survey. On WhatsApp Cloud a new language is
            submitted to Meta for approval.
          enum:
            - en
            - es
            - pt_BR
        format:
          type: string
          description: The scale. Required when the inbox has no survey yet.
          enum:
            - full_5
            - rating_5
        content:
          $ref: '#/components/schemas/CsatSurveyContentUpdate'
    CsatSurveyContent:
      type: object
      description: The texts of the survey. A key that was never set is absent.
      properties:
        question:
          type: string
          description: The question the contact is asked.
          nullable: true
          example: Como foi o atendimento?
        option_labels:
          type: array
          description: The five rating labels, from the best rating (5) to the worst (1).
          nullable: true
          items:
            type: string
          example:
            - Excelente
            - Bom
            - Regular
            - Ruim
            - Péssimo
        comment_prompt:
          type: string
          description: >-
            The prompt of the free-text comment step. Used by the `full_5`
            format.
          nullable: true
          example: Quer contar o motivo?
        submit_label:
          type: string
          description: Text of the button that sends the answer.
          nullable: true
          example: Enviar
    CsatSurveyProvisioningError:
      type: object
      description: Why the last submission of the survey to Meta failed.
      required:
        - reason
        - at
      properties:
        reason:
          type: string
          description: What failed, as a stable code.
          example: template_submission_failed
        detail:
          type: string
          description: The message Meta answered with.
          nullable: true
        language:
          type: string
          description: The survey language the failed submission was for.
          nullable: true
          example: pt_BR
        at:
          type: string
          description: When it failed (ISO 8601).
          format: date-time
    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
    CsatSurveyContentUpdate:
      type: object
      description: The texts to change. A key you leave out keeps its current value.
      additionalProperties: false
      minProperties: 1
      properties:
        question:
          type: string
          description: Up to 255 characters, 80 on WhatsApp Cloud.
        option_labels:
          type: array
          description: >-
            The five rating labels, from the best rating (5) to the worst (1),
            each up to 30 characters. Always send all five.
          minItems: 5
          maxItems: 5
          items:
            type: string
        comment_prompt:
          type: string
          description: >-
            Prompt of the comment step, used by `full_5`. Up to 255 characters,
            80 on WhatsApp Cloud.
        submit_label:
          type: string
          description: Text of the button that sends the answer, up to 30 characters.
  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.
    Forbidden:
      description: >-
        The operation was refused for who you are, not for what you sent. Two
        causes:


        - **Your role does not permit it.** Several operations here need an
        administrator, and a few need a supervisor or a CX engineer; where it
        matters, the operation says so in its own 403. Changing your own role is
        not something the API can do — ask an administrator of the account.

        - **The account is suspended.** Then nothing on it can be read or
        written until that is resolved — talk to your Cloud Humans contact.


        Not being a member of the account is a **404**, not a 403: an account
        you cannot reach and an account that does not exist are deliberately
        indistinguishable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: This account is suspended.
    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.