Instagram

Requisitos importantes:

• Você deve ter uma conta Instagram Business ou Instagram Creator (contas pessoais não são suportadas)
• A conta do Instagram deve estar vinculada a uma página do Facebook
• Seu Meta App deve ter o produto Instagram Messaging habilitado

​

🔢 Índice

1. Convert to Instagram Business Account
2. Link Instagram to Facebook Page
3. Create a Meta App and Enable Instagram
4. Generate a Page Access Token
5. Get Your Instagram Account ID
6. Configure Webhooks
7. Connect to ZappWay
8. Final Checks and Monitoring

​

1. Converter para conta comercial do Instagram

​

1.1 Converter conta pessoal em conta comercial

1. Open the Instagram mobile app.
2. Go to your profile and tap the menu (☰).
3. Tap Settings and privacy → Account type and tools → Switch to professional account.
4. Choose Business or Creator (Business is recommended for most use cases).
5. Select a category that best describes your account.
6. Add contact details (email, phone, address) as needed.
7. Complete the setup process.

Observação: Você também pode converter em Configurações → Conta → Mudar para conta profissional em algumas versões do Instagram.

​

2. Vincule o Instagram à página do Facebook

​

2.1 Conecte-se via aplicativo Instagram

1. Go to your Instagram profile.
2. Tap the menu (☰) → Settings and privacy.
3. Tap Business (or Account Center).
4. Tap Page (or Connected accounts).
5. Tap Connect Facebook Page.
6. Select the Facebook Page you want to connect, or create a new one.
7. Confirm the connection.

​

2.2 Verifique a conexão

1. In your Instagram profile, go to Settings → Account → Linked accounts.
2. You should see your Facebook Page listed.
3. Ensure the connection shows as “Active.”

Importante: A página do Facebook que você conectar será usada para gerar o token de acesso na Etapa 4.

​

3. Crie um Meta App e habilite o Instagram

​

3.1 Criar conta Meta Business

1. Navigate to https://business.facebook.com.
2. Create or log in to your Business Manager account.
3. Complete business verification if required (submit documents like company registration).

​

3.2 Criar um Metaaplicativo

1. Go to https://developers.facebook.com/apps.
2. Click “Create App.”
3. Select “Other” when asked what your app should do.
4. Choose “Business” as your app type.
5. Fill in the app details:
   • App Name: “ZappWay Instagram Bot” (or similar)
   • Contact Email: Your business email
   • Business Account: Select your Business Manager
6. Click “Create App.”

​

3.3 Adicionar produto do Instagram

1. In your App dashboard, go to “Products” in the left sidebar.
2. Find “Instagram” and click “Set Up.”
3. Wait for the Instagram product to be added (this may take a few moments).

Observação: Se o produto Instagram não estiver disponível, certifique-se de:

• Seu Meta App está no tipo Business
• Você concluiu a verificação comercial
• A API de mensagens do Instagram está disponível em sua região

​

4. Gere um token de acesso à página

​

4.1 Gerar token

1. In your Meta App, navigate to Instagram → Settings (or Instagram Basic Display → Settings).
2. Scroll to “Access Tokens” section.
3. You’ll see a list of Facebook Pages. Find the Page connected to your Instagram account.
4. Click “Generate Token” next to that Page.
5. Accept the permission requests.
6. Copy the generated Page Access Token and store it securely.

CRÍTICO: Expiração do token

• Os tokens de acesso à página expiram após 60 dias por padrão.
• Para uso em produção, crie um Usuário do Sistema no Business Manager:

1. Vá para Gerenciador de Negócios → Configurações → Usuários do sistema
2. Crie um novo usuário do sistema com função de administrador
3. Atribua o aplicativo ao usuário do sistema com permissão “Gerenciar aplicativo”
4. Gere um token nas configurações do usuário do sistema com a opção “Nunca expirar”
5. Selecione as permissões necessárias: pages_messaging, instagram_basic, instagram_manage_messages

​

4.2 Verificar permissões de token

• ✅ instagram_basic - Informações básicas da conta do Instagram
• ✅ instagram_manage_messages - Envie e receba mensagens
• ✅ pages_messaging - Mensagem pela página do Facebook
• ✅ pages_show_list - Lista de acesso de páginas

​

5. Obtenha o ID da sua conta do Instagram

​

5.1 Encontre o ID da conta do Instagram no Meta App

1. In your Meta App dashboard, go to Instagram → Settings.
2. Scroll to find your connected Instagram accounts.
3. You’ll see the Instagram Account ID displayed as a long numeric string (e.g., 17841401234567890).
4. Copy this ID - you’ll need it for ZappWay configuration.

​

5.2 Método alternativo via API Graph

curl -X GET "https://graph.facebook.com/v21.0/me/accounts?access_token=YOUR_PAGE_ACCESS_TOKEN"

curl -X GET "https://graph.facebook.com/v21.0/PAGE_ID?fields=instagram_business_account&access_token=YOUR_PAGE_ACCESS_TOKEN"

​

6. Configurar webhooks

​

6.1 Configurar URL do webhook

1. In your Meta App, go to Instagram → Settings.
2. Locate the “Webhooks” section.
3. Click “Add Callback URL”.
4. You’ll configure this in Step 7 after creating the integration in ZappWay.

​

6.2 Campos de webhook para inscrição

