WhatsApp Oficial via API Cloud (WABA)

Este guia apresenta o processo completo de configuração da API Oficial do WhatsApp da Meta (WABA/Cloud API) integrada ao Mediar Conversas.

Pré-requisitos

• Conta no Facebook.
• Número de telefone (virtual ou físico) que não esteja atualmente registrado no WhatsApp.
• Vínculo com uma conta de Business Manager.

Atenção: você não pode usar o mesmo número no aplicativo normal do WhatsApp e na API Oficial simultaneamente. Qualquer conta de WhatsApp existente nesse número precisa ser excluída permanentemente antes de prosseguir.

Etapa 1, preparação do número

Obtenha um número de telefone dedicado para uso na API (números virtuais são recomendados para testes).

Etapa 2, criação do app na Meta

1. Acesse o Facebook for Developers.
2. Crie um novo aplicativo do tipo Business.
3. Adicione o produto WhatsApp.
4. Complete as configurações básicas do app (URL de política de privacidade, URL de termos de uso).
5. Altere o status do app de "Em desenvolvimento" para "Ativo" (Live).

Etapa 3, registro e verificação do número

1. Navegue até WhatsApp → Configuração da API no painel da Meta.
2. Adicione o número de telefone com as informações da empresa.
3. Verifique via SMS ou ligação com o código recebido.
4. Adicione um método de pagamento.
5. Registre o número com um PIN de 6 dígitos (via API, usando uma ferramenta como o Postman).

Etapa 4, geração do token de acesso permanente

1. Acesse Business Manager → Usuários → Usuários do Sistema.
2. Crie um usuário do sistema com nível de administrador.
3. Atribua os ativos do app com permissão "Gerenciar App".
4. Gere o token com expiração definida como "Nunca".
5. Guarde o token com segurança, ele não pode ser exibido novamente depois de gerado.

Permissões necessárias: whatsapp_business_management e whatsapp_business_messaging.

Etapa 5, integração no Mediar Conversas e ativação do webhook

1. Adicione o canal WABA em Administração → Canais com: ID do número de telefone, ID da conta comercial do WhatsApp (WABA ID) e o token permanente gerado na Etapa 4.
2. Configure os webhooks em Configurações → Integrações Meta: copie a URL do webhook e o token de verificação, cole no painel de Configuração da API do app na Meta, e inscreva-se em todos os eventos de webhook (especialmente messages).

Solução de problemas

Latência de rede causando erros ETIMEDOUT pode ser resolvida configurando um roteamento DNS estável (ex: Cloudflare 1.1.1.1 ou Google 8.8.8.8) nas configurações do seu servidor VPS.