Facebook Messenger

How to connect your Meya bot to Messenger

Create integration

Now that our secrets are in the vault, we're ready to create the integration.

In your app's integration folder, create a folder called facebook and add a file called messenger.yaml and copy this code into it:

type: meya.facebook.messenger.integration
app_id: (@ vault.facebook.messenger.app_id )
verify_token: (@ vault.facebook.messenger.verify_token )
pages: (@ vault.facebook.messenger.pages )
filter:
  tx: >
    (
      meya.event.entry.interactive
      OR meya.presence.event.typing
      OR meya.csp.event
      OR meya.button.event.click
      OR meya.form.event.submit
    )

Create also a vault.secrets.yaml file your APP root folder and add the following key values to it:

facebook.messenger.app_id: xxx
facebook.messenger.verify_token: xxx
facebook.messenger.pages:
  - page_id: xxx
    access_token: yyyy

Update your app with the new integration:

meya vault upload --file vault.secrets.yaml
meya push --build-image

Creating facebook APP

  1. Create a Facebook App at https://developers.facebook.com/
  2. In the app, add the Messenger product.
12751275

Select the Messenger product.

  1. Open the Messenger settings page and in the Token Generation section, either select an existing Facebook Page, or click the Create a new page button and follow the Page setup instructions.
  2. Copy the page id and access token and paste it to vault.secrets.yaml
699699
facebook.messenger.app_id: xxx
facebook.messenger.verify_token: xxx
facebook.messenger.pages:
  - page_id: 106118118497527
    access_token: EAAGUntNEDVgBAHdZBKP3cwSNA947GLRnjHcI178z9i3v9abJZAy3wOtd5MsI67kR2dz5Gc04twtxw2XeyV******************************************************
  1. In the Webhooks section of the app's Messenger settings, click Setup Webhooks.
  2. Subscribe to all Fields
704704
  1. Get the integration webhook URL:
meya webhooks | grep facebook.messenger
  1. Generate a verify token which can be any random alphanumeric, e.g. UUID4
  2. Add a verify_token parameter field to the integration webhook url, e.g.:
    https://grid.meya.ai/gateway/v2/facebook_messenger/app-4089de3a72f947b69f365f0214*****/integration.facebook.messenger?verify_token=fd0473a4-fee5-4efe-9642-b13c3113483f
  3. Add the generated verify token to the Verify Token field on Facebook Messenger Callback URL Subscription and to vault.secrets.yaml
704704
facebook.messenger.app_id: xxx
facebook.messenger.verify_token: 'fd0473a4-fee5-4efe-9642-b13c3113483f'
facebook.messenger.pages:
  - page_id: 106118118497527
    access_token: EAAGUntNEDVgBAHdZBKP3cwSNA947GLRnjHcI178z9i3v9abJZAy3wOtd5MsI67kR2dz5Gc04twtxw2XeyV******************************************************
  1. Copy the APP ID and past it to vault.secrets.yaml
facebook.messenger.app_id: 444884846906712
facebook.messenger.verify_token: 'fd0473a4-fee5-4efe-9642-b13c3113483f'
facebook.messenger.pages:
  - page_id: 106118118497527
    access_token: EAAGUntNEDVgBAHdZBKP3cwSNA947GLRnjHcI178z9i3v9abJZAy3wOtd5MsI67kR2dz5Gc04twtxw2XeyV******************************************************
  1. Finally, update your vault and redeploy your APP:
meya vault upload --file vault.secrets.yaml
meya push --build-image

🚧

"The bot isn't responding to me (or another user)!"

If the bot doesn't respond to a user, check if your Facebook app is in development mode. If it is, the bot will only respond to Facebook users who are listed in the Facebook app's Roles page as an Admin, Developer, or Tester.

17881788

User profile data

The Facebook User Profile API provides the following user profile fields without requiring any additional app permissions.

Field Name

Description

App Permission Required

first_name

First name

N/A

last_name

Last name

N/A

profile_pic

Profile picture

N/A

In order to request profile data to Facebook Messenger you need to specify which fields should be requested on the integration configuration file.
You can also choose where and how do you want to store this data, the possible configurations are:

  • user
  • user_overwrite
  • thread
  • thread_overwrite
  • event
type: meya.facebook.messenger.integration
app_id: (@ vault.facebook.messenger.app_id )
verify_token: (@ vault.facebook.messenger.verify_token )
pages: (@ vault.facebook.messenger.pages )
collect:
    first_name: user
    last_name: user
    profile_pic: thread
    locale: user
    timezone:user
filter:
  tx: >
    (
      meya.event.entry.interactive
      OR meya.presence.event.typing
      OR meya.csp.event
      OR meya.button.event.click
      OR meya.form.event.submit
    )

Adding additional profile fields

In addition to the above fields, other user profile fields can be accessed if your Facebook app has the required permissions.

Field Name

Description

App Permission Required

locale

Locale of the user on Facebook

pages_user_locale

timezone

Timezone, number relative to GMT

pages_user_timezone

gender

Gender

pages_user_gender

To add these permissions:

  1. Go to your Page Settings
  2. From the left-hand menu select Advanced Messaging
  3. Scroll to the Requested Features and then expand the Info About People and then request access to each field you need.
15611561

Selecting additional profile permissions from the Facebook app's Messenger settings.

🚧

Accessing user profile data

User data will only become available after the user has responded to the bot.

Handover protocol

Define which app is the primary and which is the secondary receiver on Facebook Page

  1. Go to your Page Settings
  2. From the left-hand menu select Advanced Messaging
  3. Scroll to the Connected Apps and then under Handover Protocol click on the Configure button
  4. Select which app is the primary and which is the secondary.

Components

To work with the handover protocol Facebook Messenger has a set of components, being:

  • facebook.messenger.handover.extend_thread_control
  • facebook.messenger.handover.get_secondary_receivers
  • facebook.messenger.handover.get_thread_owner
  • facebook.messenger.handover.pass_thread_control
  • facebook.messenger.handover.release_thread_control
  • facebook.messenger.handover.request_thread_control
  • facebook.messenger.handover.take_thread_control

To see more information about handover protocol components check our reference guide.