Skip to main content
Importante: Após migrar um número de telefone para a Plataforma WhatsApp Business, esse número não poderá ser usado simultaneamente no aplicativo WhatsApp Business padrão. Deve ser dedicado exclusivamente a uma plataforma.

​
🔢 Índice

  1. Create a Meta Business Account
  2. Create a Meta App and Enable WhatsApp
  3. Create a System User in Business Manager
  4. Generate a System User Access Token
  5. Register and Verify Your Phone Number
  6. Configure Webhooks in the Meta App
  7. Connect Your Meta App to ZappWay
  8. Scan the QR Code to Pair Your Number
  9. Final Checks and Monitoring

​
1. Crie uma conta Meta Business

  1. Navigate to https://business.facebook.com.
  2. Click “Create Account.”
  3. Fill out the required information:
  • Nome da empresa
    • Seu nome completo
    • E-mail de trabalho
  1. Continue seguindo as instruções para finalizar a configuração. Quando solicitado:
  • Adicione uma Página do Facebook (pode ser uma página temporária ou de teste).
    • Adicione uma Método de pagamento se solicitado.
    • Conclua a Verificação Comercial enviando os documentos necessários (por exemplo, registro da empresa, comprovante de endereço).
Dica: Meta pode limitar certos recursos em novas contas até que você conclua o processo de verificação. Siga todas as instruções na tela e forneça todos os documentos adicionais solicitados.

​
2. Crie um Meta App e habilite o WhatsApp

  1. Go to https://developers.facebook.com/apps.
  2. Click “Create App.”
  3. When prompted “What do you want your app to do?”, select “Other.”
  4. Choose “Business” as your app type.
  5. Complete the form by providing:
  • Nome do aplicativo (por exemplo, “Integração ZappWay WhatsApp”)
    • E-mail de contato
    • Link para a Meta Conta Empresarial que você criou na Etapa 1.
  1. Clique em “Criar aplicativo”.
  2. Dentro do painel do seu aplicativo recém-criado, localize a seção “Produtos”.
  3. Selecione “+ Adicionar Produto.”
  4. Encontre “WhatsApp” na lista e clique em “Configurar”.
Nota:
  • Se Meta solicitar verificação comercial adicional nesta fase, conclua esse processo antes de continuar.
  • Se você não vir o WhatsApp listado, certifique-se de estar trabalhando com a conta correta do Business Manager.

​
3. Crie um usuário do sistema no Business Manager

Para gerenciar tokens de longa duração e atribuir as permissões necessárias, você deve criar um usuário do sistema dentro do Business Manager.
  1. In Business Manager, navigate to Business Settings → Users → System Users.
  2. Click “Add” (or “Add System User”).
  3. Enter a descriptive name (for example, “ZappWay WhatsApp Bot”) and choose “Admin” as the role.
  4. Confirm by clicking “Create.”
  5. Select the newly created System User from the list.
  6. Click “Add Assets.”
  • Para Tipo de ativo, escolha “Aplicativos”.
    • Selecione o Aplicativo WhatsApp que você criou na Etapa 2.
    • Conceda permissão “Gerenciar aplicativo”.
  1. Clique em “Atribuir”.
Verificar:
  • O usuário do sistema agora deve ter “Gerenciar aplicativo” listado nas permissões do aplicativo.
  • Isso garante que o usuário possa gerar tokens e configurar o produto WhatsApp.

​
4. Gere um token de acesso de usuário do sistema

Este token será usado para autenticar sua integração do ZappWay.
  1. Still in Business Settings → System Users, select the System User you created.
  2. Click “Generate New Token.”
  3. Choose the WhatsApp App you linked in Step 3.
  4. Select all of the following permissions:
  • whatsapp_negócios_mensagens
    • whatsapp_negócios_gestão
    • negócios_gestão
  1. Clique em “Gerar Token.”
  2. Copie o token que aparece e armazene-o de forma segura (por exemplo, em um gerenciador de senhas ou variável de ambiente).
  • Se você gerou apenas um token de vida curta, poderá estendê-lo clicando em “Gerar token de vida longa.”
    • Os tokens de longa duração duram até 60 dias antes de serem renovados.
Dica de segurança:
  • Nunca codifique esse token em seu repositório de código.
  • Use variáveis ​​de ambiente ou um gerenciador de segredos em produção.

​
5. Registre e verifique seu número de telefone

