App Events with Bots for Messenger

App Events help you understand the makeup of people who engage with your bot. This is done automatically for several activities but can also be done manually by logging custom events from your bot using Graph API calls.

Prerequisites

Before you can begin, you'll need to register your bot with Facebook. See our Messenger Platform Quick Start Guide to learn more.

Automatic Event Logging

App event logging is automatic when your Bots for Messenger app interacts with a user. To create your own events to log interactions or events that are not logged automatically, see the Logging Custom Events section.

Predefined Events for Messenger Bots

The events in this table are logged automatically by the Messenger Platform.

Event NameDescription

fb_messenger_bot_message_received

The bot has received a message.

Message Received Event ParametersDescription
fb_messenger_bot_message_typeThe message type.
fb_messenger_bot_message_template_typeThe message template type.

fb_messenger_bot_message_sent

The bot has sent a message.

Message Sent Event ParametersDescription
fb_messenger_bot_message_typeThe message type.
fb_messenger_bot_message_template_typeThe message template type.

fb_messenger_bot_postback_called

The user has interacted with an element that initiated a postback, such as a call to action (CTA) button, persistent menu or structured message.

Postback Called Event PrametersDescription
fb_messenger_bot_postback_eventThe postback event name.
fb_messenger_bot_cta_idThe ID of the CTA.
fb_messenger_bot_cta_kindThe type of the CTA.

fb_messenger_bot_started

The bot was unblocked by the user.

fb_messenger_bot_stopped

The bot was blocked by the user.

fb_messenger_bot_thread_deleted

A message thread was deleted by the user.

Logging Custom Events

In addition to the predefined events, bots can log custom events by using the Application Activities Graph API endpoint.

The following table describes the properties and values that must be provided to the endpoint to log a custom bot event.

PropertyDescriptionValue

event

Specifies the event type.

Use CUSTOM_APP_EVENTS to indicate that this is a custom event.

custom_events

Specifies the custom event details.

Use a JSON-encoded array to specify your custom event details.

advertiser_tracking_enabled

Specifies whether advertising tracking is enabled.

Use 0 to indicate that tracking is disabled.

application_tracking_enabled

Specifies whether advertising tracking is enabled at the application level.

Use 0 to indicate that tracking is disabled.

extinfo

Specifies the event source.

Use a JSON-encoded array with a single value of mb1 to indicate that this event comes form a Messenger bot.

page_id

Specifies the page ID associated with the messenger bot that logs 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.

Purchase Event Example

The following example demonstrates how to log a purchase event using Javascript with Node.JS.

var request = require('request');

request.post({ 
  url : "https://graph.facebook.com/<app_id>/activities",
  form: {
    event: 'CUSTOM_APP_EVENTS',
    custom_events: JSON.stringify([{
      _eventName: "fb_mobile_purchase",
      _valueToSum: 55.22,
      _fb_currency: 'USD'
    }]),
    advertiser_tracking_enabled: 0,
    application_tracking_enabled: 0,
    extinfo: JSON.stringify(['mb1']),
    page_id: <page_id>,
    page_scoped_user_id: recipientId
  }
}, function(err,httpResponse,body){ 
  console.error(err);
  console.log(httpResponse.statusCode);
  console.log(body);
});

Verifying Event Logging in Facebook Analytics for Apps

If you're an admin or a developer of a bot for Messenger, you can validate that you've correctly implemented custom event logging in Facebook Analytics for Apps. Please see our documentation on debugging events in Facebook Analytics for Apps to learn how to verify that events are being logged.

Special Considerations for Analytics with Bots for Messenger

  • A bot can provide interactions for multiple pages. In these cases, events from interactions with all of the pages are visible in the bot app.
  • Multiple bots can be linked to a single page. In this case, when the page is blocked, all bots linked to the page will receive a fb_messenger_bot_stopped event.

Analytics for Apps

Since app events are logged automatically, you can start using Facebook Analytics for Apps immediately. This analytics channel provides demographic info about the people using your app, offers tools for better understanding the flows people follow in your app, and lets you compare cohorts of different kids of people performing the same actions.

See our documentation for Facebook Analytics for Apps for more information.