Messaging Insights API Reference

With the Messaging Insights API, you can programatically retrieve the same information that appears in the Page Insights tab of your Facebook Page.

For more information about the Messaging Insights API and other analytics available from the Messenger Platform, see Analytics.

For more information about the Pages Insights API, including information on other metrics available and the permissions required, please see the Pages Insights docs or the Insights object reference.

Permissions

A page access token with read_insights permission is required to interact with this endpoint.

Request URI
Request Parameters
Response Properties
Available Metrics
Example Request
Example Response

Request URI

https://graph.facebook.com/v4.0/me/insights/?access_token=<PAGE_ACCESS_TOKEN>

Request Parameters

Parameter	Description
`metric`	A comma-separated list of metrics to return.
`since`	*Optional.* UNIX timestamp of the start time to get the metric for.
`until`	*Optional.* UNIX timestamp of the end time to get the metric for.

Response Properties

Property	Type	Description
`data`	Array	The response payload.
`data.name`	String	The long name of the returned report.
`data.values`	Array<value>	The available action counts by day.
`value`	Integer \| Object	The count for the requested metric. For metrics that breakdown by type, an object containing counts for each type will be returned.
`end_time`	String	UTC timestamp of the end time for the metric.

Available Metrics

As part of the Graph API v3.3 changes, 2 outdated messaging metrics were deprecated:

page_messages_active_threads_unique

page_messages_reported_conversations_by_report_type_unique

Existing apps can access these metrics using v3.2 or below until July 30, 2019

The following metrics are available via with Messaging Insights API:

Metric Name	Description
`page_messages_total_messaging_connections`	The number of people your business can send messages to. This metric shows the number of people who have ever sent a message to your business on Messenger, not including people who have blocked or reported your business on Messenger. There may be some constraints on your ability to send messages to connections, such as limitations on how many messages you can send during certain timeframes. This metric also only includes connections made since October 2016, when data became available. This metrics replaces the `page_messages_open_conversations_unique` metric, which was deprecated on May 11, 2018.
`page_messages_new_conversations_unique`	The number of messaging conversations on Facebook Messenger that began with people who had never messaged with your business before.
`page_messages_blocked_conversations_unique`	The number of conversations with the Page that have been blocked.
`page_messages_reported_conversations_unique`	The number of conversations from your Page that have been reported by people for reasons such as spam, or containing inappropriate content.
`page_messages_feedback_by_action_unique`	Deprecated `page_messages_feedback_by_action_unique` is deprecated as of November 7, 2017. This metric will be removed in Graph API v2.12. Please migrate your code to use our other Messaging Insights metrics, which provide comparable information. Daily unique conversation counts broken down by user feedback actions, including messaging turn-ons messaging turn-offs thread deletions report spams others

Example Request

curl -X GET "https://graph.facebook.com/v2.8/me/insights/?metric=<LIST_OF_METRICS>&access_token=<PAGE_ACCESS_TOKEN>"

Example Response

{ 
  "data": [ 
    { 
      "name": "<METRIC>", 
      "period": "day", 
      "values": [ 
        { 
          "value": "<VALUE>", 
          "end_time": "<UTC_TIMESTAMP>" 
        }, 
        { 
          "value": "<VALUE>", 
          "end_time": "<UTC_TIMESTAMP>" 
        }
     ]
    } 
  ],
}