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

# PATCH /v1/numbers/{id} — Configuração do número

> PATCH /v1/numbers/{id} — política de retenção, comportamento do histórico e os advanced settings do Evolution GO de um número.

# Configuração do número

`PATCH /v1/numbers/{id}` é onde se configura um número. Ele é **parcial**: só o que vier no corpo muda.

<Warning>
  Não existe `POST /v1/numbers/{id}/settings`. Se você vem da Evolution API, essa rota não existe aqui e devolve 404 — assim como o campo `syncFullHistory`. O equivalente é o `settings.historyImportEnabled` abaixo.
</Warning>

```bash theme={null}
curl -X PATCH https://pilotstatus.com.br/v1/numbers/num_01HZX... \
  -H "x-api-key: $PILOT_STATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "rejectCall": true,
      "msgRejectCall": "Não atendo por aqui",
      "webhookHistoricalMessages": false
    }
  }'
```

O mesmo bloco `settings` volta em `GET /v1/numbers/{id}`.

## Campos

| Campo                                | Tipo                                                 | Padrão             | Vale para                      |
| ------------------------------------ | ---------------------------------------------------- | ------------------ | ------------------------------ |
| `piiMode`                            | `STORE_INDEFINITE` \| `STORE_X_DAYS` \| `RELAY_ONLY` | `STORE_INDEFINITE` | todos os providers             |
| `piiRetentionDays`                   | inteiro 1–3650                                       | `null`             | obrigatório com `STORE_X_DAYS` |
| `settings.historyImportEnabled`      | booleano                                             | `false`            | todos os providers             |
| `settings.webhookHistoricalMessages` | booleano                                             | `false`            | todos os providers             |
| `settings.ignoreNewsletters`         | booleano                                             | `false`            | todos os providers             |
| `settings.alwaysOnline`              | booleano \| null                                     | `null`             | números não-oficiais           |
| `settings.rejectCall`                | booleano \| null                                     | `null`             | números não-oficiais           |
| `settings.msgRejectCall`             | string (≤1000) \| null                               | `null`             | números não-oficiais           |
| `settings.readMessages`              | booleano \| null                                     | `null`             | números não-oficiais           |
| `settings.ignoreGroups`              | booleano \| null                                     | `null`             | números não-oficiais           |
| `settings.ignoreStatus`              | booleano \| null                                     | `null`             | números não-oficiais           |

`null` num dos campos de número não-oficial significa **voltar ao padrão do provedor** — não significa `false`.

<Note>
  **`ignoreGroups` e `ignoreStatus` vêm como "não enviar".** O tráfego de grupo e de
  Status fica desligado no provedor até que algum webhook peça: assinar
  `message.group` / `message.newsletter` liga grupo, e assinar
  [`message.stories`](/pt-BR/api/webhooks/events) liga Status, para os números que
  aquele webhook cobre.

  Definir qualquer um dos dois **explicitamente** vence essa derivação — um `true`
  explícito mantém o tráfego desligado mesmo com assinatura ativa, e não é revertido
  em silêncio quando um webhook é salvo. Volte para `null` para retomar o
  comportamento dirigido por assinatura.
</Note>

Repare no nome `ignoreGroups`. É o dialeto que o provedor não-oficial realmente fala; `groupsIgnore` pertence a outra versão de provedor e nunca chega ao seu número.

<Note>
  Em número oficial da Meta os seis campos avançados são aceitos e guardados, mas nada os aplica. A resposta diz isso em `settings.appliesTo.advanced`, que vem `"none"` para número Meta e `"evolution-go"` para não-oficial.
</Note>

## Histórico

Quando um número conecta, o WhatsApp entrega ao provedor o histórico do aparelho, e a plataforma importa até **30 dias** para trás a partir do momento da conexão. Dois interruptores independentes decidem o que fazer com ele:

