Log Events with the Events API for Business Messaging

Messaging Events API Deprecation

  • Messaging Events API will be deprecated in September 2025. To prepare for this deprecation, Messaging Events API will no longer be supported in any future releases of Graph API, starting with version 21.0, as of September 24, 2024.
  • Partners who choose not to update to the latest Graph API will still be able to access Messaging Events API by calling Graph API version 20.0 or prior until the official product deprecation in September 2025.
  • For Partners who do not update to the latest Graph API, we recommend they use the Conversions API for new integrations. Learn more about the Conversions API.

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

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

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.

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