Para enviar e receber mensagens através da API, você precisa de um número de telefone ativo e verificado.
  1. In your Meta App’s WhatsApp dashboard (navigate to developers.facebook.com/apps/<YOUR_APP_ID>/whatsapp-business/wa-dev-console), find the “Numbers” section.
  2. Click “Add Phone Number.”
  3. You have two options:
  • Use um número de teste fornecido pela Meta (somente para desenvolvimento).
    • Registre seu número real inserindo seus dígitos (incluindo o código do país, por exemplo, +5511987654321).
  1. Clique em “Registrar”.
  2. Meta enviará um código de verificação via SMS ou chamada de voz para esse número.
  3. Digite o código de verificação no prompt para confirmar e ativar o número.
  4. Depois de verificado, seu número aparecerá como “Ativo” e você verá:
  • ID do número de telefone: um identificador exclusivo para esse número.
    • ID da conta comercial do WhatsApp: identifica qual conta comercial controla esse número.
Anote:
  • Formato do ID do número de telefone: normalmente uma sequência numérica longa.
  • ID da conta comercial: também uma sequência numérica que você pode precisar posteriormente.

​
6. Configure Webhooks no Meta App

Para permitir que o ZappWay receba eventos de mensagens recebidas, você deve configurar um webhook.
  1. In your Meta App’s WhatsApp settings (go to developers.facebook.com/apps/<YOUR_APP_ID>/whatsapp-business/wa-settings), locate the “Webhooks” section.
  2. In “Callback URL,” enter the URL provided by ZappWay, which will look like:
  • <SERVICE_PROVIDER_ID>: o ID exclusivo gerado pelo ZappWay quando você cria a integração (você o obterá na Etapa 7).
  1. Em “Verify Token,” insira o token de verificação que o ZappWay cria para você. Este token ficará visível na interface do ZappWay durante a configuração da integração.
  2. Em “Campos Webhook,” certifique-se de selecionar pelo menos “mensagens”. Isso permite que o ZappWay receba mensagens de texto.
  3. Clique em “Salvar” ou “Continuar”. Depois de salvo, o Meta enviará um desafio ao seu URL de retorno de chamada para verificá-lo. Se o ZappWay estiver configurado corretamente, ele responderá automaticamente com o valor de desafio esperado.
Lista de verificação de validação:
  • Confirme se messages está marcado em Campos de Webhook.
  • Se o Meta retornar um erro de desafio (HTTP 403 ou 404), verifique novamente se o URL de retorno de chamada e o token de verificação correspondem exatamente ao que o ZappWay forneceu.

​
7. Conecte seu Meta App ao ZappWay

Siga estas etapas no painel do ZappWay para concluir a integração.
  1. Log in to your ZappWay dashboard.
  2. In the sidebar, navigate to Integrations → WhatsApp.
  3. Click “Add WhatsApp Integration.” This will open a guided four-step setup wizard.

​
Etapa 1: Requisitos

  • Você verá uma breve visão geral e um link para a documentação completa de integração do ZappWay.
  • Clique em “Continuar” para passar para a próxima etapa.

​
Etapa 2: token de acesso do usuário do sistema

  • Copie o token de acesso de longa duração gerado na Etapa 4.
  • Cole-o no campo “Token do usuário do sistema”.
  • Clique em “Continuar”.
  • ZappWay validará seu token fazendo uma solicitação ao endpoint de depuração de token do Meta.
    • Se o token expirou ou não possui as permissões necessárias, você verá um erro e deverá gerar um novo token.

​
Etapa 3: ID do número de telefone

  • Insira o ID do número de telefone obtido na Etapa 5.
  • Clique em “Continuar”.
  • ZappWay chamará a API Graph do Meta para verificar se o ID do número de telefone pertence ao token.
    • Se válido, o ZappWay registrará automaticamente o número de telefone formatado e finalizará esta etapa.

