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.

Precisa conectar o número primeiro?

O Phone Number ID, o WABA ID e o token permanente são cadastrados em Conexões, na configuração manual da API Oficial. Veja o passo a passo para obter as credenciais na Meta e preencher no North, incluindo a orientação para “Sem permissão ou ID inválido”. Depois de conectar o canal, use esta tela para 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. Nesse modo, durante a conexão pelo Facebook, é normal o popup pedir para escanear um QR Code com o celular — é o passo da Meta que vincula o aplicativo do celular à API, não um erro.

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.

Agendando um template para contato futuro

Se o cliente pedir para a clínica retomar o contato em outra semana ou no fim do mês, programe um template aprovado diretamente no inbox:

Abra Conversas → Inbox e selecione o atendimento.
Abra a opção de Template e escolha um template aprovado do canal.
Preencha todas as variáveis e confira a prévia do texto e da mídia.
Clique no ícone de relógio, escolha a data e o horário e confirme em Agendar mensagem.

O horário segue o fuso configurado para a clínica. O template e os valores das variáveis ficam registrados no momento do agendamento, para que o envio possa acontecer mesmo com a janela de 24 horas fechada naquele dia.

Na conversa, a barra Envios agendados mostra os próximos disparos. Por ela, é possível alterar o horário ou cancelar enquanto o envio estiver pendente.

Se o template deixar de estar aprovado, o canal ficar indisponível ou a Meta rejeitar os parâmetros no momento do disparo, o envio não será concluído.

Conectando um canal oficial

Em Conversas → Cadastros → Conexões, crie/edite o canal e escolha o tipo API Oficial. Há dois 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.

A conexão via Gupshup (BSP) foi descontinuada e não aparece mais para canais novos. Os poucos canais que ainda usam essa integração são legados e devem ser migrados para a conexão direta com a Meta. Enquanto a migração não acontece, templates com cabeçalho de mídia precisam ter o arquivo configurado na tela de Templates antes do envio.

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).

A API oficial parou de enviar

Se o envio fica vermelho, aparece Tentar novamente ou o número da API oficial para de enviar, verifique primeiro a cobrança da conta WhatsApp Business na Meta. Um cartão inválido, uma cobrança pendente ou a falta de crédito da agência pode bloquear os envios mesmo quando o canal continua cadastrado no North.

No Meta Business Manager, abra Cobrança e pagamentos.
Selecione a conta WhatsApp Business da clínica.
Confira o cartão, as faturas pendentes ou o saldo/crédito administrado pela agência.
Depois de regularizar, sincronize novamente os templates e teste um envio.

Se o pagamento estiver regular e a falha continuar, confira o status do template e da conexão e encaminhe ao suporte a clínica, o horário e a mensagem de erro, sem expor tokens. Veja também custos e pagamento da API Oficial.

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 {saudacao}, {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.

{saudacao} é preenchida no momento efetivo do envio e usa o fuso da clínica: Bom dia das 05:00 às 11:59, Boa tarde das 12:00 às 17:59 e Boa noite das 18:00 às 04:59.

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.
As chaves do North usam um par de chaves ({saudacao}). Não digite {{saudacao}}: o formato duplo é reservado às posições numéricas da Meta.
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
Preciso chamar o cliente em uma data futura	A conversa deve ser retomada depois da janela atual	Agende um template aprovado pelo ícone de relógio no inbox
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