Build a Facebook Messenger chatbot in Laravel with BotMan Studio 2.0

With BotMan it is really easy to setup a Facebook chatbot. This week the new 2.0 version was released. We will checkout how to setup a Facebook Messenger chatbot in this new version with BotMan Studio.

Preparations

Before we start, make sure to have these things prepared:

  • PHP7+ environment
  • ngrok or Laravel Valet to get a public URL to your BotMan app
  • A Facebook Page where your chatbot will live
  • A Facebook App which we will configure together

Install BotMan Studio

The easiest way to install BotMan Studio is via the installer.

composer global require "botman/installer"

After that you can just install a new instance like that:

botman new botman-facebook

It is basically like the Laravel Installer. Your application is now already installed. When you use Laravel Valet you can directly check the homepage, botman-facebook.dev in my case. Here you will see the BotMan Studio welcome page.

Screenshot of the BotMan welcome page

When you click Tinker you can immediately test your chatbot. Type Hi and you should get a reply. This works because this behaviour comes with BotMan Studio. You will find the code for that in your routes/botman.php file.

  <?php
 ...
 $botman->hears('Hi', function ($bot) {
     $bot->reply('Hello!');
 });
 

Screenshot showing BotMan Tinker

Configure BotMan Studio

Now that BotMan is installed we need to configure it to work with Facebook Messenger. When you use the BotMan artisan command php artisan botman:list-drivers you will see the installed driver.

Screenshot showing terminal output for BotMan list driver command

As you can see, by default only the web driver is installed. Since version 2.0 almost all drivers live in separate GitHub repositories and you need to install the ones you need. In order to install the Facebook driver we can use another artisan command.

php artisan botman:install-driver facebook

Next to the driver this will also add a config/botman/facebook.php config file. There you’ll see that BotMan requires some data from your .env file.

Screenshot showing facebook botman config file

In order to connect our BotMan application to a Facebook app and page we need these env values: (we will add them later)

FACEBOOK_TOKEN=YOUR_APP_FACEBOOK_PAGE_TOKEN
FACEBOOK_APP_SECRET=YOUR_APP_SECRET
FACEBOOK_VERIFICATION=YOUR_VERIFICATION

Setup the Facebook app

On your Facebook Developer site go to your app and add the Messenger product to it.

Screenshot of how to add the Messenger product to your Facebook app

Now you’re able to create a Facebook Page Token. (= FACEBOOK_TOKEN from BotMan) Just select the Facebook page, where your bot will be available, and copy the token. On your apps dashboard you will also find the Facebook App Secret. Copy it as well and put the values in your .env file. You can chosse the value of FACEBOOK_VERIFICATION yourself there. We will need that in a short. Now all your .env Facebook values should be filled.

Connect BotMan to your Facebook app

In order to connect them we need to setup the webhook inside your Facebook app. You will find the options in the app’s Messenger section like before.

Screenshot of the Facebook app webhook options

There we need to select the subscription fields, so the app knows what to send to our BotMan application and the URL where to send it to. The callback URL (= webhook) is your BotMan application public URL + /botman and the Verify Token is the one you used in your .env file. For us the messages and messages_postbacks fields are fine for now. When you did everything correctly your webhook should now be successfully setup.

Note: If not, you will see a red "x" icon at the right of your Callback URL field. This means that the Facebook webook test request was not successful. Most of the times this is because the URL or the FACEBOOK_VERIFICATION is wrong. So please check them again. Also make sure that the URL is publicly reachable.

Screenshot of the webhook options

Note: Postbacks are values that will be send when you use Buttons or other Facebook templates.

The botman endpoint of your BotMan application is already setup in BotMan Studio. This is why that works out of the box. You will the code for that in you routes/web.php file.

 <?php
 ...
Route::match(['get', 'post'], '/botman', 'BotManController@handle'); 
 
Note: The webhook setup request is a GET request. Every other Facebook request will be a POST one. This is why we need hear for GET and POST requests.

After you have setup the webhook, you will be able to subscribe the app to a Facebook page. This makes sure that every message from the page will be sent through your app to your BotMan application.

Screenshot showing how to subscribe to a Facebook page

Test it out

Next we can test if everything is working like planned. So visit your Facebook page and send a message with just Hi. You should again get a reply with Hello!.

Screenshot showing a message and a reply in Facebook Messenger.

You can also write to your page through the Messenger web app. This is what I am using in the screenshot. Just search for your page there in order to write a message.

Note: While your Facebook app or page are not published, your Facebook user needs to be an admin of the page and the app in order to make it work.

Additionally we can test the example conversation, which is built into BotMan Studio.

Screenshot showing how to test the BotMan example conversation

First custom message

And in order to write some chatbot functionality ourselves, we add a custom listener to the routes/botman.php file.

  <?php
 ...
$botman->hears('It just works', function(BotMan $botMan) {
   $botMan->reply('Yep 🤘');
}); 

You will see that this works like a charm as well.

Screenshot showing first custom bot message

Conclusion

Although it seems quite easy to setup BotMan Studio and Facebook you still need to be aware of a few concepts regarding Facebook. I hope I could provide them there and this article helps you to setup your next Facebook Messenger chatbots. From here you are ready to build more and more features to your bot your own. So make sure to checkout the BotMan documentation to get a feeling of what is possible and learn new stuff.

comments powered by Disqus