Twitter’s ubiquity and well-documented API make it great for interactive projects and monitoring services. As it so happens, cats are also very interactive, so I figured I’d become a cat lady of the internet and make a twittercat.

A twittercat is a bot that runs a Twitter account, tweeting cat-like things periodically, and at whoever mentions or replies to the twittercat. To start, let’s answer why you would build such a silly thing, and finish off with how to do it yourself. If you want to skip to the details, check out the bot’s source and its twitter.


Twitter bots are superb for making information available and interactive, such as by calling out racists, sexists, and people editing Wikipedia from within the British Parliament. Twittercat is an example of how to build such a bot, and integrate it with dynamic data sources.

Our twittercat stores its personality in Orchestrate, reading it when needed. For static data like our cat’s personality, this is overkill. But if you wanted a bot constantly monitoring a site’s status, or the weather, or the Portland Police, it becomes critical to separate the logic that collects data from the logic that broadcasts it to Twitter. That separation means failure in either doesn’t halt the other, while allowing you to hook in other data sources or bots to interpret it as you please.

Twittercat selects items from its Orchestrate collection at random, like this:

function random () {
  // get number of responses
  return db.newSearchBuilder()
  .then(function (res) {
    return res.body.total_count;
  // generate a random number
  .then(function (count) {
    return Math.floor(Math.random() * count);
  // return that response
  .then(function (offset) {
    return db.newSearchBuilder()
  .then(function (res) {
    return res.body.results[0].value;

But if you wanted to get the latest data instead, just swap that function out for something like this:

function latest() {
    return db.newSearchBuilder()
    .then(function (res) {
        return res.body.results[0].value;

That implementation assumes the items in your database have lexicographically ascending keys, which by default, Orchestrate does.


For simplicity, our twittercat’s data source is a static JSON file we’ll upload into Orchestrate using orcup. To get orcup, run this:

npm install -g orcup

The twittercat’s personality file looks like this:

    {"text":"*chases an invisible something*"},
    {"text":"*rubs against furniture*"},
    {"text":"*rubs against your laptop*"},
    {"text":"*rubs against your cup, knocking it off the table*"},
    {"text":"*knocks your pen away from you; glares at you*"},
    {"text":"*sits on your laptop*"},
    {"text":"*blinks, slowly*"},
    {"text":"*sits on the roomba as it roves about, surveying the kingdom*"},
    {"text":"*flicks tail angrily*"},
    {"text":"*purrs loudly, interrupting conversation*"},
    {"text":"*sits, adorably*"},
    {"text":"*chases the red dot*"},

To get it into Orchestrate, run this:

orcup -a YOUR_API_KEY -c responses PATH/TO/PERSONALITY.json

Now your bot has a personality. Congratulations!

If you want to use a custom data source, just make sure it goes into the responses collection. That’s where the twittercat reads from.

Now then, let's actually deploy our twittercat:


To deploy your Twitter Cat, you’ll need these:

Now, get the repo. In a terminal, run:

git clone
cd twittercat

Then, set your environment variables. Rather than a hardcode of sensitive settings, like the bot’s Twitter authentication credentials and Orchestrate API key, we store them as environment variables using Heroku’s .env file.

So, with a text editor, open up or create a .env file and add values like this:


To get those credentials from Twitter, follow these steps:

  1. Enable mobile updates so your bot can post tweets.
  2. Create an application.
  3. Click “Permissions.”
  4. Under “Access”, select “Read, Write and Access direct messages”, and click Update Settings.
  5. Click “manage API Keys.”
  6. API key is your TWITTER_API_KEY.
  7. API secret is your TWITTER_API_SECRET.
  8. Click “Create my access tokens.”
  9. Watch this seal play in the snow while you wait for your access tokens to generate.
  10. Refresh the API keys page; your access tokens should appear.
  11. Access token is your TWITTER_ACCESS_TOKEN.
  12. Access token secret is your TWITTER_ACCESS_TOKEN_SECRET.

To get your API key from Orchestrate, follow these steps:

  1. Sign up.
  2. Create an application.
  3. Look! An API key!

Once you’ve got your credentials set up, we’ll need to give our twittercat a personality — a bank of responses to use. To do that, we’ll use orcup.

Now we’ll use Heroku to create a web server and push our configuration values to it:

heroku create
heroku plugins:install git://
heroku config:push

Finally, push your project to Heroku:

git push heroku master

Witness! Your Twitter Cat is live.

Next up

All through the making of the twittercat, I’ve been awwww-ing at my automated pet, but the project is most important as a demonstration of what you can do with bots and databases. Fork twittercat, add a dynamic data source, and have fun.