Log Events with the Events API for Business Messaging

Launching lead event reporting API

As of October 25, 2022, The page_activities endpoint now supports lead_submitted event to report threads that are considered to be a sales lead. This new messaging event is released as a Open Beta. Reporting in Ads Manager will come soon. Learn More

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

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/v17.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:

PropertyDescriptionValue

custom_events

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.

page_id

Specifies the page ID associated with the event.

Use the Facebook page ID of the page associated with the bot.

page_scoped_user_id

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.

advertiser_tracking_enabled

Specifies whether advertising tracking is enabled.

Use 0 to disable and 1 to enable

application_tracking_enabled

Specifies whether advertising tracking is enabled at the application level.

Use 0 to disable and 1 to enable

logging_source

Specifies the event source.

Use the string messenger_bot to indicate that this event comes form a Messenger bot.

logging_target

Specifies to the target entities to which the event will be logged.

Use the strings app, page, or app_and_page to control which entity will receive this event. For more details, see App Events FAQ

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 expected soon.

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/v17.0/<APP_ID>/page_activities?access_token=<PAGE_ACCESS_TOKEN>
    

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