Messenger Platform

Conversations API for Messenger Platform

This document explains how to get information about your Messenger and Instagram Messaging conversations. You can get:

  • A list of conversations for your Facebook Page or your Instagram Professional account
  • A list of messages within each conversation
  • Details about each message including when the message was sent and from who

Before You Start

This tutorial assumes you have read the Messenger Platform Overview and the Instagram Messaging Overview and implemented the needed components.

You will need:

  • The ID for your Facebook Page for your business or the Facebook Page that is linked to your Instagram Professional account
  • A Page access token requested from a person who can perform the MESSAGING or MODERATE task on the Page
  • Advanced Access is required to access conversations between your business and people who do not have a role on your messaging app, your Instagram Professional account, your Facebook Page, or your business

For Messenger conversations between people and your Page, your app will need:

For Instagram Messaging conversations between people and your Instagram Professional account, your app will need:

  • A Page access token requested by a person who can perform the MESSAGING task on the Page linked to your Instagram Business account
  • The instagram_basic, instagram_manage_messages, and pages_manage_metadata permissions
  • Your app must be owned by a verified business

Limitations

  • Only the image or video URL for a share will be included in the data returned in a call to the API or in the webhooks notification.
  • If your accounts are linked using private keys, such as an email or phone number, you will not be able to retrieve conversations between these accounts. Only conversations between one Facebook User and one Instagram account will be available. This issue will be resolved when your app has been approved for Advanced Access. If you have multiple accounts linked in the Account Center on the Instagram app, you will be able to retrieve conversations between all linked accounts.
  • Conversations that are within the Requests folder that have not been active for 30 days will not be returned in API calls.

You can leverage this API to do inbox syncing on past conversations when an Instagram business account is newly connected to your app.

Get a List of Conversations

To get a list of conversations, send a GET request to the /PAGE-ID/conversations endpoint and include the platform parameter set to instagram or messenger.

Sample Request

Formatted for readability
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

On success, your app will receive a JSON object with a list of IDs for the conversations between you and a person and the most recent time a message was sent.

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

Find a Conversation with a Specific User

To get a conversation between your Instagram Professional account or Facebook Page and a specific person, send a GET request to the /PAGE-ID/conversations endpoint with platform parameter and the user_id parameters set to the Instagram-scoped ID or Page-scoped ID for the person.

Sample Request

Formatted for readability
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"

On success, your app will receive the ID for the conversation.


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

Get a List of Messages in a Conversation

To get a list of messages in a conversations, send a GET request to the /CONVERSATION-ID endpoint and include the messages field.

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

On success, your app will receive a list of message IDs and the time each message was created.

{
  "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", 
}

Get Information about a Message

To get information about a message, such as the sender, receiver, and message content, send a GET request to the /MESSAGE-ID endpoint with the fields you are interested.

Default fields are id and created_time.

Note: Queries to the /CONVERSATION-ID endpoint will return all message IDs in a conversation. However, you can only get details about the 20 most recent messages in the conversation. If you query a message that is older than the last 20, you will see an error that the message has been deleted. 

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"

On success, your app will receive the following JSON response. In this example a customer sent a plain text message to your Instagram Professional account.

{
  "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!"
}

Learn more

Visit our reference for:

Developer Support