eDevs DocseDevs Odonto

WhatsApp Cloud API (oficial) — implantação técnica

Caminho oficial para automatizar lembretes e campanhas.

Venda / call desta semana: comece por 06 — Venda + implantação.
Também no painel: WhatsApp → Conexão (wizard) e espelho em odonto/docs/admin/02-meta-whatsapp.md.

Quem paga o quê

Item Quem paga
SaaS eDevs Odonto Clínica → eDevs
Mensagens WhatsApp Clínica → Meta (cartão na WABA)
Setup / implantação Clínica → eDevs (one-shot; ver 05)

Não somos BSP. A WABA é da clínica; o app usa o token dela.

Checklist técnico (1ª clínica com automático)

1. Meta Business + WhatsApp (clínica)

  1. business.facebook.com — portfólio
  2. Contas → WhatsApp → criar / adicionar número
  3. Método de pagamento na WhatsApp Business Platform
  4. (Opcional) verificação do negócio

2. Credenciais (App / System User)

  1. developers.facebook.com/apps — app Business (eDevs ou da clínica, conforme modelo)
  2. Produto WhatsApp
  3. API Setup: Phone number ID (+ WABA ID)
  4. Token produção: System User com
    whatsapp_business_messaging + whatsapp_business_management

3. Webhook (ambiente eDevs)

  • URL: https://<dominio>/api/whatsapp/webhook
  • Verify token = META_VERIFY_TOKEN (ou META_WEBHOOK_VERIFY_TOKEN)
  • Eventos: messages
  • HTTPS obrigatório
  • Base URL: NEXT_PUBLIC_APP_URL

4. Templates (pt_BR — nomes do seed)

Uso Categoria metaName no sistema Variáveis
Lembrete / confirmação UTILITY lembrete_consulta nome, procedimento, data
Aniversário MARKETING aniversario_paciente nome, clinica
Natal MARKETING feliz_natal nome, clinica

Enquanto aprova: teste com hello_world no wizard (checkbox no passo Teste).

5. No eDevs Odonto (wizard)

  1. Login no tenant
  2. WhatsApp → Conexão: Pré-requisitos → Credenciais (colar ou Conectar com Meta) → Verificar → Teste → Ativar
  3. Ativar só libera após verificação OK
  4. Mensagens → Fila → Disparar canal ativo

Variáveis de ambiente

Var Uso
NEXT_PUBLIC_APP_URL Base da URL do webhook
META_VERIFY_TOKEN Verify token (META_WEBHOOK_VERIFY_TOKEN também aceito)
NEXT_PUBLIC_FACEBOOK_APP_ID / FACEBOOK_APP_ID Embedded Signup
FACEBOOK_APP_SECRET Troca do código OAuth
FACEBOOK_CONFIG_ID Config ID do Embedded Signup no Meta App
FACEBOOK_API_VERSION Opcional (padrão v21.0)

Sem App ID/Secret/Config ID, o botão Conectar com Meta fica desabilitado — fluxo de colar token continua válido.

O que ainda é manual (sem Tech Provider)

  • Criar/aprovar WABA e cartão na clínica
  • Templates pt_BR na Meta
  • System User permanente ou Embedded Signup com env eDevs
  • Escala multi-clínica sem colar token → Tech Provider + Embedded Signup em produção

Cron:

curl -H "x-cron-secret: $CRON_SECRET" https://DOMINIO/api/cron/reminders

6. Opt-in

Campo Uso
reminderOptIn Confirmação / lembrete 24h
marketingOptIn Aniversário, Natal, campanhas

Erros comuns

Sintoma Causa
Template name / #100 Nome ou idioma ≠ aprovado
24h / #131047 Texto livre fora da janela
#131026 Telefone sem DDI / inválido
Webhook 403 Verify token diferente
Token expira Usar System User permanente

Escala (depois)

Tech Provider + Embedded Signup em produção — várias clínicas sem colar token. O painel já tem Conectar com Meta e troca OAuth; falta App Meta eDevs completo (IDs no .env) e status Tech Provider para escala.

Não bloqueia o 1º cliente: use o assistente com System User permanente.

Referências Meta