Log Events with the Events API for Business Messaging

This guide describes how you can log app and Facebook Page events to analyze how users interact with their Messenger experience.

Before You Start

You will need the following:

• The page_events permission

  • Advanced Access will be automatically granted for this permission when you submit for App Review if your app has already been granted Advanced Access for the pages_messaging permission and your app does not have any policy violations within the last 90 days
• A Page access token requested by a person who is able to perform the ANALYZE task on the Page that is being queried

Limitations

This API is currently not available for businesses or customers based in Europe or Japan.

Policy & Terms

• The Facebook Business Tools Terms
• Pages, Groups, and Events Policies

Logging Events

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>
    

The following table describes the properties and values that must be provided to the endpoint to log Messenger events:

Reporting Leads using Messaging Event API

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.

Example API call to report lead event happening on a thread:

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>
    

Reporting Leads using Ads Insights API

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.

Prerequisites

Before using this API, make sure the application has gone through the app review process for ads_read permission and obtain advanced access.

Execution

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:

• Leads (attributed)
  • /<OBJECT_ID>/insights?fields=actions
  • In the result, action_type=onsite_converstion.lead_grouped

For a detailed definition of the above action types, refer to the Ads Action Stats reference.

Best Practices for Classifying Leads

1. Advertiser is in one of the classical lead gen verticals (auto, professional services, financial services, B2B, education, health).
2. Advertiser asks for contact information such as phone or email address and user provides it.
3. The phone or email address questions are preceded by some sort of qualification (e.g. 1-2 additional questions).
4. If you are offering lead gen templates in your app, add this signal at the end of lead gen flows by default.

Verifying Event Logging

If you are an App or Page admin you can validate that your setup is correct by looking up your events in Ads Manager.

Special Considerations for Analytics for Messenger

• A single App can log interactions for multiple Pages. In these cases, events from interactions with all of the Pages are visible in the same App.
• Multiple Apps can be linked to a single Page. In this case, when the Page is blocked, all Apps linked to the Page will receive a fb_messenger_bot_stopped event.
• The Messenger bot conversation deleted number can be higher than the New User Activity number. Messenger bot conversation deleted is the number of times a user deletes a thread. The Page can initiate further conversation after a user deletes a thread. The additional threads can be deleted by users which increases the Messenger bot conversation deleted number.

Usage for Platform Providers

Logging target

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.

User interface

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.

Permissions

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.

Additional Resources

• App Events Best Practices Guide: Includes recommendations regarding which events to use in various types of apps.