Como configurar WhatsApp (API oficial Meta)

Este guia descreve a integração WhatsApp Business Platform (Cloud API) no OSBChat: não utiliza o WhatsApp pessoal nem o app de consumidor; o número fica vinculado a uma WABA (WhatsApp Business Account) na Meta.

Para visão geral dos canais, veja O que são integrações e quais temos?.

Experiência hoje e o que vem a seguir (Embedded Signup)

Hoje: o fluxo é manual e guiado. Quem administra a Meta cria app, número, token e webhook; no OSBChat você informa Phone Number ID, WABA ID, token de acesso e o token de verificação do webhook. Há botão de verificação de conexão e checklist na tela da integração.

Em evolução (melhor UX): o caminho recomendado pela indústria e pela Meta é o Embedded Signup (login/conexão dentro do produto, sem colar credenciais longas). Quando isso estiver disponível no OSBChat, o passo a passo abaixo será simplificado (menos cópia de IDs, mais fluxo OAuth / embedded). Avisaremos nas Documentações e no roadmap interno em docs/whatsapp-official-roadmap.md (raiz do repositório).

OAuth “Conectar com Meta”: hoje existe fluxo OAuth para Instagram no produto. O WhatsApp oficial ainda não usa o mesmo fluxo automático de token; a configuração é a descrita neste artigo.

Testes na Meta: “sandbox” e número de teste

Na prática de desenvolvimento, costuma-se falar em sandbox no sentido de: no painel do app (WhatsApp → área de API de testes / configuração inicial), a Meta disponibiliza um número de teste e pede que você cadastre até 5 números de telefone como destinatários permitidos. Enquanto o app/número estão nesse modo, as mensagens iniciadas pela API para fora dessa lista costumam ser bloqueadas — é o comportamento esperado para desenvolvimento seguro.

Isso não substitui o cadastro comercial completo (número verificado em produção, templates, etc.), mas confere para o caminho feliz de validar webhook, recebimento e envio com o OSBChat.

Embedded Signup (quando implementado)

O fluxo embutido da Meta (Embedded Signup) exige, na documentação oficial, enquadramento como Tech Provider / Tech Partner ou Solution Partner, além de configuração Facebook Login for Business (template WhatsApp Embedded Signup, config_id, domínios HTTPS permitidos). O passo a passo técnico de produto e servidor está em docs/whatsapp-official-roadmap.md (Fase A).

Pré-requisitos

Meta Business Account (business.facebook.com).
App em developers.facebook.com — tipo adequado para negócios (conforme o assistente de criação da Meta).
Produto WhatsApp adicionado ao app.
WABA (ID da conta WhatsApp Business) com número registrado na Cloud API (verificação por SMS ou voz).
Token de acesso com permissões para WhatsApp (mensagens e gestão), conforme a documentação Meta (ex.: usuário do sistema / token de longa duração, dependendo do seu modelo).
URL pública da sua instância OSBChat para o webhook (HTTPS).

Número

Pode ser um número novo dedicado à API.
Se o número já foi usado em outro produto WhatsApp, pode ser necessário migrar para a Cloud API seguindo o processo oficial da Meta (não dá para usar o mesmo número no app pessoal e na API ao mesmo tempo). Links para documentação de migração costumam estar na tela da integração no OSBChat.

Passo a passo (fluxo manual atual)

1. Meta Business e app

Crie ou acesse a organização em Business Manager.
Em Meus apps, crie um app e adicione o produto WhatsApp.

2. Número e WABA

Em WhatsApp → configuração da API, registre o número (código por SMS ou ligação).
Anote o WhatsApp Business Account ID (WABA) e o Phone number ID (identificador do número na API — não confundir apenas com o número em formato E.164 exibido ao usuário).

3. Token de acesso

Gere um token válido para chamadas à Graph API (/messages, etc.) com o escopo necessário para a sua WABA.
Guarde o token em local seguro; você vai colá-lo no OSBChat (ou, no futuro, o Embedded Signup fará essa etapa de outra forma).

4. Webhook no app Meta

