Messaging Insights API

This document explains how to programmatically get metrics for messages that your business has sent or received. The Messaging Insights API is an extension of the Pages Insights API and allows you to get the same information that appears in the Page Insights tab of your Facebook Page.

Before You Start

To view metrics for a Facebook Page you own or are able to perform the ANALYZE task on, your app will need:

• The Page ID for the Facebook Page for which you want to view metrics
  • For Instagram messaging this will be the Facebook Page linked to the Instagram Professional account
• A Page Access token
• The following permissions:
  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• Standard Access

To view metrics for a Facebook Page you do not own or can not perform the ANALYZE task on the Page, your app will need:

• The Page ID for the Facebook Page for which you want to view metrics
  • For Instagram messaging this will be the Facebook Page linked to the Instagram Professional account
• A Page Access token requested by a person who can perform the ANALYZE task on the Page
• The following permissions via Facebook Login:
  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• Advanced Access

Limitations

• In order for a new conversation to be counted, a person must have performed an action, such as sent a reply to your business. Until the person takes an action, the conversation is visible only to the person and is not counted.

Read Insights Metrics

To read information for one or more metrics, send a GET request to the /PAGE-ID/insights endpoint with the metric parameter set to a comma-separated list of metrics you want to view.

Sample Request

Formatted for readability.

curl -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights
    ?metric=page_messages_new_conversations_unique,page_messages_blocked_conversations_unique 
    &access_token=PAGE-ACCESS-TOKEN"

On success your app will receive the following JSON response:

{ 
  "data": [ 
    { 
      "name": "page_messages_new_conversations_unique", 
      "period": "day", 
      "values": [ 
        { 
          "value": "42", 
          "end_time": "1665175977" 
        }, 
      ]
    },
    { 
      "name": "page_messages_blocked_conversations_unique", 
      "period": "day", 
      "values": [ 
        { 
          "value": "0", 
          "end_time": "1665175977" 
        }, 
      ]
    } 
  ],
}

Total Over Range Sample Request

The following example finds the total number of new, unique conversations over a specific period of time by including the period parameter set to total_over_range with the time range defined by the since and until parameters in our API call.

Formatted for readability.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/
    ?metric=page_messages_new_conversations_unique
    &since=UNIX-TIMESTAMP-START
    &until=UNIX-TIMESTAMP-STOP
    &period=total_over_range
    &access_token=PAGE-ACCESS-TOKEN"

On success your app will receive the following JSON response with the number of new, unique conversations and the end of the time range:

{
  "data": [
    {
      "name": "page_messages_new_conversations_unique",
      "period": "total_over_range",
      "values": [
        {
          "value": 27
          "end_time": "1665175977"
        }
      ],
    }
  ]
}

Breakdown Sample Request

The following example finds the total number of recurring notifications tokens over a specific period of time and grouped by topic and frequency.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/
    ?metric=recurring_notifications_tokens   
    &since=UNIX-TIMESTAMP-START
    &until=UNIX-TIMESTAMP-STOP
    &period=total_over_range
    &breakdown=recurring_notifications_topic,recurring_notifications_frequency 
    &access_token=PAGE-ACCESS-TOKEN"

On success your app will receive the following JSON response with tokens grouped by topic, "newproducts" and "10percentsale", and message frequency available for each topic, "daily", "weekly", and "monthly" for "newproducts" and "daily" and "weekly" for "10percentsale":

{
  "data": [
    {
      "name": "recurring_notifications_tokens",
      "period": "total_over_range",
      "values": [ 
        {
          "value": 3,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "daily"
        },
        {
          "value": 15,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "weekly"
        },
        {
          "value": 8,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "monthly"
        },
        {
          "value": 17,
          "end_time": "1665175977",
          "recurring_notifications_topic": "10percentsale",
          "recurring_notifications_frequency": "daily"
        },
        {
          "value": 14,
          "end_time": "1665175977",
          "recurring_notifications_topic": "10percentsale",
          "recurring_notifications_frequency": "weekly"
        },
      ]
    }
  ]
}

Insights Parameters

Available Metrics

The following metrics are available via with Messaging Insights API:

Learn more about metrics in development.

Response Properties

The following information may be returned in a call to the Insights API.

See Also

• Learn more about Page Insights
• Learn more about Insights object reference