Atualizado em 25/10/2026
A qualidade do número na API do WhatsApp é uma nota que a Meta dá ao seu número de telefone comercial com base em como os destinatários reagiram às suas mensagens nos últimos sete dias. Ela aparece em três cores: verde (alta), amarelo (média) e vermelho (baixa). A cor não bloqueia o envio por si só, mas pesa no aumento do limite de mensagens, no throughput e, quando fica ruim por muito tempo, pode levar a restrições.
Este guia explica de onde vem a nota, como ela se relaciona com a qualidade de cada template, como consultar pela API e o que fazer para recuperar um número que caiu para amarelo ou vermelho.
O que é a classificação de qualidade do número
Segundo a documentação de envio de mensagens da Meta, a qualidade é calculada a partir de como os usuários receberam suas mensagens nos últimos sete dias, com peso maior para as mais recentes. Os sinais usados são de feedback do usuário:
- bloqueios;
- denúncias;
- conversas silenciadas;
- conversas arquivadas;
- motivos que o usuário informa ao bloquear a empresa.
A mesma página avisa que números com tráfego alto podem ter mudanças de qualidade em intervalos curtos, às vezes em minutos. Ou seja: uma campanha mal segmentada pode derrubar a nota no mesmo dia.
Na API, o campo é quality_rating e os valores possíveis estão na referência da Phone Number API:
| Cor | Valor na API | No WhatsApp Manager | O que indica |
|---|---|---|---|
| Verde | GREEN | Alta | Pouco ou nenhum feedback negativo |
| Amarelo | YELLOW | Média | Feedback negativo começando a pesar; hora de agir |
| Vermelho | RED | Baixa | Muito feedback negativo; risco de restrição |
| Sem nota | NA | Pendente | Ainda não há dados suficientes |
Qualidade do número x qualidade do template
São duas notas diferentes, e vale não confundir.
A qualidade do template é calculada para cada modelo de mensagem, com base em uso, feedback e engajamento. A página de qualidade de templates descreve os valores GREEN, YELLOW, RED e UNKNOWN (novo template, ainda sem dados). Um detalhe importante: além de bloqueios e denúncias, taxa de leitura baixa também derruba a nota do template.
Quando um template chega a RED, a Meta o pausa automaticamente, conforme a página de pausa de templates:
| Ocorrência | O que acontece |
|---|---|
| 1ª vez | Template pausado por 3 horas |
| 2ª vez | Template pausado por 6 horas |
| 3ª vez | Template desativado |
Tentativas de envio de um template pausado são rejeitadas, não são cobradas e não contam no limite de mensagens. A Meta afirma que a pausa, de início, não afeta o número; mas, se a empresa envia com frequência templates que chegam a baixa qualidade, o número pode ser afetado. Na prática, a nota do número é o reflexo acumulado das notas dos templates e das conversas.
Para entender como a categoria do template influencia a experiência do usuário, veja como a Meta classifica templates e o guia de templates da API do WhatsApp.
Como a qualidade afeta limites e throughput
A qualidade entra em três pontos documentados:
- Subir para 2.000 destinatários. Um dos caminhos para sair do limite inicial de 250 é enviar 2.000 mensagens entregues fora da janela de atendimento em 30 dias, usando templates com qualidade alta. Depois de qualquer caminho, a Meta analisa a qualidade das mensagens antes de aprovar o aumento (limites de mensagens).
- Escalonamento automático. Acima de 2.000, o limite só sobe para 10.000, 100.000 e ilimitado se a empresa estiver enviando mensagens de alta qualidade em todos os números e templates e tiver usado pelo menos metade do limite nos últimos 7 dias.
- Throughput maior. Para subir acima de 80 mensagens por segundo, o número precisa ter qualidade amarela ou melhor, além de outros requisitos (throughput).
O limite é do portfólio empresarial, compartilhado por todos os números. Um número com qualidade ruim atrapalha o crescimento de todos. Os detalhes de cada faixa estão em limite de mensagens da API do WhatsApp.
Status do número: conectado, sinalizado, restrito
Além da cor, cada número tem um status. A documentação de números comerciais diz que o status reflete a qualidade e o limite atual, e que só números com status “conectado” enviam e recebem pela API. Entre os valores da referência estão CONNECTED, FLAGGED (sinalizado) e RESTRICTED (restrito).
A Central de Ajuda da Meta, no artigo sobre a classificação de qualidade do número, descreve o fluxo do status sinalizado: quando a qualidade chega a baixa, o status passa de conectado para sinalizado. Se a qualidade voltar a média ou alta até o sétimo dia, o número volta a conectado sem mudança de limite; se não voltar, o número volta a conectado, mas o limite cai um nível. Enquanto estiver sinalizado, o limite não sobe.
Como consultar a qualidade pela API
Para ver cor e status de um número:
curl "https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>?fields=quality_rating,status,whatsapp_business_manager_messaging_limit" \
-H "Authorization: Bearer <ACCESS_TOKEN>"{
"quality_rating": "GREEN",
"status": "CONNECTED",
"whatsapp_business_manager_messaging_limit": "TIER_2K",
"id": "106540352242922"
}O campo antigo messaging_limit_tier foi descontinuado; use whatsapp_business_manager_messaging_limit.
Para a nota de um template:
curl "https://graph.facebook.com/v26.0/<TEMPLATE_ID>?fields=quality_score" \
-H "Authorization: Bearer <ACCESS_TOKEN>"Webhooks que ajudam a monitorar
| Campo do webhook | Quando dispara | Uso prático |
|---|---|---|
message_template_quality_update | A nota de um template muda | Alertar quando um template sai de GREEN |
message_template_status_update | Template pausado, desativado ou reativado | Parar a campanha que usa o template |
account_update | Violação de política e restrições na conta | Avisar o time e abrir análise |
phone_number_quality_update | Mudança de throughput do número | Acompanhar upgrades de capacidade |
Exemplo do message_template_quality_update:
{
"entry": [{
"id": "102290129340398",
"time": 1674864290,
"changes": [{
"value": {
"previous_quality_score": "GREEN",
"new_quality_score": "YELLOW",
"message_template_id": 806312974732579,
"message_template_name": "welcome_template",
"message_template_language": "en-US"
},
"field": "message_template_quality_update"
}]
}],
"object": "whatsapp_business_account"
}Como a página atual do webhook phone_number_quality_update fala só de throughput, vale também consultar quality_rating periodicamente (por exemplo, a cada hora durante campanhas) e gravar o histórico. Assim você vê a tendência antes de virar problema. Para montar o endpoint, veja webhook da API do WhatsApp.
O que derruba a qualidade
A Meta lista boas práticas na mesma página de envio de mensagens. Invertendo a lista, os erros mais comuns são:
- enviar para quem não deu opt-in (listas compradas, contatos antigos de outra finalidade);
- mensagens genéricas, pouco personalizadas ou sem utilidade clara;
- mensagens de boas-vindas abertas, do tipo “Oi, tudo bem?”, sem contexto;
- excesso de mensagens no mesmo dia;
- textos longos demais ou fora do que a pessoa espera receber;
- conteúdo que viola a Política de Mensagens do WhatsApp Business.
Ignorar pedidos de saída também pesa: quem não consegue parar de receber tende a bloquear e denunciar. Uma base bem montada começa no cadastro; veja como montar uma lista opt-in.
Como recuperar um número amarelo ou vermelho
- Pare as campanhas de marketing em andamento. Mensagens transacionais esperadas (confirmação de pedido, código de acesso) podem continuar.
- Descubra qual template puxou a nota. Consulte o
quality_scorede cada template ativo e cruze com o volume enviado nos últimos 7 dias. - Revise a segmentação. Corte contatos sem opt-in registrado, inativos há muito tempo e quem já pediu para sair.
- Reescreva o template problemático. Deixe claro quem está falando, por que a pessoa está recebendo e como sair. Lembre que editar um template o manda de volta para análise.
- Adicione um botão de saída nos templates de marketing e trate o clique como opt-out imediato.
- Reduza frequência. Espaçar os envios diminui silenciamentos e arquivamentos.
- Acompanhe por 7 dias. Como a nota usa uma janela de sete dias, a melhora aparece de forma gradual.
Se, além da cor, o número recebeu uma restrição por política, o caminho é outro: a aplicação de políticas prevê bloqueios de 1 ou 3 dias para templates, de 5, 7 ou 30 dias para qualquer mensagem e, em casos graves, bloqueio da conta. Os detalhes ficam no Business Support Home do Meta Business Suite. Veja também número bloqueado na API do WhatsApp.
Qualidade do número com a Vectalk
A Vectalk é um proxy da Cloud API oficial: os campos e webhooks são os mesmos da Meta. Para consultar a qualidade do número ligado a um token de instância, use GET /api/phone-numbers com o parâmetro fields:
curl "https://apis.vectalk.com.br/api/phone-numbers?fields=id,display_phone_number,quality_rating" \
-H "Authorization: Bearer SEU_TOKEN"O GET /api/phone-numbers/list devolve todos os números da conta com quality_rating e status. Os eventos da Meta chegam nas URLs que você registrar com POST /api/webhooks. Detalhes na documentação da Vectalk. Se você está começando, o guia da API oficial do WhatsApp explica os conceitos, e o cadastro fica em apps.vectalk.com.br/register.
Perguntas frequentes
Número com qualidade vermelha para de enviar?
Não automaticamente. A cor vermelha indica risco. O que impede o envio é o status do número (por exemplo, restrito) ou uma restrição por política. Ainda assim, vermelho é o momento de pausar campanhas e investigar.
Quanto tempo leva para a qualidade voltar ao verde?
A Meta calcula a nota com base nos últimos sete dias, com peso maior para os dias recentes. Sem novos sinais negativos, a tendência é melhorar ao longo dessa janela, mas não há prazo garantido.
A qualidade é do número ou da conta?
A cor é do número de telefone. O limite de mensagens, porém, é do portfólio empresarial e depende da qualidade em todos os números e templates. Um número ruim atrapalha o crescimento do portfólio inteiro.
Template pausado conta no limite ou é cobrado?
Não. Segundo a Meta, tentativas de envio de template pausado são rejeitadas, não são cobradas e não contam no limite de mensagens.
Mensagens com erro de entrega afetam a qualidade?
A nota vem do feedback dos usuários (bloqueios, denúncias, silenciamentos, arquivamentos). Falhas como a do erro 131049 não são feedback negativo, mas insistir em reenviar para quem não engaja tende a gerar bloqueios depois. Veja também os erros mais comuns da API.
Fontes oficiais consultadas em 25/10/2026: Envio de mensagens e qualidade, Limites de mensagens, Números de telefone comerciais, Referência da Phone Number API, Qualidade de templates, Pausa de templates, Throughput, Webhook message_template_quality_update, Webhook phone_number_quality_update, Aplicação de políticas, Sobre a classificação de qualidade do número (Central de Ajuda), Política de Mensagens do WhatsApp Business.