Chatterbot: A Ruby Library for Twitter Bots

26 May 2011

As mentioned here on occasion, I've written a bunch of Twitter bots. The first bot was a pretty simple custom script, then the second one was a little bit improved, and so on. Eventually, I wrote a skeleton class which held most of the guts needed to run a bot, then I would just extend it as needed for actual bots.

This was fine, but not very pretty. The code was a mess, and as I added features, it just kept getting messier. People have asked for help from time to time with their own bots, and I've always been happy enough to share some code, but it wasn't sufficiently documented and was never really intended for public consumption.

So, I spent a couple evenings and spare moments cleaning up the code, documenting it, and properly testing it, and now it's available for public consumption. Introducting Chatterbot, a ruby library for producing bots.

Here are some nice things about Chatterbot:

It handles setting up Twitter OAuth permissions fairly nicely. The first time you run a bot, it will walk you through authorization in a couple of steps.
It will run searches for you -- multiple searches if you want, and you can also check for responses to your tweets. This is the main functionality of all my bots so far -- search for a phrase or some keywords, and reply to those tweets in some interesting fashion, and then also potentially reply to any mentions of your name. You can do a lot with this sort of functionality on Twitter -- it's mostly what actual humans do on it all day long.
A fairly simple, but extensible configuration system. If you just want to run a single bot, it will store your configuration data in a YAML file, and you never even need to look at it. But if you want to run multiple bots, you can setup a global config file to store several common parameters. You can also optionally store your configuration in a database.
If desired, you can log tweets to a database. This is handy for tracking your bots activity over time.
It has a blacklist system to keep you from annoying users who don't want to be annoyed, and also to make it easy to ignore tweets which have certain keywords in them.
It has a 'debug mode' so you can test the bot without sending out actual tweets.
It has a very simple DSL for generating basic bots. Here's a basic but functional example for an actual bot:

A Note About Being an Asshole

I am a big fan of the WTFPL - Do What The Fuck You Want To Public License. I decided to release chatterbot under the WTFPL, but with one alteration. I really don't want people to use this code for evil. Spamming people on Twitter is not okay. However, this code could definitely be used to aid spamming. So, I've invented the WTFDBAL. It's pretty simple -- do whatever you want with the code, but don't be an asshole:

DO WHAT THE FUCK YOU WANT TO -- BUT DON'T BE AN ASSHOLE PUBLIC LICENSE

Version 1, May 2011

Everyone is permitted to copy and distribute verbatim or modified copies of this license document, and changing it is allowed as long as the name is changed.

DO WHAT THE FUCK YOU WANT TO -- BUT DON'T BE AN
ASSHOLE PUBLIC LICENSE

You just DO WHAT THE FUCK YOU WANT TO.
Don't be an asshole. Really.

Is that enforceable? I assume not. But if you even have to ask the question, then you're probably doing something wrong.

Got questions? Did I document something poorly? Contact me here or on Github and I'll see what I can do about that.