Plataforma do Messenger

API de Conversas da plataforma do Messenger

Este documento explica como obter informações sobre suas conversas no Messenger e nas Mensagens do Instagram. Você pode ver o seguinte:

  • Uma lista de conversas na sua Página do Facebook ou conta profissional do Instagram.
  • Uma lista de mensagens em cada conversa.
  • Detalhes sobre cada mensagem, incluindo quando a mensagem foi enviada e por quem.

Antes de começar

Neste tutorial, presumimos que você leu os guias Messenger Platform Overview e Instagram Messaging Overview, bem como implementou os componentes necessários.

Você precisará do seguinte:

  • A identificação da Página do Facebook da sua empresa ou da Página do Facebook vinculada à sua conta profissional do Instagram.
  • Um token de acesso à Página solicitado de uma pessoa que pode executar a tarefa MESSAGING ou MODERATE na Página.
  • É preciso ter acesso avançado para ver conversas entre sua empresa e pessoas que não têm uma função no seu app de mensagens, na sua conta profissional do Instagram, na sua Página do Facebook nem na sua empresa.

Para conversas no Messenger entre pessoas e sua Página, o app precisará do seguinte:

Para conversas nas Mensagens do Instagram entre pessoas e sua conta profissional do Instagram, o app precisará do seguinte:

  • Um token de acesso à Página solicitado por uma pessoa que pode executar a tarefa MESSAGING na Página vinculada à conta empresarial do Instagram.
  • As permissões instagram_basic, instagram_manage_messages e pages_manage_metadata.
  • Seu app precisa pertencer a uma empresa verificada.

Limitações

  • Apenas a URL de imagem ou vídeo para compartilhamento será incluída nos dados retornados em uma chamada de API ou na notificação de webhooks.
  • Caso você tenha contas vinculadas com chaves privadas (como email ou número de telefone), não será possível recuperar conversas entre as contas em questão. Somente as conversas entre um usuário do Facebook e uma conta do Instagram estarão disponíveis. Esse problema será resolvido quando o app for aprovado para o acesso avançado. Se você tiver várias contas vinculadas na Central de Contas no app do Instagram, será possível recuperar as conversas entre todas elas.
  • As conversas na pasta de solicitações que estiverem inativas por 30 dias não serão retornadas nas chamadas de API.

Quando uma conta empresarial do Instagram se conectar ao seu app, você poderá usar a API para sincronizar as conversas antigas da Caixa de Entrada.

Obter uma de lista de conversas

Para obter uma lista de conversas, envie uma solicitação GET ao ponto de extremidade /PAGE-ID/conversations e inclua o parâmetro platform definido como instagram ou messenger.

Exemplo de solicitação

Texto formatado para facilitar a leitura.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

Se o processo for bem-sucedido, o app receberá um objeto JSON com uma lista de IDs das conversas entre você e uma pessoa, além da hora em que a última mensagem foi enviada.

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
}

Encontrar a conversa com um usuário específico

Para obter uma conversa entre sua conta profissional do Instagram ou Página do Facebook e uma pessoa específica, envie uma solicitação GET ao ponto de extremidade /PAGE-ID/conversations com o parâmetro platform, além do user_id definido como o ID no escopo do Instagram ou da Página da pessoa em questão.

Exemplo de solicitação

Texto formatado para facilitar a leitura.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

Se o processo for bem-sucedido, o app receberá o ID da conversa.


{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
}

Obter uma lista de mensagens em uma conversa

Para obter uma lista de mensagens em conversas, envie uma solicitação GET ao ponto de extremidade /CONVERSATION-ID e inclua o campo messages.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

Se o processo for bem-sucedido, o app receberá uma lista com os IDs das mensagens e a hora em que cada mensagem foi criada.

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

Obter informações sobre uma mensagem

Para obter informações sobre uma mensagem (como remetente, destinatário e conteúdo), envie uma solicitação GET ao ponto de extremidade /MESSAGE-ID com os campos do seu interesse.

Os campos-padrão são id e created_time.

Observação: as consultas ao ponto de extremidade /CONVERSATION-ID retornarão todos os IDs de mensagens em uma conversa. No entanto, será possível obter detalhes somente sobre as 20 mensagens mais recentes. Ao consultar uma mensagem trocada antes das últimas 20, você verá um erro informando que o conteúdo foi excluído. 

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

Se o processo for bem-sucedido, o app receberá a resposta JSON a seguir. Neste exemplo, um cliente enviou uma mensagem de texto simples para sua conta profissional do Instagram.

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

Saiba mais

Consulte o nosso material de referência sobre os tópicos a seguir:

Suporte ao desenvolvedor