Microsoft recently released the bot framework to create bots for various messaging platforms such as Slack, Facebook, Telegram etc. It provides a unified interface for all of these platforms so you can reach your customers wherever they are.
In this tutorial we are going to see how to create an
Echo bot using Phoenix and Microsoft bot framework for Facebook. This involves the following steps
- Creating the service using Phoenix to receive messages from Microsoft bot framework.
- Deploy the service (we will do it on Heroku).
- Registering a bot with Microsoft bot framework.
- Registering a Facebook bot and linking with Microsoft bot service.
From here on I will refer to Microsoft bot framework as MBF.
Creating the bot service
MBF expects you to implement a web API that receives a message and in response either replies with the message to send back to the messenger or just a 200 OK response if you want to send the message asynchronously later on.
I’ve build the library ex_microsoftbot which is MBF API wrapper and the phoenix_microsoftbot which allows for easy creation of the web API for MBF to connect to. We will use both of them to create the service and send messages.
1. Create the project
Let’s create a Phoenix project using
mix phoenix.new echo_bot --no-ecto --no-html --no-brunch. We use
--no-ecto because it’s just a web API and for this simple bot we don’t need any database.
mix.exs to include the dependencies
We also have to add ex_microsoftbot in the
applications list as it internally uses
HTTPotion which needs to be started.
2. Create the controller
Let’s create a controller
web/controllers/messages_controller.ex. Let’s see the code it will contain and then I’ll explain it.
use MicrosoftBot.Phoenix.Controller which will add some functions in the controller to interpret messages from MBF. You have to implement the
message_received/2 callback, which will be called when a message from MBF is received. You can return a map from it which will be sent back as JSON or if you don’t want to send back a message you can just call
resp(conn, 200, "") to send back 200 OK.
Here we implement the
message_received/2 and its second argument is of type
ExMicrosoftBot.Models.Message containing all the information related to the message. We check the
text of the message, if it is present we prepend ECHO: to it and send it back.
3. Add the route
The third step is to add the route which will use the newly created controller.
web/router.ex to add the route
microsoftbot_routes will create a pipeline which will also validate the request coming in from MBF to see if it contains the correct credentials otherwise it will return 403 Forbidden.
Lastly just add the
app_secret in the config
As we will be deploying to Heroku so we will get the secrets from the environment variables.
That is all for creating a simple echo bot service.
You can deploy it to Heroku using the official Phoenix Heroku deployment guide.
If you are lazy or curious you can click the “Deploy to Heroku” button in the github project for the echo bot for easy deployment.
Register bot with Microsoft Bot Framework
Go to Register bot and fill up the form to register your bot. Make sure your endpoint looks something like this https://YOUR_APP.herokuapp.com/api/messages. It should be
https otherwise MBF does not send over the credentials and the bot service expects any incoming request to have
Authorization header in the request with valid credentials.
Once you create the bot add the secrets to your Heroku app by running the following in terminal
MBF provides a quick way to send messages to your bot and see its JSON response. Go to your MBF bot dashboard and then in Test connection to your bot write something and send it. You should see the response with the echoed text.
Register Facebook bot
The last step is to register a Facebook bot and link it with the MBF. Go under your MBF bot dashboard and under the Add another channel click add in front of the Facebook, it will direct you to the list of things you need to do to create Facebook bot and link it with MBF. Once you are done with it, goto Facebook Messenger and search for the page created during the Facebook bot creation part. Send a message to that and see the message echoed back.
You have a complete echo bot running, sending messages to and from Facebook. You can add more channels to it if you want.
Sending message asynchronously
Currently our bot service returns back the reply we want to send back to user as part of the response, but if you have to do some computation e.g. getting weather and then send back the response , you can return 200 OK and later call the
ExMicrosoftBot.Client.send_message/2 to send message back to the user. Let’s send a delayed message to user.
Change your controller as follows
Here if the user sends a message that starts with delayed we spawn a process that waits for 5 seconds and then calls the
send_message/2 API with the message to send. The message contains to, from, replyMessageId and text fields.
In the next part of the tutorial we will use Wit.ai APIs using elixir_wit to create a bot that can chat using the chatting model created in Wit.
- Phoenix Framework