Facebook recently started the Messenger Platform that allows bots to answer messages users write to a facebook page or business.
The really cool thing about it is that you can build small applications inside messenger without asking the user to install yet another app or any information. According to facebook already 900M users have installed messenger. You can easily build a bot that saves content for users (http://m.me/hugitapp), replaces an online shop or just shows you locations nearby if you send him your location.
In this tutorial we’re going to build a pretty “stupid” bot in node.js/TypeScript that just shows you places nearby if you send him your location. For this we’re going to contact some places api in background. Let’s call him “Loco” :-)
Update: Loco is live and you can give it a try here http://m.me/locobot1
You need node.js, a yelp and facebook account.
Basic Setup — Step1
Let’s start by creating our project. I have also created a github repo with the code at https://github.com/amitevski/locobot . To follow along you can simply clone the code and checkout the current step.
So here just type “git checkout step1” in your source folder.
Then you need to install some dependencies like below and build the project (line 6) as we’re writing in typescript.
Next have a look at loco bot controller. Open src/loco.ts in your favorite editor (I use VSC).
In the code above we create our bot controller that reacts on textMessage and replies with “Hi <user.firstname> :)”. Below you can see some environment variables that we need in order to connect our bot to facebook. In line 26 we set the message for the welcome screen.
The functionality for setting up the webhook, subscribing to page updates etc. is done by botframework in background(disclaimer: I also coded botframework as I prefer MVC like code and of course TypeScript code completion :-) ).
Create the Facebook Page and App
Now comes the boring part. First go to Facebook Pages and create a page. After creating it write down the page id somewhere, this is our FB_PAGE_ID. We will need it to start our bot.
Next create a new facebook app at https://developers.facebook.com/, it doesn’t really matter which type you choose, e.g. “Website” is fine.
Once you created it open the app at https://developers.facebook.com/apps, click on “Add Product” and choose Messenger.
In the next screen select your previously created Facebook page to generate our FB_ACCESS_TOKEN. Note this token also somewhere.
Puh this was quite some work and we’re “almost” done. Next let’s spin up our bot.
Starting and verifying Loco Bot
We still need to setup the Facebook Webhooks, but before our loco bot must be running, as facebook will connect to it.
Start localtunnel so facebook can reach your local bot. And afterwards start loco. Replace with your saved credentials before starting.
If everything works as expected you should see something like this in the console running loco
Just one more step before you can send your first message to loco. Go Back to your facebook app and click “Setup Webhooks”
Then enter your localtunnel url, your FB_VERIFY_ID and check all the checkboxes. Then click “Verify and Save”. Your localtunnel and bot have to be running when clicking as facebook is connecting to your bot.
Finally you can start talking to your bot. It’s usually just a bit hard to find him. The easiest way is to open the facebook page you created and click “Message”. Click “Get Started” and loco will send you the welcome message we set.
send him some message.
Yay loco sent us his first reply :) If you don’t get an answer right away its probably some problem with the localtunnel setup which is quite unstable. Just restart both the tunnel and the bot and try again.
Getting Locations nearby — Step2
Now that our bot is running we can start making him a bit more useful.
So type “git checkout step2” in your source folder in order to follow along. You also need to update npm “npm install” as we added a yelp client.
Add following handler to our BotController in loco.ts.
The botframework we are using offers a lot of other handlers for images, links etc. But we dont need them right now. If the msg from facebook contains a location botframework will add it for you to msg.location. If you use Visual Studio Code you will automatically get autocompletion. If not you can look at the interfaces at github.
And of course we need to implement the code that gets the locations and reformats them for facebook.
So nothing special here. We get places nearby the received location from yelp. Afterwards we reformat the responses for botframework and create an Array of IBotReplyListItem.
Next you need to create a yelp account in order to get the new keys and tokens you can see in lines 5–7 in the gist above. Once logged in you should be able to get your keys here.
Ok now we’re ready. Enter “npm run build” to transpile the new code and start your bot with the new environment variables.
And don’t forget to spin up that localtunnel, otherwise no message will reach your bot ;)
Finally you can send your current location to loco and see the places nearby.
We created a simple but pretty useful bot in no time. Creating a native or webapp with same functionality would have been more complicated. Also installing a native app means more friction.
Next steps would be to actually deploy the app and if you want to use it in production you need to let facebook review your app. Depending on the overall feedback there might be a second post explaining deployment.
Besides that I’m curious to get any tips or suggestions.