This guide describes how you can log app and Facebook Page events to analyze how users interact with their Messenger experience.
You will need the following:
page_events
permissionpages_messaging
permission and your app does not have any policy violations within the last 90 daysANALYZE
task on the Page that is being queriedThis API is currently not available for businesses or customers based in Europe or Japan.
Events are logged by submitting a POST
request to the page_activities
edge of an application:
https://graph.facebook.com/<APP_ID>/page_activities
Example request:
curl -X POST -H "Content-Type: application/json" -d '{
"custom_events": [
{
"_eventName": "fb_mobile_purchase",
"_valueToSum": 57.23,
"fb_currency": "USD"
}
],
"advertiser_tracking_enabled": 1,
"application_tracking_enabled": 1,
"page_id": <PAGE_ID>,
"page_scoped_user_id": <PSID>,
"logging_source": "messenger_bot",
"logging_target": "page"
}' https://graph.facebook.com/v21.0
/<APP_ID>/page_activities?access_token=<PAGE_ACCESS_TOKEN>
It is recommended to use standard events for the field _eventName
. Only standard events are reported in Ads Manager and available for ad targeting and optimization (where available).
For example: To log purchase events for attribution in Ads Manager, use the event name fb_mobile_purchase
.
For a complete list of standard event names and parameters, refer to the App Events API guide (section App Event Schema).
The following table describes the properties and values that must be provided to the endpoint to log Messenger events:
Property | Description | Value |
---|---|---|
| Array of events you want to log. Refer to the App Events API guide for the list of standard events and applicable parameters. You can use your own app events as well. You can specify multiple events in the array. | Use a JSON-encoded array to specify your custom event details. |
| Specifies the page ID associated with the event. | Use the Facebook page ID of the page associated with the bot. |
| Specifies the page-scoped user ID associated with the messenger bot that logs the event. | Use the page-scoped user ID provided to your webhook. |
| Specifies whether advertising tracking is enabled. | Use |
| Specifies whether advertising tracking is enabled at the application level. | Use |
| Specifies the event source. | Use the string |
| Specifies to the target entities to which the event will be logged. | Use the strings |
Apps can now begin reporting lead submissions on threads. The lead_submitted
event allows apps to automate reporting of threads that are considered to be a sales lead (e.g. the user shared their contact information and asked to be contacted regarding the sale).
The event is best used to distinguish specific users as potential leads, which should help businesses to prioritize threads from them. For example, a business can set up an automated flow qualifying a user as a potential lead, and trigger this event when the user completes such flow to flag it to a live agent as a high-potential thread.
At this time, this feature is available in an open beta and reporting in Ads Manager is integrated, so leads data will be reported in Ads Manager UI.
curl -X POST -H "Content-Type: application/json" -d '{
"custom_events": [
{
"_eventName": "lead_submitted"
}
],
"advertiser_tracking_enabled": 1,
"application_tracking_enabled": 1,
"page_id": <PAGE_ID>,
"page_scoped_user_id": <PSID>,
"logging_source": "messenger_bot",
"logging_target": "page"
}' https://graph.facebook.com/v21.0
/<APP_ID>/page_activities?access_token=<PAGE_ACCESS_TOKEN>
The reported lead event can be visualized using Ads Insights API. Using this API, you can create an advanced analytics dashboard to help visualize the lead attributed to CTX campaigns.
Before using this API, make sure the application has gone through the app review process for ads_read
permission and obtain advanced access.
A sample insight call at ad campaign level looks like this:
curl -G \ -d "date_preset=last_7d" \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<AD_CAMPAIGN_ID>/insights"
Insight API can be called at ad account, campaign, and ad set level depending on the desired granularity level.
This is the call to get the lead:
/<OBJECT_ID>/insights?fields=actions
action_type=onsite_converstion.lead_grouped
For a detailed definition of the above action types, refer to the Ads Action Stats reference.
Note: We recommend not automatically marking every conversation with a phone number or email address as a lead, especially in markets where phone numbers are shared for payment/ecommerce purposes.
If you are an App or Page admin you can validate that your setup is correct by looking up your events in Ads Manager.
fb_messenger_bot_stopped
event.Platforms that allow people to build Messenger experiences through visual interfaces usually use one central app to power all of its connected pages. To enable your customers to view their own events, you have to log them to your customers' Pages by setting logging_target
to page or app_and_page.
In the context of a visual editor, you could offer a draggable block that lets people choose an event and define additional parameters. This allows Page admins to map out the Messenger flow with suitable events. Ideally, users should be able to select a standard event name from a dropdown list, as only standard events are reported in Ads Manager and available for ad targeting and optimization (where available). If no standard event name aligns with the user action and ads reporting is not needed, you may want to offer a free-form field to allow users to enter a custom event name and parameters.
The required page_events
permission needs to be obtained during the Facebook Login flow of your application. You have to add it to the requested permission scope of the Login Button, Facebook JavaScript SDK call, or your manually built login flow as outlined in this guide.