Você trabalhará em três lugares: Meta for Developers, Configurações do negócio da Meta e Painel do gestor do ConversaFlow. Salve primeiro a configuração no ConversaFlow e depois valide o webhook na Meta.
Antes de começar
Separe uma conta Meta com permissão administrativa e confirme que o número será usado na WhatsApp Business Platform. Para uma operação de produção, o portfólio empresarial e o aplicativo precisam estar sob controle da própria empresa.
Crie o aplicativo no Meta for Developers
- Acesse Meus aplicativos no Meta for Developers e escolha Criar aplicativo.
- Selecione uma opção de uso empresarial quando a Meta solicitar o caso de uso ou o tipo do aplicativo.
- Vincule o aplicativo ao portfólio empresarial correto.
- No painel do aplicativo, adicione o produto WhatsApp e abra Configuração da API ou Getting Started.
Os nomes das opções podem mudar conforme a interface da Meta, mas o resultado deve ser um aplicativo empresarial com o produto WhatsApp adicionado.
Adicione o número e copie os identificadores corretos
- Na área do WhatsApp do aplicativo, escolha adicionar ou reivindicar um número.
- Preencha o nome de exibição da empresa e conclua a confirmação por SMS ou ligação.
- Se a Meta solicitar, defina o PIN de seis dígitos usado para registrar o número e guarde-o em local seguro.
- Localize o ID da conta do WhatsApp Business, também chamado de WABA ID.
- Na tela de configuração da API, localize Phone Number ID e copie somente esse número.
O estado VERIFIED confirma a verificação do número, mas ainda não prova que as mensagens chegarão ao ConversaFlow. O aplicativo, o webhook e o campo messages também precisam estar vinculados corretamente.
Gere o token permanente no Meta Business
- Acesse as Configurações do negócio da Meta.
- Abra Usuários e depois Usuários do sistema.
- Crie um usuário do sistema com função administrativa, por exemplo ConversaFlow.
- Em Adicionar ativos, conceda ao usuário do sistema o aplicativo e a conta do WhatsApp Business necessários, com o controle exigido para administrar e enviar mensagens.
- Escolha Gerar novo token, selecione o aplicativo e autorize as permissões whatsapp_business_management e whatsapp_business_messaging.
- Quando a Meta oferecer a escolha de expiração, selecione a opção adequada à operação contínua e guarde o token em local seguro.
Preencha o WhatsApp Oficial no ConversaFlow
No ConversaFlow, acesse Painel do gestor → Canais e localize a área WhatsApp oficial. Marque a opção de uso da API oficial e preencha os campos abaixo.
Clique em Salvar e validar. O ConversaFlow verifica as credenciais e mostra o número, o nome e a qualidade informados pela Meta. A versão compatível da API é gerenciada pela plataforma; não é necessário digitá-la.
Configure e assine o webhook
- Depois de salvar o WhatsApp Oficial, copie a URL de callback exibida no ConversaFlow.
- No Meta for Developers, abra WhatsApp → Configuração ou a seção de Webhooks.
- Cole a URL no campo URL de callback.
- No campo Verificar token, cole exatamente o mesmo token do webhook salvo no ConversaFlow.
- Não ative certificado de cliente, a menos que sua infraestrutura tenha sido preparada especificamente para mTLS.
- Clique em Verificar e salvar.
- Em Campos do webhook, localize messages e escolha Assinar.
A URL tem este formato, mas deve ser copiada diretamente da empresa aberta no ConversaFlow:
https://conversaflow.travassyx.com/api/webhooks/whatsapp?tenant_slug=identificador-da-empresa
Para o funcionamento atual do ConversaFlow, messages é o campo necessário. Não assine todos os campos apenas por precaução; habilite outros somente quando uma funcionalidade da plataforma solicitar.
Prepare o aplicativo para produção
O modo de desenvolvimento permite testes limitados. Para receber tráfego de produção, conclua as exigências apresentadas pela Meta para o seu negócio e publique o aplicativo quando estiver pronto.
- confirme os dados básicos e o domínio do aplicativo;
- informe a Política de Privacidade e os Termos de Serviço;
- conclua a verificação empresarial quando solicitada;
- mantenha o número, a conta do WhatsApp Business e o aplicativo no mesmo portfólio correto;
- publique o aplicativo somente depois de validar o fluxo completo de mensagens.
Faça o teste final
Erros mais comuns
“Não foi possível validar a URL de callback ou o token”
Salve primeiro a configuração no ConversaFlow. Depois copie novamente a URL e confirme que o token informado na Meta é idêntico ao token do webhook, sem espaço extra. Verifique também se o endereço público usa HTTPS e contém o identificador correto da empresa.
“Session has expired” ou “Error validating access token”
Foi usado um token temporário ou expirado. Gere um novo token pelo usuário do sistema no Meta Business, conceda os ativos e as permissões necessárias e substitua a credencial no ConversaFlow.
O teste da Meta chega, mas mensagens reais não aparecem
Confirme a assinatura do campo messages, a vinculação do aplicativo à conta do WhatsApp Business, o número correto e o estado de publicação do aplicativo.
A URL do webhook retorna 403 quando é aberta no navegador
Isso é esperado: o navegador faz uma consulta simples, sem os parâmetros de verificação enviados pela Meta. Valide a URL pelo botão Verificar e salvar e use uma mensagem real para testar o recebimento.
O servidor recebeu o webhook com 200, mas nenhuma mensagem apareceu
O evento pode ser apenas uma atualização de status ou um teste da Meta. Envie uma nova mensagem de outro número e confirme no diagnóstico do ConversaFlow que ela foi registrada como mensagem da API Oficial.
O ConversaFlow recebe, mas não consegue responder
Confira o Phone Number ID, as permissões do token, o acesso do usuário do sistema ao ativo do WhatsApp e a situação do número no WhatsApp Manager.
Segurança das credenciais
- não envie o token permanente nem o segredo do app por WhatsApp, e-mail aberto ou prints;
- não reutilize o token do webhook como senha de usuário;
- remova imediatamente o acesso de usuários do sistema que não forem mais necessários;
- gere uma nova credencial se houver qualquer suspeita de exposição;
- mantenha somente os ativos e as permissões necessários para a integração.