Facebook Messenger¶

The following steps give you an overview of the steps necessary to create a bot for the Facebook Messenger. Since the user interface of Facebook is regularly subject to change, the following steps are not entitlement to completeness or accurateness. However, we update the documentation on a regular basis and look forward to your hints.

Brief overview: The installation takes place in multiple steps:

1. (BBP) Create a new bot account for Facebook Messenger
2. (Facebook) Create a new bot account at Facebook
3. (BBP) Complete bot account configuration on Business Bot Platform

Step 1: (BBP) Create a new bot account for Facebook Messenger¶

Webhooks are used to send various events including messages, authentication events and callback events from Facebook to the Business Bot Platform. Because Facebook only supports the WebHook concept for receiving messages from Facebook Messenger, no other methods are supported.

1. Login to the Business Bot Platform:

   • PublicCloud users use the URL: https://my.bbp.local/
   • PrivateCloud users use the URL: https://mysuffix.bbp.local/

2. Choose Chatbot Administration → Instant Messenger Accounts → Create Bot Account. The following data is required to create the bot account:

   Field	Example value
   Name:	MyFMBotAccount
   Description:	BotAccount for department Z
   Instant Messenger:	Facebook Messenger

3. The bot account has been created and must still be configured with the instant messenger account information. To do this, click on the icon Settings and modify the following parameters:

   Required Fields	Description	Example value
   FacebookMessenger.AppSecret	[32 character string] is the application password	6e2e87d91d237dfb2eadad7b401d765d
   FacebookMessenger.PageAccessToken	[179 character string] is the Page Access Token	EAAZA9aTEEH4YBANfxb9NSrOz9...
   FacebookMessenger.ValidationToken	[Verify Token] is the key to access the webhook	password
   FacebookMessenger.WebhookId	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx the Webhook-Id which is a part of the Webhook-URL	db6a19e5-e281-4683-947c-e5490cbf98da

The FacebookMessenger.WebhookId is the unique identifier for the bot account. Facebook requires for the webhook a full URL which contains the WebhookId. In Facebook, the WebHook URL is the following compound address:

Syntax: https://demo.bbp.local/bbp/webhook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Example: https://demo.bbp.local/bbp/webhook/db6a19e5-e281-4683-947c-e5490cbf98da

In addition to the webhook URL, you must assign a key that validates the Facebook connection to the Business Bot Platform. The key is set with parameter: FacebookMessenger.ValidationToken. For example, the key can be password.

If you want to send rich media content to mobile users, a download URL of the file must be submitted to Facebook. Facebook then attempts to download the file and send it to the mobile user. Therefore, it is necessary to set the external URL to access the BBP file store. The URL is defined with the parameter System.InstantMessenger.FileStore.WebAddress in the configuration file /WEB-INF/classes/bbp.properties. For example, specify the following address:

Syntax: System.InstantMessenger.FileStore.WebAddress=https://<host>.<domain>.<tld>/bbp/filestore/
Example: System.InstantMessenger.FileStore.WebAddress=https://bbp-server.example.com/bbp/filestore/

Other mandatory fields such as FacebookMessenger.UserInfo.UserId and FacebookMessenger.PageToken can not be filled yet until the Facebook bot has been configured, which will be explained in the next section.

Step 2: (Facebook) Create a new bot account at Facebook¶

Facebook for Developers provides a configuration page for the Messenger platform to create a new bot.

Configure Facebook App

1. Open website https://developers.facebook.com/apps

2. Click button Add a New App

   {.align-center}

3. Provide a display name (z.B. MyChatbot) and contact email, then click on Create App ID. Subsequently confirm the Captcha

4. Select product category Messenger

   

5. In order to create a new Page Access Token by Facebook, a new Page must be created. Therefore click on the button Create New Page in section Access Tokens.

   

6. Now select the Page category (e.g. Business or Brand or Community or Public Figure) and click on Get Started. Enter a Page name (e.g. Mychatbotbusinesspage) and Category (e.g. Computer Company). Then, click Continue.

   

7. You can now upload a profile photo for the new page. We skip this point by clicking on Skip. We skip the step Add a Cover Photo as well.

   

8. The page has now been created and can be customized as required. Copy the number in the URL into a text editor. The number represents the UserId (FacebookMessenger.UserInfo.UserId).

   

9. Now switch back to the Facebook for developers page to the Access Tokens section and click on Add or Remove Pages to select the page you just created. Click on Next to continue and confirm with Done.

   

10. The page has now been linked to the chatbot and appears in the Pages list. Now click on the button Generate Token to create a new token. Confirm the hint with I Understand and copy the access token into a text editor. Then click on Done. The Access Token represents the parameter FacebookMessenger.PageAccessToken.

    

Webhooks

1. In section Webhooks, you have to configure the webhook. Therefore click on Add Callback URL and enter the Callback URL and Verify Token.

   

   The callback URL and the password of the Webhook is displayed in the Business Bot platform under Channels → Panel Instant Messenger Account → tab Settings and Webhook. The parameter for the password is set with FacebookMessenger.ValidationToken. Please note that the displayed Webhook-Url of the Business Bot platform does not have to correspond to the public (external) accessible URL. Click the button Verify and Save. Facebook will immediately validate the Webhook and confirm if validation was successful or not.

   

2. As soon as the callback URL has been verified by Facebook, the page will appear in the Webhooks section. In the Panel, the following subscription fields must now be selected, click on the Add Subscriptions button. The subscription fields are:

   • messages
   • messaging_postbacks
   • messaging_optins
   • message_deliveries
   • message_reads
   • messaging_account_linking
   • message_echoes

   

3. The configuration is now complete. You should now have noted the following data in the text editor:

   • FacebookMessenger.PageAccessToken
   • FacebookMessenger.UserInfo.UserId (Optional)

   Finally, you will need the password of the Facebook App (AppSecret). Click on Settings → Basic and copy the value of App Secret into the text editor. The App Secret password is required by BBP for parameter FacebookMessenger.AppSecret.

   

Step 3: (BBP) Complete bot account configuration on Business Bot Platform¶

Finally, the configuration of the Instant Messenger account must be completed on the Business Bot platform. Therefore the data in the text editor from the previous step is needed.

1. In the BBP UI, click Channels → Instant Messenger Konto → Button Settings.

2. Now enter the values for the parameters FacebookMessenger.PageAccessToken and FacebookMessenger.AppSecret.

   

The channel account for the chatbot is now configured and will be used later when creating a chatbot instance for Facebook Messenger.