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.

Example Request

curl -X GET "https://graph.facebook.com/v21.0/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>" 
        }
     ]
    } 
  ],
}

Parameters

Parameter	Description
`breakdowns`	Dimensions by which the response is grouped. May be `messaging_channel` (Messenger or Instagram), `recurring_notification_topic`, `recurring_notifications_freuency`
`date_preset`	Relative date range which can be used instead of `since` and `until`. May be `last_week`, `last_month`, `last_quarter`, and more.
`metric`	A comma-separated list of metrics to return
`period`	The aggregation provided within the since/until or date_preset range. The `total_over_range` value gives a single value for the metric over the given date range. May be `day`, `week`, `month`, `days_28`, `total_over_range`
`since`	UNIX timestamp of the start time to get the metric for
`until`	UNIX timestamp of the end time to get the metric for

Available Metrics

The following metrics are available via with Messaging Insights API:

`metric` Name	Description
`recurring_notification_tokens`	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 `breakdowns` Values: `messaging_channel` `recurring_notifications_frequency` `recurring_notifications_topic` This metric is in development.
`page_messages_engagement`	The number of times users interacted with messages on your business Page, by tapping on a call-to-action button. This metric only includes data from Marketing Messages. Possible `breakdowns` Values: `messaging_channel` `recurring_notifications_topic` This metric is in development.
`page_messages_sent`	The number of messages your business Page sent a message to a customer. This metric only includes data from Marketing Messages. Possible `breakdowns` Values: `messaging_channel` `recurring_notifications_topic` This metric is in development.
`page_messages_read_ratio`	The number of read messages divided by the number of messages sent by your Page. Some message reads may not be captured, such as when a customer has turned off read receipts. This metric only includes data from Marketing Messages. Possible `breakdowns` Values: `messaging_channel` `recurring_notifications_topic` This metric is in development.
`page_messages_order_count`	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.
`page_messages_paid_order_earnings`	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.
`page_messages_with_business_outcomes`	The number of messaging connections with at least one order created. This metric is in development.
`page_messages_blocked_conversations_unique`	The number of conversations with the Page that have been blocked.
`page_messages_new_conversations_unique`	The number of messaging conversations on Messenger that began with people who had never messaged with your business before.
`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_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.

Response Properties

Property	Description
`data` array of objects	A list of metrics objects
`name` string	The name of the metric
`period` string	The time period over which data was collected
`values` array of objects	A list of data for a metric
`value` array of objects	The count for the requested metric per day. For metrics that breakdown by type, an object containing counts for each type will be returned.
`end_time` unix timestamp	UTC timestamp of the end time for the metric.