How to integrate an Amazon Lex chatbot with Facebook Messenger
A step-by-step practical guide to service integration
Amazon Lex enables you to quickly build a chatbot in a few minutes. A few months ago, I tried to integrate a Lex chatbot with Facebook — and spent way too long because of the poor documentation and guidance.
To help save you some time and effort, this blog explains how the integration works and provides a simple and updated step-by-step guide for building your own chatbot using Amazon Lex and Facebook Messenger.
How does the integration work?
The overall integration is fairly straightforward. To get started, a developer simply creates a Facebook Page and a Facebook App. A page visitor communicates to your Facebook App by means of Facebook Messenger.
On the backend, the Facebook App sends and receives message events to Amazon Lex — this enables visitors to have back and forth communication with your Facebook App.
The Facebook App is subscribed to the Facebook Page and listens for events. Whenever a visitor sends a message to the page by means of Facebook Messenger, a webhook event is sent to the Facebook App.
The Facebook App can subscribe to variety of page events. For example, to receive messages the Facebook App must be subscribed to the following page events: messages, messaging_postbacks.
Without Lex integration, the developer needs to build their own webhook implementation to respond to these events. As an example of webhook implementation, developer can use Facebook Starter Project and must to deploy it somewhere.
However, Lex can abstract this level of difficulty away by providing a webhook implementation. To do this, Lex provides an integration channel that developer can use to connect with their Facebook App. With this approach, a developer can focus on building the bot logic — without worrying about creating their own webhook implementation.
Keeping it simple
To integrate Amazon Lex with Facebook, the current Lex documentation redirects users to Facebook’s Quick Start Tutorial. There, you are instructed to create your own webhook implementation and then host it somewhere.
You don’t need to do this. You can integrate Lex and Messenger without deploying a separate application! There are also a few other points in the tutorial which are confusing, and their documentation is very poor.
In this step-by-step tutorial, we’ll walk through all the relevant points with a simple guide to integrating these services for your chatbot.
Step-by-step guide
1. Get started by creating an Amazon Lex bot of your choice. Amazon has some good instructions for creating example bots.
2. Create a page on Facebook. You must do this by using your normal Facebook account that you use daily; otherwise, Facebook might ban your account as a fake account, and you will lose access to all your apps. The process is very straightforward.
For the sake of this tutorial, you can choose “Community or public figure” for your page, and then you can choose page name as well as a narrower page category. We will use this page in later steps.
3. Go to Facebook Developers page and log in with your normal Facebook account, if you already aren’t logged in. Don’t create a separate developer account, otherwise Facebook might consider it as fake and ban your account(s).
4. Create a new App. At the moment, you can do this by clicking on My Apps on the top right corner, and then Add New App.
5. Create a new App ID by providing required information.
6. Once your app is created, Facebook redirects you to the app page and you can choose products that your app can use. If Facebook doesn’t redirect you automatically, you can go to this page by choosing your newly created app in My Apps section on the top navigation bar. Add Messenger product to your app by clicking on “Set Up”
7. Now Facebook redirects you to Messenger Settings page. In Token Generation section, choose the Facebook page that you created in step 2. Then Facebook redirects you to a new page for confirmation.
Once you confirm the prompts, it generates Page Access Token. Copy the Access Token and save it. You will need it soon.
8. While you are in the app page, on the left bar, choose “Settings” and click on “Basic” part. On this page, you can find your App Secret. Copy the value. You will need it soon.
9. Go to Amazon Lex page and choose the bot that you would like to integrate. Choose Channels from top navigation bar, and then choose Facebook on the left column. Along with other required details, fill out Page Access Token and App Secret that you got from previous steps.
Click Activate and if you have done everything correctly, you should be able to see Callback Urls on the bottom of the page. Copy the endpoint url.
To provide some clarity on this process, I have tested from Lex console. You can see the bot reaction on the right side of page, so you can see what I expect to get from my Messenger once connected with Lex. For brevity, I have created a Bot with minimum logic.
10. Go back to your Facebook app page, in Messenger settings. In Webhooks section, click on Setup Webhooks
11. In New Page Subscription page, for Callback URL field, use the Endpoint Url you got from Lex. Also fill out same Verify Token that you defined earlier. In Subscription Fields, mark at least messages, messaging_postbacks, and messaging_optins. Then verify and save it.
12. Now, in Settings page, you should see that your webhook is marked as complete. You also need to subscribe your webhook to your page’s events. Choose the page, and click on “Subscribe”.
13. Now open your page on Facebook. Press “Add a button”. It should be straightforward. You need to create a button enabling page visitors to contact you by sending message through Messenger.
14. Once Send Message button is created, hover on it and test it. As you can see, it works for me. If it doesn’t work for you, check previous steps and make sure your have done everything correctly.
15. At this point, your bot is currently in test phase, and it works only for you. To enable others to test/use the Bot, you must add them manually to your Facebook App and to your page. Go to your App, and choose Roles from left column. Then you can add different people (with various roles ) to your project.
16. Now go to your Facebook Page, then go to Settings.
17. Go to Page Roles on the left column and add project roles. If you want your team members be able to interact with the Bot, you must also add them here.
18. Now your colleague must confirm both of the invitations you sent him/her, to be able to use the bot.
Make your app public
You can bypass the manual invitation process, by submitting your Facebook App for Facebook App Review and making it public. At the moment, Facebook can take some weeks to review your app — however this might vary from some days to some months depending on the permissions you are asking.
For bot-related permissions the review-time is usually relatively short. There is no way currently to speed up the process, so make sure you are in no rush when going live with your bot. You can get updated information about Facebook reviewing process on its documentation.
From December 2018, the permissions are granted at page level, so for each page that you would like to connect with your app, you need to do the review separately. You will also need to verify either a business or pass verification for individual developers which has been available since December 2018.
Acknowledgment
I would like to thank Pinja Kuosmanen for helping me with this post! She helped me as advisor and reviewer.
Don’t waste your time trying to hack me
Before publishing this post, I deleted my Facebook App, Page and Lex app. Therefore, credentials available in the screenshots can’t bring you anywhere. So, you don’t need to waste your time trying to hack me.