* **`historyImportEnabled`** — se esse histórico é armazenado. **O padrão é `false`**, então o número passa a existir, na prática, a partir do momento em que conectou. Ligue para guardar as conversas anteriores do aparelho.
* **`webhookHistoricalMessages`** — se essas mensagens antigas são **entregues nos seus webhooks**. Desligado por padrão: cada reconexão replica o histórico, e nada no payload permite à sua integração distinguir isso de uma mensagem que acabou de chegar. Ligado, elas chegam como `message.received` / `message.group` / `message.newsletter`; no plano FREE também contam na cota de inbound.

Para **ler** o histórico, use [`GET /v1/messages/history`](/pt-BR/api/messages/history) com `startDate` / `endDate` — é o caminho suportado, e ele filtra por quando cada mensagem realmente aconteceu.

## Canais

`ignoreNewsletters` decide o que acontece com a publicação de **Canal do WhatsApp** (`@newsletter`) que chega no seu número. O padrão é `false`, então um número que hoje recebe canal continua recebendo.

Com `true`, a publicação é descartada **na entrada**: não vira conversa, não vira mensagem guardada e não dispara `message.newsletter`. Não há modo parcial — é a classe inteira de tráfego, no chat e na integração.

```bash theme={null}
curl -X PATCH https://pilotstatus.com.br/v1/numbers/num_01HZX... \
  -H "x-api-key: $PILOT_STATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "ignoreNewsletters": true } }'
```

<Note>
  **Parece o `ignoreGroups`, mas não é um dos campos avançados — e a assimetria é do provedor, não nossa.** O provedor não-oficial aplica o `ignoreGroups` ele mesmo, e o evento de grupo nunca sai de lá. Para `@newsletter` ele não tem gate equivalente, então a publicação sempre chega na plataforma e o único lugar onde dá para recusá-la é aqui.

  É também por isso que este campo aceita só `true` / `false`, nunca `null`: `null` quer dizer "voltar ao padrão do provedor", e para canal não existe padrão do provedor para onde voltar.
</Note>

Número oficial da Meta nunca recebe canal. Lá o campo é aceito e guardado, sem nada para descartar.

### Peça o histórico na CRIAÇÃO do número

<Warning>
  **O `historyImportEnabled` tem de ser decidido antes de o número conectar, ou não é decidido.** O WhatsApp entrega o histórico numa rajada única logo após a conexão, a flag é lida mensagem a mensagem conforme elas chegam, e nada consegue pedir de novo. Criar o número e depois mandar um `PATCH` corre contra essa rajada.

  O `POST /v1/numbers` aceita o mesmo bloco `settings` exatamente por isso:

  ```bash theme={null}
  curl -X POST https://pilotstatus.com.br/v1/numbers \
    -H "x-api-key: $PILOT_STATUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Suporte",
      "number": "5511999999999",
      "settings": { "historyImportEnabled": true }
    }'
  ```

  O `201` devolve o bloco `settings` com que o número foi criado, defaults inclusive. O `POST /v1/numbers/remote-pairing` também aceita — e ali importa ainda mais, porque quem abre o link de pareamento conecta na hora.
</Warning>

<Note>
  **Mudou em 26/08/2026: o padrão era `true`.** Números criados antes dessa data mantêm o valor que tinham — nada foi reescrito. No painel, a pergunta aparece no assistente de conexão, ao lado do telefone.
</Note>

## Push para a instância

Os campos de número não-oficial são gravados no número **e** empurrados para as instâncias conectadas. A resposta reporta esse push em `settingsSync`:

```json theme={null}
{ "settingsSync": { "applied": 1, "failed": 0, "skipped": 0 } }
```

O push é best-effort. Uma instância fora do ar na hora não faz a requisição falhar — o valor fica persistido e é reaplicado no próximo provisionamento daquela instância. `skipped` conta as instâncias num provedor que não tem essa configuração.

## Erros

| Status | `code`             | Quando                                                                          |
| ------ | ------------------ | ------------------------------------------------------------------------------- |
| 400    | `INVALID_SETTINGS` | um campo veio com o tipo errado, ou `msgRejectCall` passou de 1000 caracteres   |
| 400    | `EMPTY_PATCH`      | o corpo não trouxe nenhum campo reconhecido — isso é erro, não no-op silencioso |
| 404    | —                  | o número não pertence ao tenant autenticado                                     |