Making a Messenger Bot 101—Initial setup, Launching your first bot

Before you’d see your messenger bot saying it’s first “Hello world!” there is a surprising ton of the initial setup. Though this setup is described in the official documentation, many people find this description confusing. In this post I‘ll try to create a better 3 steps guide, that I wish I’d had when I just started.

To check if the setup is working you will need a demo-bot source code. There is an official Facebook demo-bot for node.js, though I recommend starting with my simplified version: https://github.com/gilevskaya/demo-bot. The following explanation will equally work for the both demo-bots.

To run the bot you will need the config variables:
💎 Page Access Token
💎 App Secret
💎 Webhook (Server) URL

This manual will guide you through creating a Facebook Page and App, setting up the Webhook URL, getting the required variables in this process, and finally running and accessing your chatbot.

Step 1: Facebook Page

You will need a Facebook Page to access your bot. Even if you already have a page for your product or service you probably want to create a new page for the bot testing while it’s still in the developing phase. (When the bot will be ready you can publish it to your main page).

Creating a Facebook Page and Unpublishing it

Creating a Facebook page is fairly straightforward. Choose the “Create Page” option in the top right menu in your Facebook account or press this link. Then Facebook will guide you through all the rest. It doesn’t matter what options and name will you choose for this page since this is just a page for the bot testing that only you and your bot development team will see.

About people not seeing your page. The first thing you need to do after you’ve created a page is unpublish it. Otherwise it will appear in your friends’ news feed and all the people will be able to access it. For unpublishing go the page Settings and edit second from the top option.

Press “Message Now” on your Facebook Page to talk with the bot

Now your page is ready. There is an “About” block in the right page column with a “Message Now” button inside it. It will start a dialog where your bot will live. If you’d try to send a message now, there won’t be any reply. But by the end of this manual you’ll see your bot replies here.

Optionally you can add a Profile Picture to your page. The same picture then will be your bot icon in the messenger.

Also optionally you can invite more members of your team to this page (in the Settings -> Page Roles). As it’s unpublished and otherwise people can’t access it.

Step 2: Facebook App

Creating a Facebook App

To create a Facebook App go to the https://developers.facebook.com/apps and press the green “+ Add a New App” button. Type your “App Name” and “Contact Email” in the pop-up. In the case of the Messenger bot both are for internal purpose only, so you can type whatever you want and nobody will see it except other people who will work on this bot with you.

Adding a “Messenger” Product

After your App is created, you’ll see the “Product Setup” page for this App. Scroll down to Messenger and press “Get Started”.

Getting a Page Access Token

Now you’re on the page where you set up your bot from the Facebook side. Scroll down to the Token Generation, select the Page you’ve created on the Step 1, go through the Facebook confirmations and (yay!) your 💎 Page Access Token has been generated. (The Page you chose and generated token will disappear when you’ll refresh the page, but it still will be working.) You will also need to setup the Webhooks on this page, but we’ll come back to this later.

Getting an App Secret

Go to the Dashboard (first item on the left menu). Press “Show” in the App Secret field and copy the 💎 App Secret. Now you have two out of three variables required for running the demo-bot.

Optional: If you need to add more people from your team to access this app, similar to the Page settings, go to the “Roles” in left menu.

Step 3: Webhook

The last piece of the bot setup is the Webhook. Your bot can’t connect directly to Facebook, it works the other way around. Facebook App connects to your bot and subscribes to certain changes. For connection it requires a public URL with SSL — Webhook, a link to a server (or a developer machine) where your bot runs. You need to add this Webhook to the Facebook App (you’ve created in the Step 2). Webhook URL will look like:

https://<yourchatbot.yourwebsite.com>/webhook

There is some confusion in names as Server URL and Webhook URL often refer to the same link. In this manual, I’ll call it a Webhook URL, but in the demo-bot the same link will be called a Server URL.

Getting the Webhook URL is the most tricky part, as there is a lot of different ways to do it and none of them are provided by Facebook. You will need to use some external services and the easiest way to launch your first app is to run it from your local machine and then tunnel it with the Ngrok. It will be also useful to learn how to do it because then you can use it for testing your bot before publishing.

First download ngrok for your platform and save it somewhere. Then launch it and make a tunnel for the localhost on the port 5000 (this port is used in the demo-bot, you can change it anytime):

ngrok http 5000
Ngrok output in the console

You’ll see two tunnel links to your local host. Copy the one with https, add /webhook to the end of this link and this will be your 💎 Webhook URL. Now you have all the config variables to run the demo bot.

Note that if you’re using free Ngrok account, this link will change everytime you restart it. So you’ll have to repeat all the steps that will go next with the new link.

config/default.json
{
"appSecret": < 💎 App Secret >,
"pageAccessToken": < 💎 Page Access Token >,
"validationToken": < Random_String_For_Validation >,
"serverURL": < 💎 Webhook (Server) URL >
}

Download the demo-bot source code if you haven’t already. Go to the config/default.json. Use any random string for the validation token, and App Secret, Page Access Token, Webhook URL that you got on the steps before.

Run the demo-bot. Go to the localhost:5000 or your Ngrok link. You will see the “Messenger Demo” page. Keep the bot running, you’ll need it next.

Optionally you can go this page source code and fill the missing variables. Then you will see Messenger buttons on this page leading to your bot.

Webhook Setup button in the App setting

Now all that left is to do is a Webhook Setup that we skipped above. Go back to your bot App in Facebook (https://developers.facebook.com/apps -> choose the App you’ve created -> Then Messenger under Products in the left menu). Scroll to the Webhooks and press “Setup Webhooks” button.

Setting up the Webhook

Fill in your Webhook URL with the /webhook in the end, and the same Random_String_For_Validation that you wrote in the config/default.json. Check all the checkboxes in the “Subscription Fields”, press “Verify and Save”. You will need your bot running for this to work. If you don’t see the error message then everything went great.

Subscribing the Webhook to the Facebook Page

Subscribe your Page from the Step 1 to this Webhook and you’re all set.


Try talking to your bot again. Now it will be echoing everything you send 🎉
And checkout the console output to see the more detailed info on what’s going on with your bot.


💚 Like if it worked for you :-) And please comment if you have any thoughts, questions, or suggestions on how to improve this manual.