URL de callback: a URL exibida na configuração da integração OSBChat para o canal WhatsApp (webhook), no formato da sua instância, por exemplo:
https://SEU_DOMINIO/api/webhook/whatsapp
Token de verificação (verify token): defina um segredo forte. O mesmo valor deve ser salvo na configuração da integração no OSBChat (campos de verificação do webhook) e informado na Meta no campo de verificação do webhook.
Assinatura de campos: no mínimo, eventos que entregam mensagens recebidas. Conforme evoluirmos o produto, podem ser necessários campos adicionais (status de entrega/leitura, sincronização de envios / ecos — ver secção Eco e dedupe).

5. No OSBChat

Acesse Integrações e crie uma integração do tipo WhatsApp API oficial Meta (nome pode variar levemente conforme idioma).
Preencha Phone Number ID, WABA ID (se solicitado), access token e o verify token do webhook.
Salve e ative a integração.
Use Verificar conexão (ou equivalente) para validar token e número contra a Graph API.
Associe um workflow (bot) à integração, como nos outros canais.

6. Teste ponta a ponta

Envie uma mensagem de texto do seu celular para o número da WABA.
Deve surgir conversa e mensagem inbound no painel.
Responda pelo OSBChat e confirme o outbound no histórico.

Multi-tenant e roteamento do webhook

Cada número na Cloud API tem um Phone Number ID único. O OSBChat associa o webhook recebido ao phone_number_id no JSON da Meta e resolve a integração correta. Assim, várias organizações podem usar a mesma URL de webhook (/api/webhook/whatsapp) com números diferentes, sem misturar conversas.

Janela de 24 horas e templates

Mensagens iniciadas pelo cliente seguem as regras da janela de atendimento da Meta (respostas dentro do prazo permitido).
Fora desse contexto, envios iniciados pela empresa costumam exigir template aprovado no WhatsApp Manager.

Campanhas e estimativa de custo

Ao criar campanha com canal oficial, o produto pode exibir estimativa informacional em USD (categoria do template, região etc.). Valores finais são sempre os da fatura Meta; a estimativa não substitui o billing da Meta.

Eco, dedupe: lições do Instagram → cuidado no WhatsApp oficial

Na integração Instagram, o OSBChat trata ecos (mensagens refletindo envio feito pela própria página/app) com o flag sync_outbound_from_channel e deduplicação por identificador externo (mid), para não gravar duas vezes o mesmo envio — o que, caso contrário, pode confundir o histórico e até gerar segunda resposta da IA se o eco for interpretado como tráfego novo.

No WhatsApp Cloud API, a situação é análoga em espírito:

Quando passarmos a registrar envios feitos fora do OSBChat (ex.: WhatsApp Business App no celular) ou ecos da API, precisamos garantir um único registro por mensagem canônica.
A Meta expõe identificadores de mensagem (WAMID). O normalizador do OSBChat já repassa wa_wamid nos metadados quando o webhook traz id da mensagem — base para merge/dedupe no motor, no mesmo espírito do Instagram.

Regra de produto: antes de tratar novos tipos de webhook (sync, eco, status), planejar dedupe por WAMID e atualizar o roadmap em docs/whatsapp-official-roadmap.md (fase E).

Onde aprofundar

Tema	Artigo / recurso
Categorias de template (utility vs marketing)	/docs/whatsapp-templates-meta
Roadmap técnico e lacunas	`docs/whatsapp-official-roadmap.md` (raiz do repo)
Preços Meta	Documentação de preços WhatsApp
Webhooks Cloud API	Referência de webhooks

Resumo

Prepare Meta Business, app, WABA e número na Cloud API.
Configure webhook (URL + verify token iguais ao OSBChat).
Preencha Phone Number ID, WABA, token e associe o bot.
Teste recebimento e resposta.
Use templates aprovados para mensagens iniciadas pela empresa fora da janela.
Futuro: Embedded Signup simplificará o onboarding; até lá, este passo a passo permanece a referência.
Ao habilitar sync/eco, siga a dedupe por WAMID para evitar duplicar respostas da IA.