Passo a passo — API Oficial atual do ChatNex

Antes de começar

Separe os pré-requisitos

• Uma conta pessoal do Facebook com acesso administrativo ao portfólio empresarial.
• Uma empresa configurada no Meta Business e, quando solicitado, verificada.
• Um número que possa receber SMS ou ligação para a confirmação.
• Acesso de administrador ao ChatNex e ao nó oficial da Evolution API.
• Um domínio HTTPS público para a Evolution e para o ChatNex.

Atenção: se o número já estiver conectado ao WhatsApp ou WhatsApp Business comum, confirme antes se o processo escolhido exige migração. Não remova uma conta em produção sem planejar indisponibilidade e histórico.

Meta for Developers

Crie o aplicativo na Meta

1. Acesse Meus aplicativos no Meta for Developers e clique em Criar aplicativo.
2. Selecione um caso de uso relacionado a empresa ou WhatsApp. Se a interface pedir o tipo do app, use Empresa.
3. Informe um nome claro, como ChatNex — Nome da Empresa, e um e-mail de contato.
4. Associe o portfólio empresarial que será proprietário do número.
5. Conclua a criação e abra o painel do novo aplicativo.

Use um aplicativo por estrutura empresarial bem definida. Isso facilita permissões, auditoria e manutenção do token.

Produto do aplicativo

Adicione e configure o WhatsApp

1. No painel do aplicativo, localize WhatsApp e clique em Configurar.
2. Selecione ou crie a Conta do WhatsApp Business — a WABA.
3. Na área de configuração da API, confirme se o número de teste e o token temporário aparecem.
4. Faça um envio de teste para um número permitido. Isso valida o app antes de adicionar o número definitivo.

O token temporário serve para validar a API, mas expira. Não finalize uma conexão de produção com ele.

Número definitivo

Cadastre o telefone que será usado no ChatNex

1. No WhatsApp Manager, abra a área de números e escolha Adicionar número de telefone.
2. Preencha o nome de exibição, categoria e dados comerciais.
3. Informe o número com DDI e DDD e escolha a verificação por SMS ou ligação.
4. Digite o código recebido e, se solicitado, defina o PIN de verificação em duas etapas.
5. Aguarde o número aparecer como conectado ou aprovado.

O nome de exibição precisa representar a empresa e pode passar por análise da Meta. Use um nome que possa ser comprovado no site e nos documentos comerciais.

Dados necessários

Anote os identificadores corretos

Esses números parecem semelhantes, mas têm funções diferentes:

O Phone Number ID fica na configuração da API do produto WhatsApp. O WABA ID aparece como “ID da conta do WhatsApp Business”. Não cole o número de telefone em nenhum desses campos de ID.

Credencial de produção

Gere um token permanente

1. Abra as Configurações do negócio.
2. Em Usuários → Usuários do sistema, crie um usuário do sistema com perfil administrativo.
3. Adicione como ativos o aplicativo e a conta do WhatsApp Business.
4. Conceda controle suficiente para gerenciar a conta e enviar mensagens.
5. Gere um novo token para o aplicativo com as permissões whatsapp_business_messaging e whatsapp_business_management. Adicione business_management quando o gerenciamento de ativos exigir.
6. Copie o token e armazene-o em um gerenciador de segredos. A Meta pode não mostrá-lo novamente.

Webhook 1 de 2

Faça a Meta entregar eventos para a Evolution

A Evolution recebe os eventos oficiais da Meta em um endpoint próprio. Na configuração de webhook do produto WhatsApp, use:

1. Na Evolution API, defina o token de verificação do webhook oficial, conforme a versão instalada — normalmente pela variável WA_BUSINESS_TOKEN_WEBHOOK.
2. Na Meta, informe a URL acima e repita exatamente o mesmo valor no campo Token de verificação.
3. Confirme a validação do webhook.
4. Assine pelo menos o campo messages.

O token de verificação do webhook não é o token permanente da API. Crie uma string longa e exclusiva para a validação.

Assinatura da conta

Assine o aplicativo na WABA

Além de validar o webhook, o aplicativo precisa estar inscrito na conta do WhatsApp Business. Com o token permanente, faça:

Envie o token no cabeçalho Authorization: Bearer SEU_TOKEN. Uma resposta com success: true confirma a assinatura. Use uma versão vigente da Graph API no lugar de vXX.X.

Sem essa assinatura, o webhook pode validar corretamente e ainda assim nenhuma mensagem chegar.

ChatNex · Super Admin

Prepare o nó oficial da Evolution

No ChatNex, abra Nós Evolution. Edite o nó oficial existente ou crie-o se ainda não houver um.

O ChatNex permite apenas um nó do tipo Oficial. Se ele já existe, edite o cadastro em vez de criar outro.

ChatNex · Conexões

Crie a conexão Meta Oficial

Abra Conexões → Nova conexão e preencha:

As opções “Assinar mensagens com nome do usuário” e “Aviso Pendente Humano” são operacionais. Ative-as conforme o processo da equipe.

Webhook 2 de 2

Valide a entrega da Evolution ao ChatNex

A URL-base pública do webhook é https://SEU-DOMINIO-CHATNEX/evolution-webhook.php. Ao configurar a instância, o ChatNex acrescenta automaticamente o UUID da conexão:

1. Na lista de conexões, use Sincronizar para atualizar o estado.
2. Confirme que a instância aparece conectada e que o webhook está habilitado.
3. Se a Evolution permitir escolher eventos, habilite mensagens recebidas, atualizações de mensagens, envio, conexão e contatos.
4. Verifique se a URL é HTTPS, pública e não redireciona para login.

Teste final

Envie uma mensagem e só depois ative a IA

1. De outro telefone, envie uma mensagem nova para o número oficial.
2. Confirme que a conversa e o contato foram criados na empresa correta.
3. Responda manualmente pelo ChatNex e confirme a entrega no WhatsApp.
4. Confira o status da mensagem e teste também texto, imagem e áudio.
5. Depois que entrada e saída funcionarem, configure o agente de IA, vincule-o à empresa/conexão e habilite o atendimento automático.

Não é necessário importar contatos ou conversas antigos. A operação pode começar limpa e criar os registros conforme novas mensagens chegam.