Esta documentação detalha o processo completo para configurar a API Oficial do WhatsApp (também conhecida como WABA ou Cloud API) e conectá-la à plataforma Connect.ai.
Seguir os passos na ordem correta é fundamental para garantir uma instalação bem-sucedida.
Live - Criação de App no facebook developers e integração com a API Oficial, Instagram e Facebook
Tutorial passo-a-passo:
Vídeo 1: Criar número de telefone
Vídeo 2: Configurando número na Meta
Vídeo 3: Configurando WABA no Connect.ai
Vídeo 4: Configurando Webhook de callback
Vídeo 5: Registrar o número e criar templates de mensagens
Documentação das etapas:
Etapa 1: Pré-requisitos e Preparação
Antes de começar, você precisará de dois itens essenciais:
- Uma conta no Facebook.
- Um número de telefone (pode ser virtual ou um chip físico).
Importante
AVISO SOBRE O NÚMERO DE TELEFONE
- Você não pode usar o mesmo número no aplicativo normal do WhatsApp e na API Oficial.
- Se você deseja usar um número que já possui uma conta de WhatsApp, é obrigatório excluir permanentemente a conta de WhatsApp associada a ele antes de continuar. Não basta apenas deletar o aplicativo.
- Para testes, recomendamos fortemente a compra de um número virtual.
Etapa 2: Criação e Configuração do Aplicativo na Meta
Nesta etapa, vamos criar o aplicativo no ambiente da Meta que será responsável por gerenciar a API.
- Acesse o Facebook for Developers: Faça o login com sua conta do Facebook em https://developers.facebook.com/
!
- Crie um Novo Aplicativo:
- Clique em "Criar Aplicativo".
!
- Selecione "Outros"
- Selecione o tipo "Business".
!
- Dê um nome ao seu aplicativo (ex: "Waba Cloud API") e associe-o à sua conta do Gerenciador de Negócios (BM).
- Adicione o Produto WhatsApp: No painel do seu novo aplicativo, encontre e adicione o produto "WhatsApp".
!
- Configure as Informações Básicas:
- Acesse "Configurações do app" > "Básico".
!
- Preencha os campos "URL da Política de Privacidade" e "URL dos Termos de Serviço".
- Ative o Aplicativo: No topo da página, mude o status do aplicativo de "Em desenvolvimento" para "Ao vivo".
!
Etapa 3: Cadastrando e Verificando seu Número de Telefone
Agora, vamos adicionar e verificar o número de telefone que será usado pela API.
- No menu do seu aplicativo, vá para "WhatsApp" > "Configuração da API".
!
- Adicione um Número de Telefone: Clique no botão para adicionar um novo número.
!
- Preencha os Dados: Insira as informações da sua empresa e o número de telefone que você preparou na Etapa 1.
- Verifique o Número: Escolha receber o código de verificação por SMS ou ligação telefônica e insira o código recebido.
- Adicione a forma de pagamento
!
- Registre o Número com PIN (Passo Obrigatório):
- Após a verificação, a Meta exige um registro de segurança com um PIN de 6 dígitos. Este passo é realizado via API. (token provisório)
!
- Utilize uma ferramenta como o Postman e o endpoint "Registrar Fone" (disponível em nossa coleção) para enviar o PIN de 6 dígitos ao seu número. https://www.postman.com/meta/whatsapp-business-platform/request/kkn2spv/register-phone
- Este passo é crucial para que o número seja ativado com sucesso.
Dica
Etapa 4: Gerando um Token de Acesso Permanente
O token gerado pelo painel do desenvolvedor é temporário e expira em 24 horas. Para uma conexão estável com o Connect.ai, você precisa de um token permanente.
- Acesse as Configurações do Negócio: Navegue até seu Gerenciador de Negócios (BM).
- Vá para "Usuários" > "Usuários do sistema".
!
- Crie um Usuário do Sistema: Adicione um novo usuário do sistema com a função de "Admin".
- Atribua Ativos: Com o novo usuário selecionado, clique em "Atribuir Ativos".
- Selecione "Aplicativos", escolha o aplicativo que você criou na Etapa 2 e conceda a permissão de "Gerenciar App".
- Gere o Token: Ainda com o usuário selecionado, clique em "Gerar novo token".
- Selecione o seu aplicativo.
- Defina a expiração como "Nunca".
- Marque as permissões necessárias (pelo menos
whatsapp_business_managementewhatsapp_business_messaging). - Clique em "Gerar Token", copie o código e guarde-o em um local seguro, pois ele não será exibido novamente.
Etapa 5: Conectando a API no Connect.ai e Ativando Webhooks
Com tudo pronto no ambiente da Meta, o passo final é configurar a conexão dentro do Connect.ai.
Vídeo detalhado na nossa área de membros:
-
Conecte o Canal no Connect.ai (Para Enviar Mensagens):
- No painel Admin do Connect.ai, acesse "Canais" e adicione um novo canal do tipo "WABA".
!
- Preencha os campos com as informações obtidas no painel da Meta: Whatsapp - Configuração da API
- ID do número de telefone
- ID da conta do WhatsApp Business
- O Token Permanente que você gerou na Etapa 4.
- Clique em Salvar. Neste momento, você já estará apto a enviar mensagens.
-
Ative os Webhooks no Connect.ai (Para Receber Mensagens):
- No painel Admin do Connect.ai, vá para "Configurações" > "Integração Meta".
- Copie a URL do Webhook e o Token de Verificação.
- Volte ao painel do seu aplicativo na Meta, em "WhatsApp" > "Configuração da API".
!
- Clique em "Editar" na seção de Webhooks.
- Cole a URL e o Token copiados do Connect.ai e clique em "Verificar e Salvar".
- Após verificar, clique em "Gerenciar" e assine (subscribe) todos os eventos de webhook disponíveis (especialmente
messages).
!
Encerramento
Com os webhooks ativos, sua plataforma está pronta para enviar e receber mensagens através da API Oficial do WhatsApp. Esta é a conexão mais estável e segura, recomendada para todas as operações.
Possíveis erros
Solução de Problemas: Evite falhas de comunicação com o Webhook da Meta (Erro ETIMEDOUT)
Os erros AxiosError do tipo "ETIMEDOUT" registrados no log indicam que a comunicação com o servidor da Meta (Webhook) está sofrendo atraso de resposta — geralmente causado por alta latência de rede.
Isso ocorre quando o ping entre sua VPS e o domínio graph.facebook.com ultrapassa 40 ms, resultando em falhas do tipo TIMEDOUT nas requisições.
Para prevenir esse problema, é importante definir uma rota pública estável em sua VPS. Se você utiliza a Hostinger, por exemplo, o caminho é:
- Acesse o painel da Hostinger.
- Vá até Configurações → Rede → DNS.
- Defina um DNS fixo recomendado, como:
1.1.1.1(Cloudflare)8.8.8.8(Google)
Essas configurações ajudam a garantir uma rota mais direta e estável entre a VPS e a infraestrutura da Meta, reduzindo atrasos e eliminando o erro de timeout nos logs.
!
Links de apoio - Meta API
Guia Verificação do app (tech provider)
Guia Configuração coexistência:
</api-oficial-waba/whatsapp-oficial-cadastro-incorporado-e-coexistencia-com-app-proprio>
Configuração login incorporado:
Configuração instagram nativo:
</facebook-e-instagram-nativo/canal-instagram-nativo-beta>
Configuração facebook messenger nativo:
</facebook-e-instagram-nativo/canal-facebook-messenger-nativo-beta>
Guia da Meta para configuração do login incorporado:
https://developers.facebook.com/docs/facebook-login/facebook-login-for-business/\
Guia da Meta para configuração da coexistência:
https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users
Central de ajuda e suporte técnico meta:
https://developers.facebook.com/support/