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

# Atualizando a Instância

> Atualiza os dados da instância na plataforma, como o nome e os metadados.


Use este endpoint para atualizar os dados da própria instância na plataforma: o nome (`name`), os metadados (`metadata`) e o identificador de pesquisa (`lookup_key`).

Ele não altera o perfil do WhatsApp (nome de exibição, foto, descrição). Para isso, use o endpoint de [atualização de perfil](/pt-BR/v1/api-reference/instance/update-profile). As configurações de comportamento têm o seu próprio endpoint de [atualização de configurações](/pt-BR/v1/api-reference/instance/update-settings).

### Atualize só o que precisar

Você não precisa enviar todos os campos a cada chamada. Envie apenas o que quer mudar e tudo o que ficar de fora continua exatamente como está.

Nenhum campo aceita `null`: `name` é sempre um texto, e os valores de `metadata` são sempre um texto ou um número. Para "limpar" um valor, veja a regra da string vazia logo abaixo.

### Como o `metadata` é atualizado

O `metadata` também é atualizado de forma parcial: as chaves enviadas são alteradas e todas as outras permanecem intactas. Não é necessário (nem recomendado) reenviar o objeto inteiro.

* Para **alterar ou criar** uma chave, envie a chave com o novo valor.
* Para **manter** uma chave como está, simplesmente não a envie.
* Para **limpar** o valor de uma chave, envie uma string vazia `""`.

Por exemplo, se a instância tem os metadados `customer_id`, `customer_name` e `campaign`, a requisição abaixo altera `customer_id`, limpa `campaign` e mantém `customer_name` intacto:

```json theme={null}
{
  "metadata": {
    "customer_id": "789012",
    "campaign": ""
  }
}
```

### Chaves reservadas `wa_`

Chaves de metadata iniciadas com `wa_` são gerenciadas automaticamente pela plataforma e funcionam como somente leitura: se você enviá-las na requisição, elas são ignoradas e os valores originais são preservados. Use outros nomes para as suas próprias chaves.


## OpenAPI

````yaml PATCH /wa/instances/{instance_id}
openapi: 3.1.0
info:
  title: Zapster API
  description: ''
  version: 1.0.0
servers:
  - url: https://api.zapsterapi.com/v1
    description: Produção
security: []
tags: []
paths:
  /wa/instances/{instance_id}:
    patch:
      tags: []
      summary: Atualização da Instância
      description: >
        Atualiza os dados da instância na plataforma, como o nome e os
        metadados.
      parameters:
        - name: instance_id
          in: path
          description: ID da instância.
          required: true
          example: ozj35qv418rpmlrb
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Minha Instância
                  description: >
                    Nome da instância na plataforma. Sempre um texto, nunca
                    `null`.
                metadata:
                  type: object
                  description: >
                    Metadados armazenados como chave e valor. Cada chave é um
                    texto e o valor pode ser um texto ou um número, nunca
                    `null`.


                    A atualização é parcial: apenas as chaves enviadas são
                    alteradas e as demais permanecem como estão. Para limpar o
                    valor de uma chave, envie uma string vazia `""`.


                    Chaves iniciadas com `wa_` são gerenciadas pela plataforma e
                    somente leitura: se enviadas, são ignoradas.
                  additionalProperties:
                    oneOf:
                      - type: string
                      - type: number
                lookup_key:
                  type: string
                  maxLength: 32
                  example: ins_8j7wlxmpjlixx9mux5
                  description: >
                    Identificador único opcional de pesquisa que permite
                    associar sua instância a uma estrutura de dados específica.
                    A Zapster API não utiliza esse dado internamente; ele serve
                    exclusivamente para facilitar consultas na API.
              example:
                name: Loja Centro
                metadata:
                  customer_id: '123456'
                  campaign: ''
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '400':
          description: Erro de validação no corpo da requisição
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Código do erro de validação
                          example: invalid_type
                        message:
                          type: string
                          description: Mensagem de erro
                          example: Expected string, received null
                        path:
                          type: string
                          description: Caminho do campo inválido no corpo da requisição
                          example: name
        '404':
          description: Instância não encontrada ou não pertence ao usuário
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: instance_not_found
                        message:
                          type: string
                          example: Instance not found.
      deprecated: false
      security:
        - bearer: []
