So what is a Messenger bot, really? Conceptually, Messenger bots are simple webhook handling services that can be used on any technology you prefer. I personally prefer Rails, and in this introductory tutorial I would like to share some concepts on how fun it can be to build Facebook messenger bots on Rails.

Everything Starts From An Idea

Currently there are a bunch of naive bot examples that show weather forecasts, deliver food, etc. I wouldn’t say that weather forecast bot examples are boring, but I would like to build something where I can play with as many interactions as possible and touch some fancy stuff from the Facebook Messenger API.

So what are we going to build? We want to build something that’s not boring yet is “doable” at the same time. The first thing that came to my mind was the concept of a “life log” where you are prompted with a simple question and respond with a small sentence about your day. Sounds pretty simple, right? Let’s start by describing our user flow:

When I write message to the bot, I would like to start the conversation by getting an introductory message.

After that, I would like to see what the bot can do.

Then, I would like to setup it.

it. During this setup phase, the bot will prompt me when I would like to be prompted to give life log sentence each day.

the bot will prompt me I would like to be prompted to give life log sentence each day. Then, I would like to be asked about my mood and be allowed to pick from an emoji list.

After that, the bot will respond with some clever answer and store this message for future reference.

This flow looks very simple and straightforward, so how can we make it fancier? Let’s add an additional requirement. I would like to ask the bot in natural language, “What I did two days ago?” and have the bot send me a clickable button that will open web view of my activity page.

Preparing Our Toolbox

Thanks to the great Ruby and Rails community, we will not start building our own Facebook messenger API payload parsers, but instead use a very good library hyperoslo/facebook-messenger, which gives the most important toolset out of the box. Returning to our requirements, we will also need to find out how to parse natural language and provide proper responses from the bot to the end user. Fortunately, for this we can leverage some awesomeness of wit.ai which gives a great natural language api absolutely for free.

Building Our Dummy Bot

We have the needed toolset, so now the main question is, “How do we get started?” Let’s think about our checklist:

Facebook requires us to have a separate Facebook page, and a Facebook app that can be created in the Facebook developer center.

To start processing messages, we will need a service that will handle webhooks sent from Facebook. For this purpose will write our Rails app.

Our bot requires a persistence layer to “remember” all settings and data the we will provide from conversation flow, so we will need a database, in our case we will use heroku.

Setting Everything Up On Facebook’s Side

First, you need to create your own Facebook page which will represent your bot. You can do that by visiting this link.

In order to start working with webhook processing we need to create a Facebook app. This can be done by following developers.facebook.com.

After you have created your app, you will need to add Messenger platform support. This can be done by clicking the “add product” menu item at the sidebar. Now you have almost everything you need from Facebook’s side, we will return to the developer center a bit later. Now we need to dive into our Rails app.

Building A Simple Rails App

I will not describe everything that you need to do for setting up a Rails app because I expect you are already familiar with Rails and can create new Rails app by yourself. If you don’t want to do this, you can also clone the repo listed above where all the starter files are already provided. After you setup rails and all required dependencies, you will need to make sure that all required dependencies works properly.

Make sure that you’ve added gem 'facebook-messenger' to your Gemfile as we are using a custom directory for bot files, so we need to make sure that Rails “knows” about it.

Add this at config/initializers/messenger_bot.rb

In order to successfully communicate with Facebook’s api from your dev environment, you need to share access to your local machine somehow. For this purpose, I would suggest using the tool ngrok. Run your Rails server using bundle exec rails s and then open new shell and run ngrok http 3000 where 3000 it can be any port where your rails app is currently bound. Quick note: if you are starting your app at first time don’t forget to run rails db:create

The next thing you will need are tokens from Facebook’s developer console. You need to get: a page access token, a verify token for incoming webhooks, and an app token. You can get all of these tokens from the developer console.

As I have provided .env support to the starter repo you can add .env file and include the following keys there.

ACCESS_TOKEN=YOURTOKEN

APP_SECRET=YOURSECRET

VERIFY_TOKEN=YOURVERIFYTOKEN

After you have successfully obtained all the required tokens, you should add your URL provided by ngrok to the Facebook webhook settings.

Now, let’s write some basic code to test if everything works.

We can restart our Rails server, find our Facebook page name in Messenger, and simply write a message. In our case, let’s use hello bot . According to the code example, we should respond with a simple: hello human

Yay! We have basic skeleton for our bot!

What’s Next?

In this article, we have successfully defined the scope of our small project, provided basic bot structure, and prepared all required dependencies so we can move forward. In the next part of the series, we will deep dive into implementation of the setup phase. We will touch different Messenger specific UI elements and even implement basic natural language processing support. See you in the next part!