API Oficial do WhatsApp: templates, variáveis e janela de 24h

Além do canal comum conectado por QR Code, o North Clinic CRM suporta canais na API Oficial do WhatsApp (Meta) — a integração autorizada pela Meta, que não depende de um celular ligado. Em troca, ela tem regras próprias: templates aprovados e a janela de 24 horas. Este guia explica as diferenças e como gerenciar os templates.

API Oficial × QR Code: o que muda na prática

	Canal QR Code	Canal API Oficial
Conexão	Espelha o WhatsApp de um celular da clínica	Direto com a Meta (sem celular)
Estabilidade	Depende do celular (internet, bateria)	Não cai por causa do celular
Envio livre	Qualquer mensagem, a qualquer momento	Só dentro da janela de 24h
Fora da janela	—	Apenas templates aprovados
Aprovação de conteúdo	Não precisa	Templates passam por aprovação da Meta
Limites	—	Tier de conversas/dia definido pela Meta (cresce com uso e qualidade)

Coexistência: dá para conectar a API Oficial mantendo o número funcionando no aplicativo WhatsApp Business do celular — as conversas passam a aparecer nos dois lugares.

A janela de 24 horas

Na API Oficial, cada resposta do cliente abre uma janela de 24h. Dentro dela, a equipe envia mensagens livremente. Passadas 24h sem o cliente responder (ou se ele nunca escreveu), a janela fecha e o sistema bloqueia o envio de texto livre — só templates aprovados podem ser enviados para “reabrir” a conversa.

É por isso que, num canal oficial, a confirmação de agendamento e os disparos usam templates: eles funcionam mesmo com a janela fechada.

Conectando um canal oficial

Em Conversas → Cadastros → Conexões, crie/edite o canal e escolha o tipo API Oficial. Há três caminhos:

Facebook (recomendado) — um popup do Facebook guia a autorização da conta WhatsApp Business; o CRM recebe as credenciais automaticamente.
Manual — colar as credenciais obtidas no Meta Business Suite.
Via Gupshup (BSP) — para contas conectadas por esse provedor.

A tela de Templates

Conversas → Templates (rota /app/whatsapp-templates). Ela lista os templates de todos os canais oficiais da clínica, com três informações-chave por template:

Status de aprovação — Aprovado, Pendente ou Rejeitado (pela Meta). Só aprovados podem ser enviados.
Categoria — Utilidade, Marketing ou Autenticação.
Qualidade — bolinha verde/amarela/vermelha atribuída pela Meta conforme a reação dos destinatários (bloqueios e denúncias derrubam a qualidade e podem pausar o template).

Use Sincronizar para puxar da Meta o estado atual de todos os templates — inclusive os criados fora do CRM (Meta Business Manager).

Criando um template

Novo template e preencha:

Nome — só letras minúsculas, números e _ (regra da Meta).
Idioma e categoria.
Corpo (obrigatório), cabeçalho (texto ou mídia), rodapé e botões (resposta rápida, URL, telefone) — opcionais.

Ao salvar, o template é enviado para aprovação da Meta e fica Pendente. Enquanto pendente, não pode ser editado nem enviado — acompanhe pelo botão Atualizar status. A aprovação costuma ser rápida (minutos a horas), mas depende da Meta.

Variáveis (chaves)

No corpo do template você insere chaves do CRM — como {primeiro_nome_cliente}, {data_agendamento}, {hora_agendamento}, {nome_clinica} — usando o seletor da tela. Por baixo, o CRM as converte para as variáveis numeradas da Meta ({{1}}, {{2}}…) e guarda o mapeamento; no envio automático, cada chave é preenchida com o dado real do cliente/agendamento.

Regras que evitam dor de cabeça:

Use sempre o seletor de chaves ao montar o template — chave digitada com nome errado não é reconhecida e pode chegar “crua” ao cliente.
Toda variável precisa de um exemplo no cadastro (exigência da Meta para aprovar).
No envio manual (pela conversa), o sistema só libera o botão de enviar quando todas as variáveis estiverem preenchidas.

Mídia no cabeçalho

Template com imagem/vídeo/documento no cabeçalho exige o upload do arquivo no CRM (imagem JPG/PNG até 5 MB, vídeo MP4 até 16 MB, PDF até 100 MB):

No cadastro, o arquivo de amostra é obrigatório para a Meta aprovar.
Se o template foi criado fora do CRM, após Sincronizar ele pode aparecer com o aviso “Mídia pendente” — use a ação Enviar mídia na listagem para subir o arquivo. Sem isso, o sistema bloqueia o envio do template (para não sair “amputado”, só com o texto — o que ainda assim seria cobrado pela Meta).

Erros comuns e o que fazer

Sintoma	Causa provável	Solução
”Janela de 24h fechada” ao enviar texto	Cliente não responde há mais de 24h	Envie um template aprovado
Template não aparece para envio	Status Pendente ou Rejeitado	Aguarde/ajuste e reenvie para aprovação
Envio bloqueado pedindo mídia	Template com cabeçalho de mídia sem arquivo	Faça o upload da mídia no template
Mensagem chegou com a chave “crua” (ex.: `{primeiro_nome_cliente}`)	Chave digitada errada ou não mapeada	Reedite o template usando o seletor de chaves
Envios param de funcionar no canal oficial	Limite do tier diário da Meta ou qualidade baixa	Verifique a qualidade dos templates; o tier sobe com bom uso