Facebook Analytics Quickstart Guide for Messenger Bots

This guide is intended to help you set up Facebook Analytics so that you can measure the performance of your Messenger bot and better understand how people are using it.

1. Event Logging

Automatic Logging

As soon as your bot is live, the following events are automatically logged by the Messenger Platform.

Event NameDescription

fb_messenger_bot_message_received

The bot has received a message. Expand the table to view received event parameters.

fb_messenger_bot_message_type

The message type.

fb_messenger_bot_message_template_type

The message template type.

fb_messenger_bot_message_sent

The bot has sent a message. Expand the table to view sent event parameters.

fb_messenger_bot_message_type

The message type.

fb_messenger_bot_message_template_type

The 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. Expand the table to view postback called event parameters.

fb_messenger_bot_postback_event

The postback event name.

fb_messenger_bot_cta_id

The ID of the CTA.

fb_messenger_bot_cta_kind

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

Custom Logging

In addition to the automatic Messenger Platform events, bots can log custom events by using the Application Activities Graph API endpoint. In contrast to the Web SDK, which offers client-side logging, bot events are logged from server to server (from your Messenger bot to the Application Activities endpoint).

Custom events are often used to map out the user journey in your bot. With this logging structure in place, you can use the funnel analysis capability in Facebook Analytics to identify how your bot is used and how it can be optimized. Event names don't have to follow a naming convention but we recommend using predefined event names wherever applicable for the reasons outlined in the info box below.

Predefined vs. Custom Events

Predefined events follow the event and parameter naming conventions of the Android, iOS, and Web SDK. The advantage of predefined events is that they are well integrated into the Facebook ecosystem.

For example, if you log purchases in your bot with the fb_mobile_purchase event, you can enable app event tracking and attribute purchases to your Click-to-Messenger campaigns in Ads Manager.

For a complete list of predefined 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 bot events:

PropertyDescriptionValue

event

Specifies the event type.

Use CUSTOM_APP_EVENTS to indicate that this is a custom event.

custom_events

Array of events you want to log. Refer to the App Events API guide for the list of predefined 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.

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

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 from a bot implemented in JavaScript / Node.js.

Do not send an Access Token with this call

The {app-id}/activities endpoint does not require an Access Token. If you provide an access token with this call, the User ID provided on page_scoped_user_id will be replaced with the user that the token was issued for, which means you won't be able to see demographics data for your events.

var request = require('request');

request.post({ 
  url : "https://graph.facebook.com/your-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: 1,
    application_tracking_enabled: 1,
    extinfo: JSON.stringify(['mb1']),
    page_id: your-page-id,
    page_scoped_user_id: recipientId
  }
}, function(err,httpResponse,body){ 
  console.error(err);
  console.log(httpResponse.statusCode);
  console.log(body);
});

2. Verifying Event Logging in Facebook Analytics

If you are an admin or a developer of a bot for Messenger, you can validate that you have correctly implemented event logging in your Messenger bot. Please see our documentation on debugging events in Facebook Analytics 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.
  • 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 bot can initiate additional threads after the users deletes a thread. The additional threads can be deleted by users which increases the Messenger bot conversation deleted number.

Take a Guided Tour of Facebook Analytics

Now that you're logging app events, visit our demo app to take a guided tour of all of the key features that Facebook Analytics offers you and your business.

The demo app does not have an Event Debugging link. This link is only available in apps that you create.

Next Steps

Be sure to check out our other documentation pages for more advanced guides.