• ✅ mensagens - Receba mensagens diretas recebidas
• ✅ messaging_postbacks - Receba cliques de botão
• ✅ messaging_optins - Receba eventos de aceitação
• ✅ message_deliveries - Acompanhe o status da entrega
• ✅ message_reads - Rastreie confirmações de leitura

​

7. Conecte-se ao ZappWay

​

Etapa 1: Requisitos

1. Log in to your ZappWay dashboard.
2. Navigate to Integrations → Instagram.
3. Click “Add Instagram 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 4.
2. Click “Continue.”
   • ZappWay will validate the token and retrieve your connected Facebook Page.
   • The system will verify that an Instagram Business account is linked to this Page.

​

Etapa 3: ID da conta do Instagram

1. Paste the Instagram Account ID you obtained in Step 5.
2. Click “Continue.”
   • ZappWay will validate the account ID using your token.
   • The system will retrieve your Instagram username and profile information.
   • If validation succeeds, ZappWay will create the integration.

​

Etapa 4: configuração do webhook

https://app.zappway.ai/api/integrations/instagram/webhook?service_provider_id=abc123

1. Copie ambos os valores.
2. Volte para seu Meta App → Instagram → Configurações → Webhooks.
3. Cole o URL de retorno de chamada.
4. Cole o Token de verificação.
5. Clique em “Verificar e salvar.”
6. Assine os campos do webhook: mensagens, mensagens_postbacks, mensagens_optins, mensagens_deliveries, mensagens_leituras.
7. Retorne ao ZappWay e clique em “Concluir”.

​

8. Verificações finais e monitoramento

​

8.1 Verifique o status da conexão

• Na página Integrações do ZappWay, verifique se a integração do Instagram mostra “Conectado”.
• Seu nome de usuário do Instagram deve ser exibido.

​

8.2 Teste o fluxo de mensagens

1. Send a Direct Message to your Instagram Business account from another account.
2. Verify 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 corresponde exatamente no Meta App
• Verifique se as assinaturas do webhook estão ativas para “mensagens”
• Revise os logs de entrega do webhook no painel do Meta App
• Certifique-se de que seu token de acesso à página seja válido e não tenha expirado
• Confirme se a conta do Instagram está devidamente vinculada à página do Facebook

​

8.3 Problemas e soluções comuns

• Verifique se a conta do Instagram está definida como tipo Empresarial ou Criador
• Certifique-se de que o Instagram esteja vinculado à página correta do Facebook
• Verifique se o token de acesso à página tem permissão instagram_basic

• Verifique novamente o URL de retorno de chamada e a correspondência exata do token de verificação
• Garanta que os servidores ZappWay sejam acessíveis a partir dos IPs do Meta
• Revise os logs do webhook do Meta App para mensagens de erro específicas

• Verifique se o token tem permissão instagram_manage_messages
• Verifique se as mensagens do Instagram estão ativadas nas configurações do aplicativo Instagram
• Revise os limites de taxa no painel do Meta App

• Gere novamente o token de acesso à página com todas as permissões necessárias
• Verifique se o token foi gerado para a página correta do Facebook
• Verifique se o usuário do sistema (se usado) possui permissões de aplicativo adequadas

​

8.4 Limites e Restrições de Tarifas

• Limite de taxa padrão: 200 chamadas de API por hora
• Destinatários de mensagens limitados pelo nível de verificação do seu aplicativo
• Limites mais altos disponíveis após análise e verificação do aplicativo

• Você só pode responder aos usuários dentro de 24 horas após a última mensagem
• Após 24 horas, você precisa do consentimento do usuário para enviar uma nova mensagem
• Use tags de mensagens para casos de uso específicos fora da janela de 24 horas

• Siga as Diretrizes da Comunidade do Instagram
• Evite spam, conteúdo promocional ou mensagens enganosas *Não envie mensagens não solicitadas

​

✅ Melhores Práticas

​

Segurança

• Armazene tokens de acesso à página com segurança (variáveis de ambiente, gerenciador de segredos)
• Use tokens de usuário do sistema para produção (que nunca expira)
• Gire os tokens regularmente (pelo menos a cada 60 dias)
• Monitore o uso do token e as datas de expiração

​

Conformidade

• Siga a Política da Plataforma Instagram e os Termos da Meta Plataforma
• Obtenha o consentimento do usuário antes de enviar mensagens
• Forneça instruções claras de cancelamento
• Respeite a privacidade do usuário e as leis de proteção de dados

​

Experiência do usuário

• Responda rapidamente (menos de 3 segundos quando possível)
• Use rich media (imagens, respostas rápidas) para engajamento
• Implementar indicadores de digitação para respostas mais longas
• Forneça informações úteis e contextuais

​

Monitoramento

• Configure alertas para falhas na entrega do webhook
• Acompanhe a entrega de mensagens e taxas de leitura
• Monitore as taxas de erro da API
• Revise as métricas de envolvimento do usuário

​

🔗 Links úteis

• API de mensagens do Instagram: https://developers.facebook.com/docs/messenger-platform/instagram
• API do Instagram Graph: https://developers.facebook.com/docs/instagram-api
• Webhooks para Instagram: https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook
• Política da plataforma: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/overview#instagram-platform-policy
• Diretrizes da comunidade: https://help.instagram.com/477434105621119