Skip to main content
Importante: Você deve ter uma página no Facebook para usar a integração com o Messenger. A Página será a identidade através da qual sua IA responde aos usuários.

​
🔢 Índice

  1. Create a Meta Business Account
  2. Create a Meta App and Enable Messenger
  3. Generate a Page Access Token
  4. Configure Webhooks in the Meta App
  5. Connect Your Meta App to ZappWay
  6. 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:
    • Business Name
    • Your Full Name
    • Work Email
  4. Continue through the prompts to finalize setup. When prompted:
    • Add a Facebook Page (you can use an existing page or create a new one).
    • Add a Payment Method if requested.
    • Complete Business Verification by submitting the necessary documents (e.g., company registration, proof of address).
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 Messenger

  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:
    • App Name (for example, “ZappWay Messenger Bot”)
    • Contact Email
    • Link to the Meta Business Account you created in Step 1.
  6. Click “Create App.”
  7. Inside your newly created App’s dashboard, locate the “Products” section.
  8. Select ”+ Add Product.”
  9. Find “Messenger” in the list, and click “Set Up.”
Nota:
  • Se Meta solicitar verificação comercial adicional nesta fase, conclua esse processo antes de continuar.
  • Certifique-se de estar trabalhando com a conta correta do Business Manager.

​
3. Gere um token de acesso à página

O token de acesso à página autentica sua integração e permite que o ZappWay envie e receba mensagens em nome da sua página do Facebook.

​
3.1 Gerar token no painel do Meta App

  1. In your Meta App, navigate to Messenger → Settings.
  2. Under “Access Tokens” section, you’ll see your connected Facebook Pages.
  3. Select the Page you want to use for this integration.
  4. Click “Generate Token”.
  5. A modal will appear asking for permissions - accept all required permissions.
  6. Copy the generated Page Access Token immediately and store it securely.
CRÍTICO: Expiração do token
  • Por padrão, os tokens de acesso à página expiram após 60 dias.
  • Para criar um token que nunca expira, você deve:
  1. Crie um usuário do sistema no Business Manager
  2. Atribua o usuário do sistema ao seu aplicativo com permissão “Gerenciar aplicativo”
  3. Gere um token do usuário do sistema (selecione “Nunca” para expiração)
  • Recomendamos o uso de tokens que nunca expiram para uso em produção.

​
3.2 Verificar permissões de token

Seu token deve ter estas permissões:
  • pages_messaging - Enviar e receber mensagens
  • pages_manage_metadata – Gerenciar metadados da página
  • pages_read_engagement – Ler dados de engajamento da página
  • pages_show_list - Lista de acesso de páginas
Você pode verificar as permissões em: https://developers.facebook.com/tools/debug/accesstoken/

​
4. Configure Webhooks no Meta App

Webhooks permitem que Meta envie mensagens recebidas para ZappWay em tempo real.

​
4.1 Configurar URL do webhook

  1. In your Meta App’s Messenger settings, locate the “Webhooks” section.
  2. Click “Add Callback URL” (or “Edit Callback URL” if one exists).
  3. You’ll need two pieces of information from ZappWay (obtained in Step 5):
    • Callback URL: https://app.zappway.ai/api/integrations/messenger/webhook?service_provider_id=<SERVICE_PROVIDER_ID>
    • Verify Token: A unique string generated by ZappWay
Observação: Você obterá esses valores após criar a integração no ZappWay (Etapa 5), ​​então pode ser necessário voltar a esta etapa.

​
4.2 Inscrever-se nos campos do Webhook

Depois de verificar o URL de retorno de chamada, inscreva-se nestes campos de webhook:
  • ✅ mensagens - Receba mensagens recebidas
  • ✅ messaging_postbacks - Receba cliques de botões e postbacks
  • ✅ messaging_optins - Receba eventos de aceitação
  • ✅ message_deliveries - Acompanhe o status de entrega da mensagem
  • ✅ message_reads - Acompanhe quando as mensagens são lidas
Clique em “Inscrever-se” para ativar assinaturas de webhook.

​
5. Conecte seu Meta App ao ZappWay

Siga estas etapas no painel do ZappWay para concluir a integração.

​
Etapa 1: Requisitos

  1. Log in to your ZappWay dashboard.
  2. Navigate to Integrations → Messenger.
  3. Click “Add Messenger Integration.”
  4. Review the requirements and click “Continue.”

