Conceitos do WhatsApp
Metade dos erros da API não é erro de código: é uma regra da Meta que a integração esbarrou sem saber que existia. São cinco, e entender as cinco evita quase todo problema de envio.
1. A janela de 24 horas (link para esta seção)
Quando alguém te manda uma mensagem, abre uma janela de 24 horas. Dentro dela, você responde o que quiser: texto, imagem, áudio, documento. Fora dela, só template aprovado.
A janela conta a partir da última mensagem que o cliente enviou, não da sua resposta. Se ele escreve de novo, ela reinicia. Se ele some por 24h, ela fecha, e aí você precisa de template mesmo que a conversa estivesse no meio.
outside_24h_window. A pessoa testa o envio de manhã, funciona, roda a campanha à noite e todas falham: a janela fechou entre uma coisa e outra.Como saber se está aberta
No painel, o cabeçalho da conversa mostra "24h aberta" ou "24h fechada". Pela API, a resposta honesta é: tente o texto e trate o erro. Não existe endpoint que pergunte isso à Meta, e manter esse relógio do seu lado é fonte garantida de divergência.
2. Template aprovado (link para esta seção)
Template é uma mensagem pré-escrita e aprovada pela Meta. É o único jeito de falar com alguém fora da janela de 24h. Você cria no painel, em Templates, a Meta analisa (costuma levar de minutos a algumas horas) e depois você dispara pela API pelo nome dele.
As partes variáveis vão em {{1}}, {{2}} e assim por diante. O texto fixo não muda: se quiser mudar a frase, cria outro template e espera aprovar de novo.
As três categorias
| Categoria | Para que serve | Cuidado |
|---|---|---|
| Marketing | Promoção, novidade, reativação. | A mais cara e a mais fiscalizada. Reclamação aqui derruba a qualidade do número rápido. |
| Utilidade | Confirmação de pedido, aviso de entrega, cobrança, agendamento. | Precisa ser sobre algo que a pessoa pediu ou contratou. Promoção disfarçada de utilidade é reprovada. |
| Autenticação | Código de verificação, só isso. | Formato restrito. Não dá para pendurar recado junto do código. |
Por que reprova
Os motivos que mais aparecem: variável no começo ou no fim do texto sem nada em volta (a Meta não consegue avaliar o que vai ali), texto que promete algo que a marca não pode cumprir, categoria errada, e erro de digitação grosseiro. Reprovado, dá para corrigir e reenviar.
3. Opt-in (consentimento) (link para esta seção)
Antes de mandar mensagem para alguém, essa pessoa precisa ter concordado em receber. A Meta exige, e a LGPD também. O consentimento pode vir de um formulário no seu site, de uma caixa marcada no checkout, de uma conversa em que a pessoa pediu para ser avisada, ou do próprio WhatsApp.
O que a Meta espera de você é conseguir provar: quando, onde e como a pessoa aceitou. No painel isso fica registrado por contato, com data e origem, e é o que você mostra se alguém questionar.
Quem pede para sair tem que sair. Mantenha uma lista de supressão e respeite antes de qualquer disparo, inclusive nas campanhas por etiqueta.
4. Qualidade do número (link para esta seção)
A Meta dá uma nota ao seu número, de verde a vermelho, baseada em como as pessoas reagem às suas mensagens: bloqueio, denúncia de spam e falta de resposta puxam para baixo; conversa de volta puxa para cima.
| Nota | O que significa |
|---|---|
| Verde (alta) | Tudo certo. É onde o número deve ficar. |
| Amarelo (média) | Sinal de alerta. Reveja quem está recebendo e o que está sendo enviado. |
| Vermelho (baixa) | Risco real de limitação. Pare a campanha e olhe a lista antes de continuar. |
Qualidade baixa por tempo suficiente vira limitação: o número passa a poder falar com menos contatos por dia, ou entra em revisão. A nota aparece no painel, em Configurações, e mudanças chegam como alerta.
5. Limite diário (link para esta seção)
Não é limite de mensagens, é limite de contatos diferentes que você inicia conversa por dia. Responder quem te chamou não consome esse limite.
Um número novo começa em 250 contatos por dia e sobe (1.000, 10.000, 100.000, ilimitado) conforme você envia com qualidade alta. É automático, não se pede. Cair de qualidade faz descer também.
Bônus: coexistência (link para esta seção)
Dá para usar o mesmo número no aplicativo do celular e na API ao mesmo tempo. A equipe segue atendendo pelo celular, e o que ela envia por lá aparece no painel e no seu sistema.
Duas consequências que pegam quem integra: mensagem enviada pelo aplicativo não recebe status de entrega (a Meta não acompanha essas), então elas ficam com um selo só; e o histórico anterior à conexão não vem junto, o que chega é o que acontece a partir dali.
Como isso vira erro na API (link para esta seção)
| Conceito | Erro que aparece |
|---|---|
| Janela de 24h | outside_24h_window |
| Template | invalid_template |
| Qualidade e limite diário | delivery_limited |
| Conta em revisão | account_restricted |
| Número sem WhatsApp | recipient_unreachable |
A lista completa, com o que fazer e quais valem repetir, está em Erros e limites.