O webhook phone_number_quality_update
O phone_number_quality_update informa mudanças de throughput e de limite de mensagens de um número. Em 2026 ele não carrega a classificação de qualidade verde, amarela ou vermelha, apesar do nome, e essa classificação precisa ser consultada no número.
O ano em que o conteúdo deste campo deixou de ser a classificação por cor.
Classificações de qualidade que um número pode ter: verde, amarela e vermelha, e nenhuma chega aqui.
O erro que um número devolve depois que a limitação por qualidade entra em vigor.
O que este webhook realmente contém?
Informação de throughput e de limite de mensagens, entregue como um valor de evento mais campos que carregam o limite atual.
O conteúdo prático é que a capacidade de um número mudou: ele foi para outra faixa de mensagens, ou o nível de throughput dele foi ajustado. Esses dados valem ser registrados porque mudam o que uma integração consegue fazer, e porque uma faixa que desce é um sinal precoce.
O que não está nele, apesar do nome do campo, é a classificação de qualidade. Um handler escrito com base em documentação antiga vai procurar GREEN, YELLOW ou RED aqui, não vai achar nada, e então vai concluir que a qualidade nunca muda.
De onde vem a classificação por cor, então?
De ler o número de telefone diretamente, em uma rotina periódica.
O campo quality_rating fica no objeto do número de telefone na Graph API, e ele precisa ser consultado em vez de esperado. É por isso que monitorar uma conexão direito exige um poller além de um receptor de webhook: os dois carregam coisas diferentes e nenhum dos dois basta sozinho.
É também por isso que uma queda de qualidade é invisível para a maioria das integrações. Nada empurra essa informação, o app do WhatsApp Business não dá nenhum sinal dela, e quando ela produz o erro 131048 os envios afetados já falharam.
Erros comuns
- Procurar GREEN, YELLOW ou RED neste payload. Em 2026 isso não está lá.
- Montar o monitoramento só com webhooks. A classificação de qualidade precisa ser consultada.
- Ignorar uma queda de faixa. Costuma ser o primeiro sinal visível de um problema.
A EasyCoexistence consulta a classificação de qualidade, a faixa de mensagens e o nível de throughput em cada número conectado e registra cada checagem, então uma queda fica visível antes de custar um envio.
Perguntas frequentes
Por que o campo tem nome de qualidade, então?
Ele é anterior à mudança. O nome ficou enquanto o conteúdo mudou, e é por isso que isso pega as pessoas de surpresa.
Com que frequência a classificação deve ser consultada?
Com frequência suficiente para pegar a queda antes de virar limite. Consultamos em uma rotina periódica, e não sob demanda.
O app mostra a classificação?
Não. Nada sobre ela aparece no app do WhatsApp Business no celular.
O 131048 tem relação?
Sim. É o erro que um número passa a devolver quando uma classificação baixa vira limitação.
Continue lendo
Pronto para começar?
Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.
Começar teste grátisVerificado em