Skip to main content

​
Configuração do número

PATCH /v1/numbers/{id} é onde se configura um número. Ele é parcial: só o que vier no corpo muda.
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.
O mesmo bloco settings volta em GET /v1/numbers/{id}.

​
Campos

null num dos campos de número não-oficial significa voltar ao padrão do provedor — não significa false.
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 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.
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.
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.

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

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

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