> ## 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} — Number settings

> PATCH /v1/numbers/{id} — retention policy, history behaviour and the Evolution GO advanced settings of one number.

# Number settings

`PATCH /v1/numbers/{id}` is where you configure a number. It is **partial**: only the fields you send change.

<Warning>
  There is no `POST /v1/numbers/{id}/settings`. If you are coming from the Evolution API, that route does not exist here and returns a 404 — as does its `syncFullHistory` field. The equivalent is `settings.historyImportEnabled` below.
</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": "I do not take calls here",
      "webhookHistoricalMessages": false
    }
  }'
```

The same `settings` block comes back on `GET /v1/numbers/{id}`.

## Fields

| Field                                | Type                                                 | Default            | Applies to                   |
| ------------------------------------ | ---------------------------------------------------- | ------------------ | ---------------------------- |
| `piiMode`                            | `STORE_INDEFINITE` \| `STORE_X_DAYS` \| `RELAY_ONLY` | `STORE_INDEFINITE` | all providers                |
| `piiRetentionDays`                   | integer 1–3650                                       | `null`             | required with `STORE_X_DAYS` |
| `settings.historyImportEnabled`      | boolean                                              | `false`            | all providers                |
| `settings.webhookHistoricalMessages` | boolean                                              | `false`            | all providers                |
| `settings.ignoreNewsletters`         | boolean                                              | `false`            | all providers                |
| `settings.alwaysOnline`              | boolean \| null                                      | `null`             | unofficial numbers           |
| `settings.rejectCall`                | boolean \| null                                      | `null`             | unofficial numbers           |
| `settings.msgRejectCall`             | string (≤1000) \| null                               | `null`             | unofficial numbers           |
| `settings.readMessages`              | boolean \| null                                      | `null`             | unofficial numbers           |
| `settings.ignoreGroups`              | boolean \| null                                      | `null`             | unofficial numbers           |
| `settings.ignoreStatus`              | boolean \| null                                      | `null`             | unofficial numbers           |

`null` on one of the unofficial-number fields means **reset to the provider default** — it does not mean `false`.

<Note>
  **`ignoreGroups` and `ignoreStatus` default to "do not send".** Group and Status
  traffic is off at the provider until a webhook asks for it: subscribing to
  `message.group` / `message.newsletter` turns groups on, and subscribing to
  [`message.stories`](/api/webhooks/events) turns Status on, for the numbers that
  webhook covers.

  Setting either field **explicitly** overrides that — an explicit `true` keeps the
  traffic off even with an active subscription, and it is not silently reverted the
  next time a webhook is saved. Set it back to `null` to return to the
  subscription-driven behaviour.
</Note>

Note the field name `ignoreGroups`. That is the dialect the unofficial provider actually speaks; `groupsIgnore` belongs to a different provider version and never reaches your number.

<Note>
  On an official Meta number the six advanced fields are accepted and stored, but nothing ever applies them. The response says so in `settings.appliesTo.advanced`, which is `"none"` for Meta numbers and `"evolution-go"` for unofficial ones.
</Note>

## History

When a number connects, WhatsApp hands the provider the device's message history, and the platform imports up to **30 days** back from the connection moment. Two independent switches control what happens to it:

* **`historyImportEnabled`** — whether that history is stored at all. **It defaults to `false`**, so a number effectively starts existing at the moment it connected. Turn it on to keep the device's previous conversations.
* **`webhookHistoricalMessages`** — whether those old messages are **delivered to your webhooks**. Off by default: every reconnect replays the history, and nothing in the payload lets your integration tell it apart from a message that just arrived. Turn it on and they arrive as `message.received` / `message.group` / `message.newsletter`; on the FREE plan they also count against your inbound allowance.

To **read** history, use [`GET /v1/messages/history`](/api/messages/history) with `startDate` / `endDate` — that is the supported path, and it filters on when each message actually happened.

## Channels

`ignoreNewsletters` decides what happens to a **WhatsApp Channel** (`@newsletter`) post that arrives at your number. It defaults to `false`, so a number that receives channels today keeps receiving them.

Set it to `true` and the post is dropped **on arrival**: it becomes no conversation, no stored message and no `message.newsletter` webhook. There is no partial mode — it is the whole class of traffic, in the chat and in the integration alike.

```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>
  **It reads like `ignoreGroups`, but it is not one of the advanced fields — and the asymmetry is the provider's, not ours.** The unofficial provider applies `ignoreGroups` itself, and the group event never leaves it. It has no equivalent gate for `@newsletter`, so a channel post always reaches the platform and the only place it can be refused is here.

  That is also why this field takes a plain `true` / `false` and never `null`: `null` means "reset to the provider default", and for channels there is no provider default to fall back to.
</Note>

An official Meta number never receives channels at all. The field is accepted and stored there, with nothing to drop.

### Ask for the history when you CREATE the number

<Warning>
  **`historyImportEnabled` has to be decided before the number connects, or not at all.** WhatsApp hands the history over in a single burst right after the connection, the flag is read per message as those arrive, and nothing can request them again. Creating the number and then sending a `PATCH` races that burst.

  `POST /v1/numbers` accepts the same `settings` block for exactly this reason:

  ```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": "Support",
      "number": "5511999999999",
      "settings": { "historyImportEnabled": true }
    }'
  ```

  The `201` echoes back the `settings` the number was created with, defaults included. `POST /v1/numbers/remote-pairing` accepts the block too — it matters most there, because whoever opens the pairing link connects on the spot.
</Warning>

<Note>
  **Changed on 2026-08-26: the default used to be `true`.** Numbers created before that date keep the value they had — nothing was rewritten. The dashboard asks the question in the connect wizard, next to the phone number.
</Note>

## Upstream push

The unofficial-number fields are stored on the number **and** pushed to its connected instances. The response reports that push in `settingsSync`:

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

The push is best-effort. An instance that is offline at the time does not fail the request — the value stays persisted and is reapplied the next time that instance is provisioned. `skipped` counts instances on a provider that has no such setting.

## Errors

| Status | `code`             | When                                                                          |
| ------ | ------------------ | ----------------------------------------------------------------------------- |
| 400    | `INVALID_SETTINGS` | a field has the wrong type, or `msgRejectCall` is longer than 1000 characters |
| 400    | `EMPTY_PATCH`      | the body carries no recognised field — this is an error, not a silent no-op   |
| 404    | —                  | the number does not belong to the authenticated tenant                        |