Chatterbot: A Ruby Library for Twitter Bots

Introducing Chatterbot, a ruby library for producing bots.

Features

• It makes setting up Twitter OAuth permissions very easy. The included chatterbot-register script will walk you through authorization in a couple of steps and generate a skeleton script for your bot.
• It has a very simple DSL for generating basic bots. Here's a basic but functional example for an actual bot:

• 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 very basic macro system -- if you reply to a tweet with your bot, and put "#USER#" in the reply string, it will replace that with the name of the user you're replying to.
• 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.

Setting up a Bot

Make a Twitter Account

First thing you'll need to do is create an account for your bot on Twitter. That's the easy part.

Install Chatterbot

gem install chatterbot should do the trick.

Run the Generator

Chatterbot comes with a script named chatterbot-register which will handle two tasks -- it will authorize your bot with Twitter and it will generate a skeleton script, which you use to implement your actual bot.

Write your bot

Chatterbot has a very simple DSL inspired by Sinatra and Twibot, an earlier Twitter bot framework. Here's an example, based on @dr_rumack, an actual bot running on Twitter:

    require 'chatterbot/dsl'
    search("'surely you must be joking'") do |tweet|
      reply "@#{tweet_user(tweet)} I am serious, and don't call me Shirley!", tweet
    end

Or, you can create a bot object yourself, extend it if needed, and use it like so:

   bot = Chatterbot::Bot.new
   bot.search("'surely you must be joking'") do |tweet|
     bot.reply "@#{tweet_user(tweet)} I am serious, and don't call me Shirley!", tweet
   end

That's it!

Bots in Action

You can check out the bots I've written on my Twitter Bot page, and there's a bunch of relevant stuff tagged as 'twitter' on muffinlabs.

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