​
Etapa 4: configuração do webhook

  • ZappWay exibirá dois campos somente leitura:
    1. Callback URL (e.g., https://app.zappway.ai/api/integrations/whatsapp/webhook?service_provider_id=abcdef123456)
    2. Verification Token (a unique string generated by ZappWay)
  • Copy each of these values. You will enter them in your Meta App’s Webhook settings (refer back to Step 6).
  • Confirm that you have selected “messages” under Webhook Fields in the Meta dashboard.
  • Click “Save.”
Ao clicar em “Salvar”, o ZappWay considera a integração configurada. Ele aguardará que o Meta entregue eventos de webhook para o URL de retorno de chamada que você forneceu.

​
8. Digitalize o código QR para emparelhar seu número

Agora que a integração de back-end está configurada, você deve vincular (parear) seu número do WhatsApp Business ao ZappWay digitalizando um código QR.
  1. In the ZappWay dashboard under Integrations → WhatsApp, locate your newly created integration entry.
  2. If it is not already connected, you will see a button labeled “Scan QR Code.” Click it to display the QR code.
  3. On your mobile device, open the WhatsApp Business App.
  4. Tap the three‐dot menu (⋮) in the top right → “Linked Devices” (or “Linked Devices”).
  5. Tap “Link a Device” (or “Pair a Device”).
  6. Use your phone’s camera to scan the QR code shown in ZappWay.
  7. After successfully scanning, you will see a confirmation message in the phone app, and ZappWay will update its status to “Connected.”
Dicas para solução de problemas:
  • Caso o código QR não apareça, certifique-se de que seu navegador não esteja bloqueando pop-ups ou que sua sessão no ZappWay não tenha expirado.
  • Se o emparelhamento falhar repetidamente, verifique se não existem outras sessões ativas para o mesmo número. Talvez seja necessário sair primeiro de outros dispositivos vinculados.

​
9. Verificações finais e monitoramento

Após o emparelhamento, execute estas verificações finais para garantir que sua integração esteja totalmente funcional.

​
9.1 Verifique o status da conexão

  • No ZappWay, a integração agora deve exibir um indicador de status “Conectado” (normalmente verde).
  • Se aparecer “Erro” ou “Desconectado”, clique em “Desconectar” para limpar a sessão existente e repita a Etapa 8 para escanear o código QR novamente.

​
9.2 Teste o fluxo de mensagens

  1. Send a test message from any WhatsApp account to your newly integrated WhatsApp Business number.
  2. Confirm that the message appears in ZappWay’s Inbox interface.
  3. If you have configured any auto-response rules or AI workflows, verify that the AI Employee replies as expected.
Se as mensagens não chegarem:
  • Confirme se o URL de retorno de chamada do webhook está acessível (sem bloqueio de firewall, certificado SSL válido).
  • Verifique os logs do webhook do ZappWay para ver se o Meta está entregando os eventos.
  • Certifique-se de que “mensagens” permaneça selecionado em Campos de Webhook nas configurações do Meta App.

​
9.3 Monitorar erros comuns

  • Token de acesso expirado (401 não autorizado):
  • Se o seu token de usuário do sistema expirar, o ZappWay mostrará erros de autorização nos logs.
    • Gere um novo token de longa duração no Business Manager e cole-o novamente no campo “System User Token”.
  • Falha na verificação do Webhook (403/404):
  • Indica que a solicitação de desafio do Meta não recebeu o token de verificação esperado.
    • Verifique novamente se o URL de retorno de chamada e o token de verificação inserido no Meta correspondem exatamente ao que o ZappWay forneceu.
  • Falha na sessão (stream:error 515):
  • Significa que a sessão do WhatsApp não pôde ser persistida.
    • Confirme se nenhuma outra sessão do WhatsApp está conectada no mesmo número e se o seu servidor possui uma conexão de rede estável.
    • Se necessário, use a função “Desconectar” do ZappWay para limpar a sessão e tente escanear o código QR novamente.

​
9.4 Cronograma de renovação de token

*Os tokens de longa duração são válidos por até 60 dias.
  • Antes que um token expire, repita a Etapa 4 para gerar um novo token e depois retorne para Integrações → WhatsApp no ZappWay para substituir o token antigo pelo novo.

​
✅ Notas Finais

  • Verificação de conta comercial: Uma conta Meta Business totalmente verificada desbloqueia limites mais altos de mensagens e garante acesso ininterrupto à API.
  • Limites de mensagens: Novas contas do WhatsApp Business geralmente começam com cotas de mensagens mais baixas. Envolva-se ativamente e siga as diretrizes da Meta para aumentar gradualmente seu limite.
  • Confiabilidade do Webhook: Certifique-se de que o endpoint do webhook do seu servidor esteja sempre online e possa responder às solicitações recebidas em tempo hábil.
  • Práticas recomendadas de segurança: Armazene tokens em cofres seguros ou variáveis ​​de ambiente. Gire-os periodicamente para manter a segurança.
Seguindo essas etapas cuidadosamente, você terá uma integração robusta e totalmente funcional do WhatsApp no ​​ZappWay, permitindo que seu funcionário de IA lide com as interações com os clientes de maneira integrada.
Links úteis: Siga exatamente estas instruções e sua integração será configurada com sucesso.