Primeiros passos

Este documento explica como fazer chamadas bem-sucedidas ao serviço da Messenger API for Instagram (também conhecida como API de Mensagens do Instagram nas Políticas do Desenvolvedor) usando seu app e como obter mensagens da conta profissional do Instagram. Para acompanhar este guia, presumimos que você já conheça a Graph API e o Login do Facebook.

Antes de começar

Você precisará do seguinte:

• Uma conta profissional do Instagram
• Uma Página do Facebook conectada a essa conta
• Uma conta de desenvolvedor da Meta que pode executar a tarefa MODERATE na Página
• Um app da Meta criado com o caso de uso do Login do Facebook e definido com as configurações básicas

Desenvolvedores que são iniciantes na plataforma do Messenger

• Siga o passo a passo abaixo para gerar o token de acesso à Página e configurar Webhooks.
• Saiba mais sobre os vários recursos da plataforma e adote os que atenderem às suas necessidades.

Desenvolvedores com experiência na plataforma do Messenger

• Os conceitos de token de acesso e Webhooks são semelhantes. O serviço da Messenger API for Instagram requer instagram_manage_messages no token de acesso à Página e assinatura dos Webhooks em tópicos do Instagram.
• A maioria dos recursos é semelhante à Messenger API. Analise os detalhes da lista de recursos e adote os que atenderem às suas necessidades.

Fluxo de login

Você pode usar o Login do Facebook ou o Login para Empresas do Instagram para solicitar aos usuários do app as permissões necessárias.

O fluxo do Login para Empresas do Instagram permite que uma pessoa faça o seguinte durante o fluxo de login:

• Converter a conta do Instagram dela em uma conta profissional do Instagram
• Criar uma Página do Facebook para a própria empresa
• Conectar a Página à conta profissional do Instagram

Para implementar o Login para Empresas do Instagram, consulte primeiro o guia Business Login for Instagram e depois retorne a esta página.

1. Obter um token de acesso do usuário

Verifique sua conexão à conta de desenvolvedor do Facebook. Depois, acesse o app e dispare o modal de Login do Facebook. Lembre-se: sua conta de desenvolvedor do Facebook precisa ter a capacidade de executar tarefas, com acesso de nível "Moderado" ou superior, na Página do Facebook conectada à conta do Instagram que você deseja consultar.

Depois de acionar o modal, clique em OK para conceder ao app as permissões instagram_basic, instagram_manage_messages e pages_manage_metadata.

A API retornará um token de acesso do usuário. Capture o token para que o app possa usá-lo nas consultas seguintes. Se você estiver usando o Explorador da Graph API, ele será capturado automaticamente e exibido para referência no campo Token de acesso:

2. Obter as Páginas do usuário

Consulte o ponto de extremidade GET /me/accounts. Isso é convertido para GET /{user-id}/accounts, que executa um GET no nó do usuário do Facebook, com base no seu token de acesso.

curl -i -X GET \
 "https://graph.facebook.com/v9.0/me/accounts?access_token={access-token}"

Essa ação deve retornar uma coleção de Páginas do Facebook nas quais o usuário atual pode executar as tarefas MANAGE, CREATE_CONTENT, MODERATE ou ADVERTISE:

{
  "data": [
    {
      "access_token": "EAAJjmJ...",
      "category": "App Page",
      "category_list": [
        {
          "id": "2301",
          "name": "App Page"
        }
      ],
      "name": "Metricsaurus",
      "id": "134895793791914",  // capture the Page ID
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    }
  ]
}

Capture a identificação da Página do Facebook conectada à conta do Instagram que você quer consultar. Tenha em mente que os usuários do app podem ter a capacidade de executar tarefas em várias Páginas. Por isso, em algum momento, você precisará usar uma lógica que possa determinar a identificação da Página correta que deve ser capturada (ou criar uma interface do usuário em que os usuários do app possam identificar a Página correta para você).

3. Obter o token de acesso à Página

Para executar várias chamadas à API de Mensagens do Instagram, será necessário usar o token de acesso à Página (PAT, pelas iniciais em inglês) associado da conta profissional do Instagram em questão que foi concedido anteriormente por meio do fluxo de login do Facebook.

Envie uma solicitação GET para o ponto de extremidade /{page-id} usando o token de acesso do usuário. Por exemplo:

curl -i -X GET "https://graph.facebook.com/{page-id}?
  fields=access_token&
  access_token={user-access-token}"  

Se o processo for bem-sucedido, o app obterá esta resposta:

{
  "access_token":"{page-access-token}",
  "id":"{page-id}"              
}  

• Se o token de acesso do usuário for de curta duração, o token de acesso à Página será válido por apenas 1 hora.
• Se o token de acesso do usuário for de longa duração, o token de acesso à Página não terá data de validade.

Para gerar um token de acesso à Página de longa duração, siga este guia.

3a. Obter o token de acesso à Página via ferramenta Painel do Desenvolvedor do Instagram

Se for o proprietário dos ativos (conta do Instagram e Página do Facebook) que deseja integrar ao serviço da Messenger API for Instagram, você tem a opção de usar a ferramenta de configuração do Instagram no Painel de Apps do Desenvolvedor para configurar com mais praticidade os tokens de acesso à Página e os Webhooks. Você encontra a ferramenta em Painel de Apps do Desenvolvedor → Messenger → Configurações do Instagram. A maneira atual de configurar tokens e webhooks continuará funcionando, mas essa ferramenta facilitará a configuração do ambiente.

4. Habilitar as ferramentas conectadas de controle de mensagens

Para gerenciar as mensagens do Instagram via API, as contas profissionais do Instagram precisarão habilitar a alternância de ferramentas conectadas nas configurações do controle de mensagens.

5. Obter os objetos de Caixa de Entrada da conta profissional do Instagram

Use a identificação da Página capturada e o token de acesso à Página (PAT, pelas iniciais em inglês) para consultar o ponto de extremidade GET /{page-id}/conversations?platform=instagram:

curl -i -X GET \
 "https://graph.facebook.com/v9.0/17841405822304914/conversations?platform=instagram&access_token={access-token}"  

Essa ação deve retornar as identificações de todos os objetos de conversa no usuário do Instagram:

{
  "data": [
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTM2MDk5MDc1MzYyOTgx"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTYzMzQ2MzE5NjM1NDcy"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTk3MTY0NjI2NzAyMjMw"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MzkzNDI5MDYzMzkyNjU0"
    }
}

Se conseguir realizar essa consulta final, você poderá fazer consultas usando qualquer um dos pontos de extremidade do serviço da Messenger API for Instagram. Consulte os nossos vários guias e referências para saber o que cada ponto de extremidade faz e quais permissões eles requerem.

Próximas etapas

• Aperfeiçoe o app para que ele possa usar todos os pontos de extremidade necessários e veja as permissões que cada um requer.
• Conclua a configuração do Webhook para que ele possa receber notificações em tempo real sempre que o usuário enviar uma mensagem para a conta profissional do Instagram.
• Conclua o processo de análise do app e solicite a aprovação de todas as permissões necessárias para que os usuários possam concedê-las enquanto o app estiver em produção.