> ## 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 Configurações

> Atualiza as configurações de comportamento da instância (rejeição de ligações, delay de envio, presença, limpeza de conversa e confirmação de leitura automática).

A atualização é um **merge profundo** com as configurações atuais: apenas os campos enviados no corpo são alterados, os demais são preservados. Em objetos aninhados, como `message_delay` e o formato segmentado de `read_confirmation`, o merge acontece campo a campo, então enviar `{ "read_confirmation": { "chats": true } }` liga a confirmação de leitura em conversas individuais sem alterar `groups` ou `status`.

A mudança é propagada para a instância em tempo real, sem necessidade de reiniciá-la.


Use este endpoint para atualizar as configurações de comportamento da sua instância: rejeição de ligações, delay antes do envio de mensagens, presença (online/digitando), limpeza de conversa e confirmação de leitura automática.

### Atualize só o que precisar

Você não precisa enviar todas as configurações a cada chamada. Envie apenas o que quer mudar e tudo o que ficar de fora continua exatamente como está.

Isso vale até para configurações com subcampos, como `message_delay` e o formato segmentado de `read_confirmation`: cada subcampo que você não enviar também fica como estava. Por exemplo, enviando apenas:

```json theme={null}
{
  "settings": {
    "read_confirmation": {
      "chats": true
    }
  }
}
```

Você liga a confirmação de leitura automática só para conversas individuais, e `groups` e `status` seguem do jeito que estavam.

### Configurações disponíveis

* **`call_rejection`**: define se ligações recebidas devem ser rejeitadas automaticamente. Aceita `all` (rejeita todas), `none` (não rejeita nenhuma), `video_only` (rejeita apenas chamadas de vídeo) ou `audio_only` (rejeita apenas chamadas de áudio).
* **`message_delay`**: adiciona um atraso proposital antes do envio de cada mensagem, útil para simular um comportamento mais humano. É um objeto com `enabled` (liga/desliga o delay), `min` e `max` (limites em segundos, o tempo real é sorteado dentro desse intervalo).
* **`delay_per_word`**: quando ligado, o delay antes do envio passa a ser calculado com base na quantidade de palavras da mensagem, até um teto de 10 segundos. Quando `message_delay` está configurado, ele tem prioridade e `delay_per_word` é ignorado.
* **`presence_behavior`**: controla quando a instância aparece como "online" para os contatos. `only_composing` mostra "online" apenas durante o envio da mensagem (recomendado), `always_online` mantém a instância sempre online e `always_offline` evita aparecer online exceto quando necessário para o envio.
* **`delete_chat_after_sent`**: quando ligado, limpa a conversa no aparelho logo depois do envio da mensagem, para evitar acúmulo de histórico no dispositivo conectado.
* **`read_confirmation`**: controla a confirmação de leitura automática das mensagens recebidas. Aceita os valores `never` (nunca confirma) ou `always` (sempre confirma), ou um objeto segmentado por tipo de conversa com os campos `chats`, `groups` e `status`, cada um booleano e independente. Quando o segmento `status` está ligado, os status publicados pelos seus contatos são marcados como vistos assim que recebidos. Mensagens enviadas pela própria instância, listas de transmissão e publicações de canais nunca recebem confirmação automática, independentemente dessa configuração.

Se você precisa de controle fino sobre o momento exato da confirmação de leitura, por exemplo, marcar como lida só depois que um atendente responder, desligue a confirmação automática do segmento desejado e use o endpoint de [leitura sob demanda](/pt-BR/v1/api-reference/messages/read-message) para confirmar mensagem por mensagem.

A atualização é aplicada à instância em tempo real, sem necessidade de reiniciá-la.


## OpenAPI

````yaml PATCH /wa/instances/{instance_id}/settings
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}/settings:
    patch:
      tags: []
      summary: Atualização de Configurações
      description: >
        Atualiza as configurações de comportamento da instância (rejeição de
        ligações, delay de envio, presença, limpeza de conversa e confirmação de
        leitura automática).


        A atualização é um **merge profundo** com as configurações atuais:
        apenas os campos enviados no corpo são alterados, os demais são
        preservados. Em objetos aninhados, como `message_delay` e o formato
        segmentado de `read_confirmation`, o merge acontece campo a campo, então
        enviar `{ "read_confirmation": { "chats": true } }` liga a confirmação
        de leitura em conversas individuais sem alterar `groups` ou `status`.


        A mudança é propagada para a instância em tempo real, sem necessidade de
        reiniciá-la.
      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:
                settings:
                  $ref: '#/components/schemas/InstanceSettings'
              example:
                settings:
                  read_confirmation:
                    chats: true
      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_enum_value
                        message:
                          type: string
                          description: Mensagem de erro
                          example: >-
                            Invalid enum value. Expected 'all' | 'none' |
                            'video_only' | 'audio_only'
                        path:
                          type: string
                          description: Caminho do campo inválido no corpo da requisição
                          example: settings.call_rejection
        '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.
        '412':
          description: >-
            A instância precisa ser atualizada para suportar a configuração
            enviada
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: instance_update_required
                        message:
                          type: string
                          example: >-
                            This instance is running an older version that does
                            not support this feature. Power the instance off and
                            on to update it, or contact support for help.
      deprecated: false
      security:
        - bearer: []
components:
  schemas:
    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.
    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
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````