Conceitos do WhatsApp
Entenda a janela de atendimento, os templates e os limites que afetam sua integração.
1. A janela de 24 horas (link para esta seção)
Uma mensagem do contato abre a janela de 24 horas para o número da empresa que a recebeu. Nesta API, você pode responder com texto livre ou template. Fora da janela, use um template aprovado.
O prazo conta a partir da última mensagem recebida do contato. Uma nova mensagem dele renova a janela; respostas da empresa não alteram o prazo.
outside_24h_windowmesmo quando uma consulta anterior indicava janela aberta.Como saber se está aberta
No painel, o cabeçalho da conversa mostra "24h aberta" ou "24h fechada". Pela API, use GET /public/v1/window/{to}. A consulta usa as mensagens recebidas que foram registradas pela plataforma. A Meta confirma a permissão quando a mensagem é enviada, então trate também o erro de janela vencida.
2. Template aprovado (link para esta seção)
Template é um modelo de mensagem aprovado pela Meta. Crie o modelo no painel, em Templates, e aguarde a aprovação. Para enviá-lo pela API, informe o nome, o idioma e os campos exigidos pelo cadastro.
As partes variáveis podem ser posicionais, como {{1}}, ou nomeadas, como {{pedido}}. Alterações no conteúdo dependem das regras de edição e revisão da Meta.
As três categorias
| Categoria | Para que serve | Cuidado |
|---|---|---|
| Marketing | Promoção, novidade, reativação. | A mensagem precisa ser esperada pelo destinatário. Confira o consentimento e as regras vigentes. |
| Utilidade | Confirmação de pedido, aviso de entrega, cobrança, agendamento. | Deve estar relacionado a uma solicitação ou transação do destinatário. Conteúdo promocional pode ser reclassificado. |
| Autenticação | Código de verificação de acesso ou de uma operação. | Use o formato próprio de autenticação e valide o código no seu sistema. |
Se o modelo for rejeitado
Consulte o motivo informado pela Meta no painel de Templates. Revise a categoria, o texto e os exemplos das variáveis antes de solicitar uma nova análise.
3. Opt-in (consentimento) (link para esta seção)
Antes de iniciar mensagens pelo WhatsApp, respeite as regras de permissão da Meta e a preferência do destinatário. O registro 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.
Mantenha a data, a origem e o contexto da autorização. O painel permite registrar o consentimento por contato; seu sistema também deve conservar as evidências da operação.
Mantenha uma lista de contatos que não desejam receber mensagens e consulte-a antes de enviar, inclusive nas campanhas por etiqueta.
4. Qualidade do número (link para esta seção)
A Meta informa a qualidade do número com base em sinais recentes dos destinatários, incluindo bloqueios e denúncias. Acompanhe o status e evite insistir em mensagens que a pessoa não espera.
| Nota | O que significa |
|---|---|
| Verde (alta) | Qualidade alta nos sinais informados pela Meta. |
| Amarelo (média) | Revise os destinatários, a frequência e o conteúdo das mensagens. |
| Vermelho (baixa) | Revise as campanhas e acompanhe possíveis restrições de envio. |
A qualidade pode afetar a capacidade de envio. Confira a situação do número e eventuais restrições no painel e no WhatsApp Manager.
5. Limite diário (link para esta seção)
O limite de mensagens iniciadas pela empresa considera destinatários únicos em uma janela móvel de 24 horas. Ele é diferente do limite de requisições da API e da capacidade de envio por segundo.
Consulte o limite atribuído ao seu portfólio no WhatsApp Manager. A elegibilidade e o aumento de capacidade dependem dos critérios atuais da Meta. Não fixe um limite universal no código da integração.
6. Coexistência com o aplicativo (link para esta seção)
Na coexistência, o mesmo número pode operar no aplicativo WhatsApp Business e na API. O painel exibe as mensagens do aplicativo que a Meta sincronizou. Isso não significa que o webhook público encaminhe essas saídas como mensagens recebidas do contato.
Mensagens enviadas pelo aplicativo não têm as mesmas confirmações disponíveis no painel que uma mensagem enviada pela API. A disponibilidade de histórico e mídia também depende do que a Meta sincronizou. Não conte ausência de confirmação como falha de entrega.
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 |
| Destinatário não pôde receber | recipient_unreachable |
A lista completa, com o que fazer e quais valem repetir, está em Erros e limites.