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. Fb Application 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 Fb Messenger Settings
    • In the Access Tokens section of your Messenger Settings add a new page Fb Messenger Add 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.Fb Messenger Page Search
    • Allow the application to manage and access page conversations in Facebook Messenger Fb Messenger Subscription
    • 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. Fb Messenger Page Access Token

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. Fb Messenger Page Access Token

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>"
    }
  }

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 is the name of your organization.
  • Where 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 Fb Messenger Settings
  • Go to the Webhooks section in the Messenger Settings. Fb Messenger Webhook 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

  • 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