ServisBOT Documentation > Product Features > Engagement Adapters > Facebook Messenger Adapter

Facebook Messenger Adapter

The Facebook Messenger engagement adaptor enables you to create a custom integration with ServisBOT using Facebook Messenger.

Setting up a Facebook Messenger Engagement Adapter

Facebook Prerequisites

To create a Facebook Messenger based adaptor, you will need to setup the following:

Facebook Page - A Facebook page that will be used as the identity of your Facebook Messenger experience, see here for creating a Facebook page https://www.facebook.com/pages/create.
Facebook Developer Account - A Facebook developer account which is required to create new applications that integrate with Facebook services such as Facebook Messenger. More on this can be found here https://developers.facebook.com/.
Facebook App - A Facebook app associated with your developer account that contains the settings for your Facebook Messenger experience. More on this can be found here https://developers.facebook.com/apps. When prompted about the app usage choose “Manage Business Integrations”. This allows you to use Facebook Messenger within your application.

A guide on setting up each of these pieces can be found here https://developers.facebook.com/docs/messenger-platform/getting-started/app-setup/

Once you have completed the steps outlined above navigate to your Facebook App dashboard and do the following:

Add Facebook Messenger to your Application

Navigate to the products section on the sidebar of your application and click Products. Search for Messenger and click Set Up. This will add Facebook Messenger to your application.
Facebook Messenger Page Subscription - Under the Facebook Messenger settings which can be found here
- In the Access Tokens section of your Messenger Settings add a new page
- Search for the page you created in the previous section. This will be the page your Facebook Messenger application will be associated with. In the example photo below the page we are subscribing to is called Servisbotengagementadapter.
- Allow the application to manage and access page conversations in Facebook Messenger
- Generate an Access Token for the page and take note of the token as it will be needed later on to create a ServisBOT secret. This will be referred to as your Page Access Token, and will be used when ServisBOT needs to communicate messages to your Facebook Messenger.

Create a Verify Token

Facebook requires you to create a randomly generated Verify Token to verify applications against webhooks. To generate a random token using the command line you can do the following:

openssl rand -base64 45 | tr -d "/@\"\ " | cut -c-24

Keep note of this token, it will be required in future steps to verify your application against the ServisBOT webhook.

Obtain you Facebook Application Secret

ServisBOT validates incoming messages from Facebook Messenger applications by signing them using the Facebook application’s App Secret. This helps ServisBOT validate the source of the message and validates that it has not been tampered with. To find your application secret do the following:
Navigate to the Settings section of your Facebook application dashboard.
Go to Basic
Your App Secret should be on this section, click Show to view it.
Take note of the App Secret as it will be required later on for creating a ServisBOT secret.

Create a ServisBOT Secret

To allow ServisBOT to interact with your Facebook Messenger application you must create a ServisBOT secret containing the necessary information to allow ServisBOT to send a receive messages from your Facebook Messenger application.

Create the following secret

{
    "Name": "<YOUR_SECRET_NAME>",
    "Type": "secretdoc",
    "Value": {
        "AppSecret": "<YOUR_FACEBOOK_APP_SECRET>",
        "VerifyToken": "<YOUR_VERIFY_TOKEN>",
        "PageAccessToken": "<YOUR_FACEBOOK_PAGE_ACCESS_TOKEN>"
    }
  }

Where <YOUR_SECRET_NAME> is the name you wish to give to the secret.
Where <YOUR_FACEBOOK_APP_SECRET> is the Facebook App Secret that you obtained in the Obtain you Facebook Application Secret section.
Where <YOUR_VERIFY_TOKEN> is the Verify Token that you generated in the Create a Verify Token section.
Where <YOUR_FACEBOOK_PAGE_ACCESS_TOKEN> is the Page Access Token that you obtained in the Add Facebook Messenger to your Application section.
Take note of the SRN of the secret which is provided from the secret creation.

Create a ServisBOT Endpoint

To communicate with ServisBOT via your Facebook Messenger Application you must create a new ServisBOT endpoint to use as the webhook url for your Facebook Messenger events. Create an endpoint using the following definition and replacing and placeholders that are mentioned below:

{
    "Address": "<YOUR_ORGANIZATION>-FacebookAdapter",
    "OutboundBotReference": "FacebookAdapterBot",
    "InboundBotReference": "FacebookAdapterBot",
    "EngagementType": "FacebookMessenger",
    "Status": "online",
    "AllowedDomains": [
      "*.production.helium.servismatrix.com",
      "*.production.helium.servismatrixcdn.com",
      "*.servisbot.com",
      "https://servisbot.com"
    ],
    "EngagementConfig": {
      "Secret": "<YOUR_SECRET_SRN>"
    },
    "TargetBotReference": "FacebookAdapter",
    "Name": "FacebookAdapterEndpoint",
    "Useragent": "useragent"
  }

Where <YOUR_ORGANIZATION> is the name of your organization.
Where <YOUR_SECRET_SRN> is the SRN of the secret you created in the Create a ServisBOT Secret section.
Take note of the Address portion of your endpoint, this will be required later when setting the webhook url for your Facebook Messenger Application.

Facebook Messenger Webhook Settings

Navigate back to your Facebook Application dashboard.
Go to Messenger Settings here
Go to the Webhooks section in the Messenger Settings.
Enter the callback url, the callback url takes the following form:
- https://engagement.<sb-region>.servisbot.com/picard/v1/engage/<endpoint-address>
- Example for the current public ServisBot Regions:
  - https://engagement.eu-1.servisbot.com/picard/v1/engage/<ENDPOINT-ADDRESS>
  - https://engagement.us-1.servisbot.com/picard/v1/engage/<ENDPOINT-ADDRESS>
  - Where ENDPOINT_ADDRESS is the address you obtained in the Create a ServisBOT Endpoint section.
Enter the Verify Token that you generated and included in your ServisBOT secret for your endpoint configuration. The Verify Token was generated in the Create a Verify Token section.
Click Verify and Save
Finally, we need to choose what the webhook subscribes to. Click the Add Subscriptions button on new your webhook.
Check the messages checkbox and save.
Your Facebook Messenger can now send and receive messages from ServisBOT.

Test your Bot

Send a message to your Facebook page using the Facebook Messenger.
Assuming you have a basic flow set up for your ServisBOT bot it will respond to you in Facebook Messenger.
Currently the only flow nodes supported for the Facebook Messenger Adapter are as follows:
- Dialogue
- Input
- Markup
  - List
  - DetailView