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

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.

The Facebook User Profile API lets your bot get more information about the user and personalize their experience. In this series of posts about Facebook & Microsoft Bot Framework, I am going to explain how to implement better Messenger Platform support into your existing BotBuilder project. Today we will have a look at how to integrate the User Profile API.

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

  1. Install the BotBuilder-FacebookExtension package via npm.
    npm install botbuilder-facebookextension --save
  2. Retrieve the (Facebook) Page Access Token from the 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.

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

  4. 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';

        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


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.

        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

Mick Vleeshouwer

Partner Technology Strategist @ Microsoft | Software Engineer