Skip to main content

​
Number settings

PATCH /v1/numbers/{id} is where you configure a number. It is partial: only the fields you send change.
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.
The same settings block comes back on GET /v1/numbers/{id}.

​
Fields

null on one of the unofficial-number fields means reset to the provider default — it does not mean false.
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 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 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.
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.

​
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 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.
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.
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

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:
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.
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.

​
Upstream push

The unofficial-number fields are stored on the number and pushed to its connected instances. The response reports that push in settingsSync:
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