Here's a howto guide on creating and running a bot on the Facebook messenger platform using Clojure on the Heroku PaaS platform. Part inspired from this post by Abhay.

The messenger platform requires the use of a HTTPS URL, and the URL needs to be available and accessible to test against. I found that using Heroku solves multiple goals, no need to expose the URL via ngrok+localhost, nor is getting a SSL certicate required since Heroku dynos are available on an HTTPS URI.

Steps:

Create a Heroku free tier account

• Heroku has a free dyno tier of that allows running an application for 550 hours.
• We need to get a Heroku account and download the Heroku command line toolbelt.

Create a Facebook App and page

I found the terminology a bit confusing at first.

• The FB App(lication) is what hosts the chatbot within the Facebook platform. The primary task of the App is to provide a chat-like user interface.
• A Webhook (as named by Facebook) is the chat service hosted on an external web service. When a user types a message, the Facebook App "forwards" the message to the web service URI (via an HTTPS POST message with a particular format). The web service can respond to a message by POSTing back to a Facebook URI.
• The chat web service is a REST-style web service that reads and writes JSON encoded data.
• Additionally, for the FB App to be "discovered", it needs to be associated with a Facebook page. It appears that a user or a page on Facebook is the primary 'actor' with which other human actors interact. When a user navigates to a page on Facebook and clicks on "Message", Facebook forwards the messages to the App (which has been associated with that page).

Create a Page and verify token

• There are 2 kinds of tokens required:
• A verify token is what FB uses to verify that the webhook is valid and authenticated
• A page token is used to authenticate the connection between the App and the Page.
• Note that the page tokens are not displayed on Facebook, if you haven't had it stored, you might need to regenerate a new token

Clone the repo and deploy it

• The repo is available at Github
• Run lein test to verify that tests pass
• Deploy the App from instructions at the link below.

Config vars

• The page token and verify token are included in the HTTP responses and need to be accessed by Clojure Application.
• The Environ library is used to load these tokens. Typically, Environ loads this from a .lein-env file.
• Since Heroku bundles the jar as an uberjar, the tokens need to be packaged into this uberjar to be accessible on the Heroku dyno.
• A cleaner way to set the token's values is to use Heroku's config, which can be set from the command line.

Testing the App is described in Part II