Skip to main content
Version: 1.5

Messenger Setup

Requirements

Before going further, we assume that you have already prepared:

  • A Facebook Developer account
  • A Facebook App for your Messenger Bot
  • A Facebook Page for your Messenger Bot

Note: If you are not familiar with Facebook App, you can refer to Facebook's official doc, Setting Up Your Facebook App.

Enabling Messenger Channels

To enable Messenger channels, you can start either from new or existing Bottender apps.

New Bottender Apps

Create Bottender App is the best way to start building a new app in Bottender.

To create a project, run:

npx create-bottender-app my-app

Make sure to select the messenger option:

After you go through the steps, bottender.config.js and .env are generated automatically for further channel settings.

Existing Bottender Apps

First, you must have a bottender.config.js file includes the following settings:

module.exports = {
  channels: {
    messenger: {
      enabled: true,
      path: '/webhooks/messenger',
      pageId: process.env.MESSENGER_PAGE_ID,
      accessToken: process.env.MESSENGER_ACCESS_TOKEN,
      appId: process.env.MESSENGER_APP_ID,
      appSecret: process.env.MESSENGER_APP_SECRET,
      verifyToken: process.env.MESSENGER_VERIFY_TOKEN,
    },
  },
};

Make sure to set the channels.messenger.enabled field to true.

By default, the Bottender server listens to the Messenger requests on the /webhooks/messenger path. However, you can overwrite the path by assigning the preferred webhook path in the channels.messenger.path field.

We highly recommend setting your sensitive config using process.env, so you could avoid any credentials get exposed.

Environment Configuration

When you run a Bottender app, Bottender loads environment variables in the config file, bottender.config.js. Then, bottender.config.js loads sensitive or environment-dependent variables in .env.

To make a Messenger Bot works, you have to fill in the below environment variables in .env.

# .env

MESSENGER_PAGE_ID=
MESSENGER_ACCESS_TOKEN=
MESSENGER_APP_ID=
MESSENGER_APP_SECRET=
MESSENGER_VERIFY_TOKEN=

Prepare MESSENGER_APP_ID and MESSENGER_APP_SECRET

Traverse to Your Facebook Apps → \${Your App Page} → Settings → Basic.

You can see your App ID and App Secret. Facebook will ask your Facebook password again before display your App Secret. Fill these two values to MESSENGER_APP_ID and MESSENGER_APP_SECRET in .env.

Prepare MESSENGER_PAGE_ID and MESSENGER_ACCESS_TOKEN

First, please make sure that you have added Messenger as a product of your Facebook App.

Traverse to Your Facebook Apps → \${Your App Page} → Messenger → Settings → Access Tokens. Add your Facebook Page to your Facebook App.

Once you have added your Facebook Page for your App, you can find the Facebook ID. Click the Generate Token button to generate Messenger Access Token.

Facebook has a strict security policy. You can only have one chance to save your Access Token. Remember to have your access token copied before closing the Token Generated pop up. If you forgot or lost your Access Token, the only thing you can do is to revoke a new one.

Prepare MESSENGER_VERIFY_TOKEN

You can define your Verify Token in the filed of MESSENGER_VERIFY_TOKEN in .env. This token is for Facebook to confirm the origin of the response is from your bot server.

Prepare Webhook, and Subscriptions

Before going further, please make sure you have filled in the following fields: MESSENGER_PAGE_ID, MESSENGER_ACCESS_TOKEN, MESSENGER_APP_ID, MESSENGER_APP_SECRET, MESSENGER_VERIFY_TOKEN.

In Development

You can run your Bottender project by the following commands.

npm run dev

Then you can run the following commands to set webhook and enable bot related Messenger subscriptions.

npx bottender messenger webhook set

Finally, you are ready to test your bot on Messenger.

In Production

Run your Bottender project on your hosting by the following commands.

npm start

If you deployed your bot on https://example.com/, your Messenger Bot webhook is https://example.com/webhooks/messenger with the default settings.

Set Up Webhook and Enable Subscriptions by Command

You can set your webhook by the command below.

npx bottender messenger webhook set -w https://example.com/webhooks/messenger

Set Up Webhook and Enable Subscriptions on Facebook App Page

However, there are many more options and information on Facebook App page. You can also set up your webhook on Facebook App Page.

Traverse to Your Facebook Apps → \${Your App Page} → Messenger → Settings → Webhook. Click button Add Callback URL.

Fill your webhook URL in the Callback URL and copy your MESSENGER_VERIFY_TOKEN from .env and paste to Verify Token.

Please make sure that you have enabled Subscriptions you need by clicking Edit Button. We usually recommend developers to enable the following subscriptions: messages, messaging_postbacks, messaging_optins, messaging_referrals, messaging_handovers, messaging_policy_enforcement.

Last but not least, let's echo again about Messenger's strict security policy. Before you release your bot to the public, you have to submit your App to Facebook to get relevant permissions, e.g., pages_message. For more information, see Facebook's official document, Submitting Your Messenger App.