​
Etapa 2: token de acesso à página

  1. Paste the Page Access Token you generated in Step 3.
  2. Click “Continue.”
    • ZappWay will validate the token by making a request to Meta’s Graph API.
    • The system will automatically detect your Page ID and Page Name.
    • If validation fails, verify that your token is valid and has the required permissions.

​
Etapa 3: seleção de página

  1. ZappWay will display the detected Page Name and Page ID.
  2. If this is correct, click “Continue.”
  3. If you need to use a different page:
    • Generate a new token for that page in the Meta App dashboard
    • Return to Step 2 with the new token

​
Etapa 4: configuração do webhook

ZappWay exibirá dois valores que você precisa configurar no Meta:
  1. Callback URL (example: https://app.zappway.ai/api/integrations/messenger/webhook?service_provider_id=abc123)
  2. Verify Token (a unique string generated by ZappWay)
Ação necessária:
  1. Copie esses valores.
  2. Retorne às configurações do Messenger do seu Meta App (Etapa 4).
  3. Cole o URL de retorno de chamada e o token de verificação.
  4. Clique em “Verificar e salvar” no painel Meta.
  5. Certifique-se de que todos os campos do webhook estejam inscritos (mensagens, mensagens_postbacks, etc.).
  6. Retorne ao ZappWay e clique em “Concluir”.

​
6. Verificações finais e monitoramento

​
6.1 Verifique o status da conexão

  • Na página Integrações do ZappWay, a integração do Messenger deve mostrar o status “Conectado”.
  • O nome da página deve ser exibido corretamente.

​
6.2 Teste o fluxo de mensagens

  1. Open Messenger and send a test message to your Facebook Page.
  2. Verify that the message appears in ZappWay’s Inbox.
  3. Check that your AI Employee responds according to configured rules.
Se as mensagens não chegarem:
  • Verifique se o URL de retorno de chamada do webhook está configurado corretamente no Meta
  • Verifique se os campos do webhook estão inscritos (especialmente “mensagens”)
  • Revise os logs do webhook no painel do Meta App em busca de erros de entrega
  • Certifique-se de que seu token de acesso à página não expirou

​
6.3 Monitorar problemas comuns

Expiração do token (401 não autorizado):
  • Os tokens de acesso à página podem expirar após 60 dias
  • Use um token de usuário do sistema para acesso que nunca expira
  • Atualize o token no ZappWay antes da expiração
Falhas na verificação do Webhook:
  • Verifique se o URL de retorno de chamada e o token de verificação correspondem exatamente
  • Verifique se os servidores do ZappWay são acessíveis a partir dos IPs do Meta
  • Revise os registros do webhook do painel do Meta App para obter detalhes do erro
Mensagens não enviadas:
  • Verifique as permissões do token de acesso à página
  • Verifique os limites de taxa no painel do Meta App
  • Revise os logs do ZappWay em busca de erros de API
Detecção de Spam:
  • Meta pode sinalizar sua página se muitos usuários a bloquearem ou denunciarem
  • Certifique-se de que suas respostas de IA sejam úteis e apropriadas
  • Evite enviar mensagens não solicitadas

​
6.4 Limites de Taxa

  • O Messenger tem limites de taxas com base no nível de verificação do seu aplicativo
  • Limite de taxa padrão: 200 chamadas de API por hora por usuário
  • Limites mais altos disponíveis após verificação do aplicativo
  • Monitore o uso no painel do Meta App

​
✅ Melhores Práticas

​
Segurança

  • Nunca compartilhe seu token de acesso à página publicamente
  • Armazene tokens em variáveis de ambiente ou gerenciador de segredos
  • Gire os tokens periodicamente (a cada 60 dias no mínimo)
  • Use tokens de usuário do sistema para ambientes de produção

​
Conformidade

  • Siga as Políticas da Plataforma e a Política da Plataforma Messenger da Meta
  • Obtenha o consentimento do usuário antes de enviar mensagens
  • Fornecer mecanismos claros de cancelamento
  • Respeite as preferências e a privacidade do usuário

​
Experiência do usuário

  • Mantenha os tempos de resposta abaixo de 3 segundos
  • Forneça respostas úteis e contextuais
  • Use respostas rápidas para ações comuns
  • Implementar indicadores de digitação para respostas mais longas

​
Monitoramento

  • Configure alertas para falhas de webhook
  • Monitore as taxas de entrega de mensagens
  • Acompanhe as métricas de envolvimento do usuário
  • Revise os logs de erros regularmente

​
🔗 Links úteis

Precisar de ajuda? Se você encontrar problemas durante a configuração, entre em contato com o suporte do ZappWay ou visite nossa documentação em docs.zappway.ai