Facebook Messenger

The Facebook Messenger platform integration allows you to build custom Messenger bots using Jovo.

Apps for Facebook Messenger are called Messenger bots. You can find a general introduction into building those bots in the official Messenger documentation.

In the installation section, we're going to set up a Jovo project that works with Facebook Messenger.

A Messenger bot usually consists of two parts:

• The Facebook app that is connected to a Facebook page in the Facebook for Developers portal
• The code that handles the logic of your bot

In the Facebook for Developers portal, you need to create an app that gets connected to a Facebook page. Learn how to set it up in the deployment section.

If a user sends messages to your page, the Messenger platform sends API requests to your webhook endpoint. The code is then responsible for returning an appropriate response. We're going to set up the code for this in the installation section, and look into configuration options afterwards.

Jovo is a framework that allows you to build apps that work across devices and platforms. However, this does not mean that you can't build highly complex Messenger bots with Jovo. Any custom Messenger bot that can be built with the official Messenger SDK can also be built with the Jovo Framework. In the platform-specific features section, we're going to take a look at Facebook Messenger features in Jovo.

To create a new Facebook Messenger project with Jovo, we recommend installing the Jovo CLI, creating a new Jovo project, and selecting Facebook Messenger as platform using the CLI wizard. Learn more in our getting started guide.

# Install Jovo CLI globally
$ npm install -g @jovotech/cli

# Start new project wizard
# In the platform step, use the space key to select Facebook Messenger
$ jovo new <directory>

If you want to add Facebook Messenger to an existing Jovo project, you can install the plugin like this:

$ npm install @jovotech/platform-facebookmessenger

Add it as plugin to your app configuration, e.g. app.ts:

import { App } from '@jovotech/framework';
import { FacebookMessengerPlatform } from '@jovotech/platform-facebookmessenger';
// ...

const app = new App({
  plugins: [
    new FacebookMessengerPlatform({
      pageAccessToken: '<yourAccessToken>',
      verifyToken: '<yourVerifyToken>',
    }),
    // ...
  ],
});

The integration needs at least a pageAccessToken and a verifyToken. Learn more in the configuration section.

You can configure the Facebook Messenger platform in the app configuration, for example app.ts:

import { FacebookMessengerPlatform } from '@jovotech/platform-facebookmessenger';
// ...

const app = new App({
  plugins: [
    new FacebookMessengerPlatform({
      pageAccessToken: '<yourAccessToken>',
      verifyToken: '<yourVerifyToken>',
      plugins: [
        /* ... */
      ],
      session: {
        /* ... */
      },
      senderActions: {
        /* ... */
      },
    }),
    // ...
  ],
});

Options include:

• pageAccessToken: The access token to your page generated in the Facebook Developer portal. See deployment for more information.
• verifyToken: A string to add to the Facebook developer portal to verify server requests. See deployment for more information.
• plugins: For example, you need to add an NLU integration here.
• session: Session specific config. Take a look at session data for more information.
• senderActions: Facebook Messenger sender actions.

Facebook Messenger requests mostly consist of raw text that need to be turned into structured data using a natural language understanding (NLU) integration.

Here is an example how you can add an NLU integration (in this case NLP.js) to the app configuration in app.ts:

import { FacebookMessengerPlatform } from '@jovotech/platform-facebookmessenger';
import { NlpjsNlu } from '@jovotech/nlu-nlpjs';
// ...

const app = new App({
  plugins: [
    new FacebookMessengerPlatform({
      plugins: [new NlpjsNlu()],
    }),
    // ...
  ],
});

Facebook Messenger does not offer session storage, which is needed for features like session data, component data, and the $state stack.

To make Facebook Messenger bots work with these features, Jovo automatically enables the storage of session data to the active database integration. Under the hood, it adds session to the storedElements config.

Since Facebook does not have the concept of sessions, we need to define after which time a request should be seen as the start of the new session. The default is 15 minutes and can be modified either in the storedElements config (works across platforms) or in the Facebook Messenger config:

new FacebookMessengerPlatform({
  session: {
    expiresAfterSeconds: 900,
  },
});

Facebook Messenger sender actions allow you to mark latest user messages as seen and enable typing indicators while your bot is working on sending a response.

By default, both actions are enabled by default:

new FacebookMessengerPlatform({
  senderActions: {
    markSeen: true,
    typingIndicator: true,
  },
});

• markSeen: This adds the mark_seen sender action and show latest messages as read.
• typingIndicator: This turns typing indicators on when a request was received (in the dialogue.start middleware) and turns them off when the dialogue lifecycle is completed (in the dialogue.end middleware).

Note: Although Instagram works similar compared to Facebook Messenger, it does not support sender actions at the moment.

You can access the Facebook Messenger specific object like this:

this.$facebookMessenger;

You can also use this object to see if the request is coming from Facebook Messenger (or a different platform):

if (this.$facebookMessenger) {
  // ...
}

There are various Facebook Messenger specific elements that can be added to the output.

For output that is only used for Facebook Messenger, you can add the following to the output object:

{
  // ...
  platforms: {
    facebookMessenger: {
      // ...
    }
  }
}

You can add response objects that should show up exactly like this in the Facebook Messenger response object using the nativeResponse object:

{
  // ...
  platforms: {
    facebookMessenger: {
      nativeResponse: {
        // ...
      }
      // ...
    }
  }
}

To test your Messenger bot with a Facebook page, you need to create an app in the Facebook for Developers portal. Learn more in the official Messenger docs.

You need to do two things:

• Connect a page to the app, generate an access token, and add it to the accessToken configuration.
• Add your app endpoint (for example your Jovo Webhook URL for testing) as callback URL and add a verify token that you also specify in the verifyToken configuration. This will be used by Facebook to verify your server.