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.
This guide assumes you have read the Messenger Platform Overview and implemented the needed components for sending and receiving messages and notifications.
To view metrics for a Facebook Page you own or are able to perform the ANALYZE
task on, your app will need:
pages_messaging
pages_read_engagement
pages_show_list
read_insights
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:
ANALYZE
task on the Pagepages_messaging
pages_read_engagement
pages_show_list
read_insights
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.
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" }, ] } ], }
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.
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" } ], } ] }
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" }, ] } ] }
Parameter | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Dimensions by which the response is grouped. May be one or more of the following:
| ||||||||||||||||
| Relative date range which can be used instead of | ||||||||||||||||
| Required. A comma-separated list of metrics to return | ||||||||||||||||
| The aggregation provided within the since/until or date_preset range. The | ||||||||||||||||
| The start date for the date range during which you wish to view data. Includes data for the date set beginning at 12:00am. Format for the value is | ||||||||||||||||
| The end date for the date range during which you wish to view data. Excludes data for the date set beginning at 12:00am. Format for the value is |
The following metrics are available via with Messaging Insights API:
metric Name | Description |
---|---|
| The number of conversations with the Page that have been blocked. |
| The number of times customers interacted with marketing messages sent by your business Page by tapping on a call-to-action button. Possible
This metric is in development. |
| The number of messaging conversations on Messenger that began with people who had never messaged with your business before. |
| The number of times you created an order in messaging conversations or in third-party apps or websites used to manage messaging conversations. This metric is in development. |
| The approximate amount of money you have earned from orders created through messaging conversations or through third-party apps or websites used to manage messaging conversations. Final earnings may differ due to currency conversions. This metric is in development. |
| The number of marketing messages read divided by the number of marketing messages sent by your Page. Some message reads may not be captured, such as when a customer has turned off read receipts. Possible
This metric is in development. |
| The number of conversations from your Page that have been reported by people for reasons such as spam, or containing inappropriate content. |
| The number of marketing messages your business Page sent to customers. Possible
This metric is in development. |
| 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. |
| The number of messaging connections with at least one order created. This metric is in development. |
| The number of times an account has subscribed to receive marketing messages from your business. If an account has subscribed to multiple topics, it will be counted again for each topic. How it’s calculated: This metric counts the number of times accounts agreed to receive recurring messages minus the number of times accounts unsubscribed. Possible
This metric is in development. |
Learn more about metrics in development.
The following information may be returned in a call to the Insights API.
Property | Description |
---|---|
| A list of metrics objects |
name string | The name of the metric |
period string | The time period over which data was reported |
values array of objects | A list of data for a metric. |
value int | The count for the requested metric during the date range specified |
end_time unix timestamp | UTC timestamp of the end time for the metric |