components:
  schemas:
    Instance:
      type: object
      description: Estrutura de uma instância registrada na API.
      properties:
        created_at:
          type: string
          format: date-time
          description: Data e hora de criação da instância no formato ISO 8601.
          example: '2024-10-03T21:56:22.620Z'
        id:
          type: string
          description: Identificador único da instância.
          example: xy9rexnkwobmgg3tehgvs
        metadata:
          type: object
          description: Metadados adicionais armazenados como chave e valor.
          additionalProperties:
            oneOf:
              - type: string
              - type: number
          example:
            customer_id: '123456'
            customer_name: Joãozinho
            phone_number: '+5587989075555'
        connection_type:
          type: string
          enum:
            - unofficial
            - waba
          description: |
            Tipo de conexão da instância:
            - `unofficial`: conexão via QR code (padrão)
            - `waba`: conexão via API oficial do WhatsApp (Cloud API da Meta)
          example: unofficial
        name:
          type: string
          description: Nome da instância.
          example: MyNewInstance2
        owner:
          type: object
          description: Informações sobre o proprietário da instância.
          properties:
            display_name:
              type: string
              nullable: true
              description: Nome de exibição do proprietário. Pode ser nulo.
              example: null
            id:
              type: string
              format: uuid
              description: Identificador único do proprietário.
          required:
            - id
        qrcode:
          type: string
          nullable: true
          description: QR Code da instância, caso disponível.
          example: null
        settings:
          $ref: '#/components/schemas/InstanceSettings'
        status:
          type: string
          enum:
            - connected
            - disconnected
            - offline
          description: Status atual da instância
          example: disconnected
        webhooks:
          type: array
          description: Lista de webhooks configurados para esta instância.
          items:
            type: object
            description: Configuração de um webhook associado à instância.
            properties:
              enabled:
                type: boolean
                description: Indica se o webhook está ativado.
                example: true
              events:
                type: array
                description: Lista de eventos que acionam este webhook.
                items:
                  type: string
                  enum:
                    - group.created
                    - group.participants_added
                    - group.participants_demoted
                    - group.participants_promoted
                    - group.participants_removed
                    - group.updated
                    - instance.connected
                    - instance.disconnected
                    - instance.forbidden
                    - instance.mentioned
                    - instance.qrcode
                    - message.deleted
                    - message.delivered
                    - message.failed
                    - message.flow_reply
                    - message.pinned
                    - message.reaction
                    - message.read
                    - message.received
                    - message.sent
                    - message.unpinned
                    - poll.created
                    - poll.deleted
                    - poll.updated
                    - status.reply
                example:
                  - message.received
              id:
                type: string
                description: Identificador único do webhook.
                example: 2nenz69l0xbf0m3uu9tfo
              name:
                type: string
                description: Nome do webhook configurado.
                example: Webhook Name
              test_mode:
                type: boolean
                description: Indica se o webhook está em modo de teste.
                example: false
              test_url:
                type: string
                nullable: true
                description: URL de teste do webhook, se disponível.
                example: null
              url:
                type: string
                format: uri
                description: URL do webhook para onde os eventos serão enviados.
                example: https://webhook.mydomain.com
            required:
              - enabled
              - events
              - id
              - name
              - test_mode
              - url
        lookup_key:
          type: string
          description: Identificador de pesquisa criado anteriormente.
          example: ins_8j7wlxmpjlixx9mux5
      required:
        - created_at
        - id
        - metadata
        - name
        - owner
        - settings
        - status
        - webhooks
    InstanceSettings:
      type: object
      description: |
        Objeto **opcional** de configurações da sua instância.
      properties:
        call_rejection:
          type: string
          description: |
            Define o comportarmento de rejeição de ligações.

            - `all` - Irá rejeitar todas ligações
            - `none` - Não irá rejeitar ligações.
            - `video_only` - Irá rejeitar apenas ligações de **vídeo**.
            - `audio_only` - Irá rejeitar apenas ligações de **audio**.
          enum:
            - all
            - none
            - video_only
            - audio_only
        delay_per_word:
          type: boolean
          description: >
            Define se o delay antes de enviar a mensagem deve ser baseado na
            quantidade de palavras.


            ℹ️ Limitado a no máximo **10 segundos** de espera.
        delete_chat_after_sent:
          type: boolean
          description: >
            ⚠️ *Esta função não está funcionando adequadamente, estamos
            trabalhando para regulariza-la.*


            Define se o chat/conversa deve ser limpo depois do envio da
            mensagem. Isso garante que o dispositivo fique acumulando mensagens
            a ponto de muitas vezes travar o dispositivo que foi conectado.
        message_delay:
          type: object
          description: >
            Define a configuração de delay antes do envio da mensagem, se
            configurado `delay_per_word` é ignorado. O tempo é gerado
            randomicamente entre os limites configurado (`min` e `max`).
          properties:
            enabled:
              type: boolean
              default: true
            max:
              type: integer
              description: >-
                Máximo de tempo em segundos que deve ser esperado antes do envio
                da mensagem.
              default: 10
            min:
              type: integer
              description: >-
                Mínimo de tempo em segundos que deve ser esperado antes do envio
                da mensagem.
              default: 1
        presence_behavior:
          type: string
          description: >
            Define o comportamento da presença (Online, Digitando...,
            Gravando...) da sua instância.


            - `only_composing` - Aparecerá "Online" apenas durante o envio da
            mensagem. (**recomendado**)

            - `always_online` - Aparecerá sempre online

            - `always_offline` - Nunca aparecerá "Online" exceto quando
            necessário durante os envios (por boas práticas)
          enum:
            - only_composing
            - always_online
            - always_offline
        read_confirmation:
          description: >
            Define o comportamento de "confirmação de leitura", ou seja, a
            leitura automática das mensagens recebidas.


            Aceita os valores clássicos em texto ou um objeto segmentado por
            tipo de conversa:


            - `never` - Nunca confirma a leitura (equivale a todos os segmentos
            desligados)

            - `always` - Sempre confirma a leitura (equivale a todos os
            segmentos ligados)

            - Objeto com os campos `chats`, `groups` e `status` - Controla cada
            segmento de forma independente


            No formato de objeto, cada campo é booleano e o padrão é `false`:


            - `chats` - Conversas individuais

            - `groups` - Grupos

            - `status` - Status publicados pelos seus contatos (com este
            segmento ligado, os status recebidos são marcados como vistos)


            Mensagens enviadas pela própria instância, listas de transmissão e
            publicações de canais nunca recebem confirmação de leitura
            automática.
          oneOf:
            - type: string
              enum:
                - never
                - always
            - type: object
              properties:
                chats:
                  type: boolean
                  default: false
                  description: >-
                    Confirma a leitura de mensagens recebidas em conversas
                    individuais.
                groups:
                  type: boolean
                  default: false
                  description: Confirma a leitura de mensagens recebidas em grupos.
                status:
                  type: boolean
                  default: false
                  description: Marca como vistos os status publicados pelos seus contatos.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````