> ## 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 a message template

> Edits an existing WhatsApp template and sends it back to Meta for review.

**The edit replaces every component.** Send the complete set the template should have afterwards, not only the part that changes. The template is identified by `name` in the path and `language` in the body, and has to exist in the synced catalogue of this inbox; otherwise the call answers `404` with code `not_found` in `error.details`. A template created a few minutes ago may not have synced yet. Names and languages come from [List message templates](/api-reference/cloudchat/endpoints/list-message-templates), which shows approved templates only.

Administrators only, and only on an official WhatsApp Cloud API inbox (any other answers `422` with code `unsupported_channel`). `name`, `category` and `language` cannot be changed: sending `name` or `category` answers `422` with code `not_editable`, and a different language is a different template, so create a new one instead. Headers are text only, and the variable and button rules of [Create a message template](/api-reference/cloudchat/endpoints/create-a-message-template) apply.

**Meta decides what can be edited** and says no with `422` and code `meta_rejected`. Only templates that are approved, rejected or paused can be edited, and Meta limits how often an approved template can be edited. The answer carries `id`, `name`, `language` and `category` but no status: success only means Meta accepted the resubmission for review.



## OpenAPI

````yaml api-reference/specs/cloudchat/v1.json PATCH /v1/accounts/{accountId}/inboxes/{inboxId}/message-templates/{name}
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}/message-templates/{name}:
    parameters:
      - $ref: '#/components/parameters/CloudChatInstance'
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/InboxId'
    patch:
      tags:
        - Campaigns
      summary: Update a message template
      description: >-
        Edits an existing WhatsApp template and sends it back to Meta for
        review.


        **The edit replaces every component.** Send the complete set the
        template should have afterwards, not only the part that changes. The
        template is identified by `name` in the path and `language` in the body,
        and has to exist in the synced catalogue of this inbox; otherwise the
        call answers `404` with code `not_found` in `error.details`. A template
        created a few minutes ago may not have synced yet. Names and languages
        come from [List message
        templates](/api-reference/cloudchat/endpoints/list-message-templates),
        which shows approved templates only.


        Administrators only, and only on an official WhatsApp Cloud API inbox
        (any other answers `422` with code `unsupported_channel`). `name`,
        `category` and `language` cannot be changed: sending `name` or
        `category` answers `422` with code `not_editable`, and a different
        language is a different template, so create a new one instead. Headers
        are text only, and the variable and button rules of [Create a message
        template](/api-reference/cloudchat/endpoints/create-a-message-template)
        apply.


        **Meta decides what can be edited** and says no with `422` and code
        `meta_rejected`. Only templates that are approved, rejected or paused
        can be edited, and Meta limits how often an approved template can be
        edited. The answer carries `id`, `name`, `language` and `category` but
        no status: success only means Meta accepted the resubmission for review.
      operationId: updateWhatsappTemplate
      parameters:
        - name: name
          in: path
          required: true
          description: >-
            Name of the template to edit, exactly as [List message
            templates](/api-reference/cloudchat/endpoints/list-message-templates)
            returns it. It cannot be changed.
          schema:
            type: string
            example: reactivation_september
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappTemplateUpdateRequest'
      responses:
        '200':
          description: Meta accepted the edit for review.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsappTemplateEdit'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >-
            No such resource, or none these credentials can reach: an account,
            an inbox, or a template (by `name` and `language`) missing from this
            inbox's synced catalogue. When the template is the missing piece,
            `error.details` names it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: Resource could not be found.
                  details:
                    - field: name
                      code: not_found
                      message: >-
                        This inbox has no template named reactivation_september
                        in that language. Templates created in the last few
                        minutes may not have synced yet.
        '422':
          description: >-
            The edit was refused and **nothing was changed**. `details[].code`
            says why: `unsupported_channel` for an inbox that is not a WhatsApp
            Cloud API inbox, `not_editable` for a `name` or `category` in the
            body, `blank` for a missing `language`, `invalid_shape` for
            `components` that is not a list of objects, `header_not_supported`
            for a media header, `invalid_template` for a rule checked before
            Meta, and `meta_rejected` when Meta refuses the edit, for instance
            because the template's status does not allow it or the edit limit
            was reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                error:
                  code: validation_failed
                  message: The request payload is invalid.
                  details:
                    - field: template
                      code: meta_rejected
                      message: >-
                        You can only edit an approved template once every 24
                        hours. Please wait and try again later.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: >-
            WhatsApp did not answer in time, or reported a transient failure.
            **The template may have been submitted anyway.** Do not resend a
            create blindly: a name that was already submitted is refused. Check
            the template in the Cloud Chat screen first; an edit can simply be
            retried.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: service_unavailable
                  message: >-
                    WhatsApp did not answer in time. Check the template before
                    retrying: it may already have been submitted.
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:
    WhatsappTemplateUpdateRequest:
      type: object
      required:
        - template
      description: The edited template.
      properties:
        template:
          $ref: '#/components/schemas/WhatsappTemplateUpdateInput'
    WhatsappTemplateEdit:
      type: object
      description: A template whose edit Meta accepted for review.
      properties:
        id:
          type: string
          description: Meta's template id.
          example: '1157693219400316'
        name:
          type: string
          description: The template name.
          example: order_shipped
        language:
          type: string
          description: The template language.
          example: en_US
        category:
          type: string
          nullable: true
          description: >-
            The template category as last synced. `null` if the catalogue entry
            carries none.
          example: UTILITY
    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.
    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
    WhatsappTemplateUpdateInput:
      type: object
      required:
        - language
        - components
      description: >-
        The new content of an existing WhatsApp template. `name` and `category`
        are not accepted.
      properties:
        language:
          type: string
          description: >-
            Language of the template to edit, as listed by [List message
            templates](/api-reference/cloudchat/endpoints/list-message-templates).
            It selects the template when the same name exists in several
            languages and it cannot be changed.
          example: en_US
        components:
          type: array
          description: >-
            The complete set of components the template should have after the
            edit. Anything you leave out is removed.
          items:
            $ref: '#/components/schemas/WhatsappTemplateComponent'
    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
    WhatsappTemplateComponent:
      type: object
      required:
        - type
      description: One part of a template.
      properties:
        type:
          type: string
          enum:
            - HEADER
            - BODY
            - FOOTER
            - BUTTONS
          description: >-
            Which part of the template this is. At most one component of each
            type.
        format:
          type: string
          enum:
            - TEXT
          description: >-
            HEADER only. Only `TEXT` is accepted; media headers are not
            supported on this API.
        text:
          type: string
          description: >-
            The text of a HEADER, BODY or FOOTER. Variables are written `{{1}}`
            (positional) or `{{name}}` (named), never mixed. Leave it out on the
            BODY and FOOTER of an `AUTHENTICATION` template, where Meta writes
            the text.
        example:
          $ref: '#/components/schemas/WhatsappTemplateExample'
        buttons:
          type: array
          description: 'BUTTONS only: the buttons, at most 10.'
          items:
            $ref: '#/components/schemas/WhatsappTemplateButton'
        add_security_recommendation:
          type: boolean
          description: >-
            BODY of an `AUTHENTICATION` template only: add Meta's line telling
            the recipient not to share the code.
        code_expiration_minutes:
          type: integer
          description: >-
            FOOTER of an `AUTHENTICATION` template only: how long the code stays
            valid, from 1 to 90 minutes.
    WhatsappTemplateExample:
      type: object
      description: >-
        Sample values for the variables of a BODY, which Meta requires to review
        it.
      properties:
        body_text:
          type: array
          description: >-
            BODY with positional variables: one row of sample values in variable
            order, e.g. `[["Ana", "10482"]]`.
          items:
            type: array
            items:
              type: string
        body_text_named_params:
          type: array
          description: 'BODY with named variables: one sample per variable.'
          items:
            $ref: '#/components/schemas/WhatsappTemplateNamedExample'
    WhatsappTemplateButton:
      type: object
      required:
        - type
      description: One button of a BUTTONS component.
      properties:
        type:
          type: string
          enum:
            - QUICK_REPLY
            - URL
            - PHONE_NUMBER
            - COPY_CODE
            - OTP
          description: >-
            `OTP` is the only type allowed on an `AUTHENTICATION` template and
            is not allowed elsewhere. `COPY_CODE` is only allowed on `MARKETING`
            templates. At most 2 `URL`, 1 `PHONE_NUMBER` and 1 `COPY_CODE`.
        text:
          type: string
          description: >-
            The label shown on the button. Required for every type except
            `COPY_CODE`; at most 25 characters on an `OTP` button.
        url:
          type: string
          description: >-
            `URL` buttons: the address opened on tap. A `{{1}}` in it makes it
            dynamic, and then `example` is required.
        phone_number:
          type: string
          description: >-
            `PHONE_NUMBER` buttons: the number dialled on tap, in international
            format.
        otp_type:
          type: string
          enum:
            - COPY_CODE
          description: '`OTP` buttons: only `COPY_CODE` is supported.'
        example:
          type: array
          description: >-
            `URL` with a variable: one sample address. `COPY_CODE`: one sample
            code of at most 15 characters.
          items:
            type: string
    WhatsappTemplateNamedExample:
      type: object
      description: The sample value of one named variable.
      properties:
        param_name:
          type: string
          description: The variable name, without braces.
          example: customer_name
        example:
          type: string
          description: A sample value for it.
          example: Ana
  responses:
    BadRequest:
      description: >-
        The request itself is malformed, before any value is validated:


        - a body that isn't valid JSON, or one with no `canned_response`
        wrapper,

        - a `canned_response` that isn't an object (`{"canned_response":
        "text"}`),

        - `page`, `per_page`, `search` or `sort` sent as an array or a nested
        object (`?page[]=1`, `?sort[x]=y`) instead of a plain value,

        - **the `cloudchat-instance` header missing or holding a value we don't
        route,**

        - an `accountId` that is not a number — including the literal
        `{accountId}` that some API clients send when the argument is left
        unset. This one answers with the normal envelope and `error.details`
        naming `accountId`, and it is deliberately **not** a 404: a 404 would
        mean the account cannot be reached, while this means the value was never
        an account id at all, so re-read the argument instead of trying other
        numbers.


        **Two different shapes answer with 400, and the difference will bite you
        on day one.** That last case is rejected before the request reaches the
        API, so `error` is a plain **string** instead of the usual object:


        ```json

        { "error": "<human-readable message>" }

        ```


        Every other 400 uses the normal envelope, where `error` is an object
        with `code` and `message`. Reading `error.code` without checking the
        type first throws on the missing-header case — which is the most likely
        400 of your first integration. Check `typeof error === "string"` first,
        or read `error?.code` defensively.


        A 400 always means fix the request shape; it never means a value was
        rejected. Rejected values are 422.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: bad_request
              message: The request is malformed.
    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.
    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.