O webhook phone_number_quality_update
phone_number_quality_update comunica alterações no throughput e no limite de mensagens de um número. Em 2026, não transporta a classificação de qualidade verde, amarela ou vermelha, apesar do nome; essa classificação tem de ser consultada diretamente no número.
O ano em que o conteúdo deste campo deixou de incluir a classificação por cor.
Classificações de qualidade possíveis: verde, amarela e vermelha, nenhuma das quais chega aqui.
O erro devolvido por um número quando a limitação por qualidade entra em vigor.
O que contém realmente este webhook?
Informação sobre o throughput e o limite de mensagens, entregue como um valor de evento e campos com o limite atual.
Na prática, o conteúdo indica que a capacidade de um número mudou: passou para outro escalão de mensagens ou o seu nível de throughput foi ajustado. É útil registar estas alterações porque mudam o que uma integração pode fazer e porque uma descida de escalão é um sinal precoce.
O que não está incluído, apesar do nome do campo, é a classificação de qualidade. Um processador baseado em documentação antiga procurará GREEN, YELLOW ou RED aqui e não encontrará nada, concluindo depois que a qualidade nunca muda.
De onde vem então a classificação por cor?
Da leitura direta do número, segundo um calendário definido.
O campo quality_rating está no objeto do número de telefone na Graph API e tem de ser consultado periodicamente, em vez de se aguardar um evento. Por isso, a monitorização correta de uma ligação precisa tanto de um processo de consulta como de um recetor de webhook: os dois transportam informações diferentes e nenhum é suficiente por si só.
É também por isso que uma descida de qualidade passa despercebida na maioria das integrações. Nada a envia automaticamente, a aplicação WhatsApp Business não mostra qualquer indicação e, quando surge o erro 131048, os envios afetados já falharam.
Erros comuns
- Procurar GREEN, YELLOW ou RED neste payload. Em 2026, não estão lá.
- Criar a monitorização apenas com webhooks. A classificação de qualidade tem de ser consultada.
- Ignorar uma descida de escalão. É normalmente o primeiro sinal visível de um problema.
A EasyCoexistence consulta a classificação de qualidade, o escalão de mensagens e o nível de throughput em todos os números ligados e regista cada verificação, para que uma descida seja visível antes de custar um envio.
Perguntas frequentes
Porque se chama o campo assim, se é sobre qualidade?
O nome é anterior à alteração. Manteve-se enquanto o conteúdo mudou, e é por isso que este campo induz tantas pessoas em erro.
Com que frequência deve ser consultada a classificação?
Com frequência suficiente para detetar uma descida antes de se tornar numa limitação. Fazemos consultas segundo um calendário, não a pedido.
A aplicação mostra a classificação?
Não. A aplicação WhatsApp Business no telemóvel não mostra qualquer informação sobre ela.
O 131048 está relacionado?
Sim. É o erro que um número começa a devolver quando uma classificação baixa resulta numa limitação.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em