Part 1 - Getting started
So, you want to build a Twitter chatbot? Awesome! Now before you jump in, just know that there is a fair amount of effort needed to build the chatbot and you’ll need to be familiar with (or learn!) the following:
Webhooks. You’ll need to learn about webhooks (here’s a primer). There is some (fun) discovery to do there if you’re unfamiliar.
Deploying a web app. You must learn the basics of implementing and deploying a basic web app. Here are some helpful tutorials:
While developing your chatbot it is very handy to be able to receive Twitter webhook events with a local server (e.g. your own laptop!), as an alternative to coding and debugging on a remote, cloud-hosted server. Tunneling tools like ngrok are highly recommended.
The Twitter API. There are at least three Twitter API endpoints that your chatbot app should integrate.
- Account Activity - This webhook-based (!) API sends real-time "events" for subscribed accounts. The chatbot events of interest are incoming Direct Messages with user requests and scores.
- Direct Message - This API provides a private communication channel, along with essential user-interface support such as Welcome Messages. Be sure to set your chatbot's Twitter account to have open Direct Messages, meaning you can receive Direct Messages from Twitter users that do not follow you.
- Post Tweet - Many chatbots support public interactions. In our case, we wanted to Tweet out updated leaderboards during the tournament and also post shoutouts to teams when they posted scores under par.
If you are unfamiliar with these endpoints, check out the documentation links above.
You’ll need an approved Twitter developer account and a Twitter App in order to integrate with the necessary Twitter endpoints. To learn more about how to establish access to the Twitter chatbot endpoints (Account Activity, Direct Message, and Post Tweet) and more Python-environment details, see the project README and code at https://github.com/twitterdev/live-leaderboard.
So, what comes first? The server or the web app? Both come early in the prototyping process, and in our case, we built out the Flask web app relatively quickly (more details below).
Meanwhile, we figured out the tunneling necessary to enable events coming from the Twitter webhook publisher to arrive on our development laptops. We ended up using the ngrok tool and quickly had the development environment needed. You should definitely plan on setting up this ability to jumpstart development with your own local environment, before deploying on a 'real' server.
We started out with the free 'sandbox' version of the Premium Account Activity API, which supports a single webhook to be registered (details on that below). If you are building a chatbot on your own, this works well. If you are working on a team, and are developing with multiple local environments, it requires coordination to share a single webhook. Unless you upgrade to a paid tier that supports multiple webhooks, you will need to repeatedly delete and re-register your webhook.
Next, we'll take a code tour of the Flask-based web app for the live leaderboard prototype.
Building a simple Flask web app
Coming into this project, we had experience building a Ruby-based chatbot (@SnowBotDev) using the Sinatra web app framework. We wanted to use Python for this project, so we decided to build the web app using the Python equivalent, Flask. Luckily, the two frameworks are similar enough that our previous Sinatra experience helped us to get up and running quickly with Flask. Regardless of the web app framework you choose, there are three "routes" that you should plan on supporting:
- GET /webhook - This path is used to first establish the connection between Twitter and your web app. Once established, Twitter will "challenge" your authenticated "ownership" of the web app on a regular basis. See below for more details.
- Note: While the 'webhook' path is a reasonable default, this path is up to you. If you are consuming other webhook events, this could be something like "twitter_webhook".
- POST /webhook - The path where Twitter will send account events via the Account Activity endpoint.
- Note: the "webhook" path can be what you want. A key point is that this path needs to support both GET and POST HTTP methods.
- GET / - The default 'home' path of your web app. Supporting this route is optional, but it gives you the chance to serve up 'home page' information about your chatbot.
When using Flask, here is a simplified look at the web app code: