How to retrieve User Data from Facebook using the Microsoft Bot Framework

DEPRECATION WARNING: The content in this article is written for BotBuilder v3 which is almost out of support. The package mentioned is not maintained anymore either.

The Microsoft Bot Builder SDK is one of three main components of the Microsoft Bot Framework. The Microsoft Bot Framework provides just what you need to build and connect intelligent bots that interact naturally wherever your users are talking, from text/SMS to Skype, Slack, Office 365 mail and other popular services.

In order to retrieve the profile fields (first and last name, picture, locale, timezone and gender) an API request is necessary. To ease this process, I have written a middleware which handles this automatically for each user. This allows you to use the Facebook User Data directly in your dialog, without worrying about API requests.

Getting Started

Install the BotBuilder-FacebookExtension package via npm.
npm install botbuilder-facebookextension --save

Retrieve the (Facebook) Page Access Token from the BotFramework.com portal. This is necessary for the API call.

Go to My bots and choose your bot. Then you search for the Facebook Messenger channel and you press edit.

Search for 'Enter your credentials' and copy your Page Access Token.

Store your Page Access Token somewhere in your environment variables. This is a secret token and should not be hardcoded inside your bot!

Load the Facebook Extension module and register the Middleware. As you can see, I retrieve my AccessToken from an environment variable.

import { RetrieveUserProfile } from 'botbuilder-facebookextension';

bot.use(
    RetrieveUserProfile({
        accessToken: process.env.FacebookAccessToken,
    })
);

The userData will be retrieved before every dialog runs. Now you can easily use it in your bot and make the conversations more personal. All data is stored inside session.userData.field_name. All available field names are described in the Messenger Platform Docs.

bot.dialog('/', [
    (session, args, next) => {
        session.send(`Hi ${session.userData.first_name}!`); // The userData is prepopulated by the Middleware
    }
]);

Advanced options

Settings

By default the User Data will be cached for a day for performance reasons. You can change this to any amount of minutes by setting the expireMinutes key. Change it to 0 to disable the cache.

By default all available fields will be retrieved from the User Profile API. If you want to override this, you can set an array of fields as the fields key. See the example below.

bot.use(
    RetrieveUserProfile({
        accessToken: process.env.FacebookAccessToken,
        expireMinutes: 60, // OPTIONAL
        fields: ['first_name', 'last_name', 'gender'] // OPTIONAL
    })
);

Set preferred locale

At the moment there are some issues with the recognition of the user locale on Facebook, while using the BotBuilder SDK. As a workaround you can set the preferred locale based on the locale we retrieved from Facebook.

session.preferredLocale(session.userData.locale, (err) => {
    if (!err) {
        // Locale files loaded
    } else {
        // Problem loading the selected locale
    }
});

Done!
Any questions? Leave them in the comments or tweet me at @imicknl. In the coming weeks I am going to extend this package with more native Messenger Platform functions. Let me know what you would like to see integrated into this BotBuilder extension!

View project on Github: BotBuilder-FacebookExtension