Anyone following along, or who has checked out the code, has probably found a few bugs in the Chatterbot library. Anyway, I have converted almost all of my current bots to use Chatterbot. In the process of that, I found a bunch of bugs, and they should mostly be fixed now. Replies to tweets weren't being posted properly, and if you were using the database to store config information, that wasn't quite working either.

I also made a new bot which replies to anyone asking a question starting with "mirror mirror on the wall":

And here's the code, if you want to get an idea of how to use chatterbot:

Writing a Twitter bot is fairly easy, but jumping through the hoops required to actually get it posting is a real drag. Twitter switched their API authorization to OAuth in 2010. They require anyone using their API to post tweets to do so via OAuth. You can get some technical details about this on their page Authenticating Requests with OAuth. Here's a quick taste:

To use the Twitter API, the first thing you have to do is register a client application. Each client application you register will be provisioned a consumer key and secret. This key and secret scheme is similar to the public and private keys used in protocols such as ssh for those who are familiar. This key and secret will be used, in conjunction with an OAuth library in your programming language of choice, to sign every request you make to the API. It is through this signing process that we trust that the traffic that identifies itself as you is, in fact, you.

Here's how to setup an app that you can use to run chatterbot:

First, go to Twitter's Register New Application page. You need to be logged into Twitter at this point, but you do not need to be logged in as your bot. Fill out this form (click to make biggish):

Fill out the form with entries like this:

• Application Name: You can name it anything you want.
• Description: Put whatever you like here
• Application Website: Got a website? Put it here
• Organization: Anything should be fine
• Application Type: Important: choose Client here
• Default Access type: choose Read & Write if you want to send Tweets. Chatterbot doesn't support Direct Messages, so there's no point in choosing that option.

When this is done, you have successfully setup an app! You'll get a page with a bunch of API key information.

Under "OAuth 1.0a Settings", make a note of the Consumer key/secret values. Make sure you don't use the @Anywhere Settings key by mistake. You want these values:

OK, now run your bot script. Chatterbot will detect that it doesn't have your consumer key/secret, and will ask you to enter them:

**** API SETUP TIME! ****
Hey, looks like you need to get an API key from Twitter before you can get started.
Please go to this URL: https://twitter.com/apps/new

Choose 'Client' as the app type.
Choose 'Read & Write' access.

Paste the 'Consumer Key' here:
Paste the 'Consumer Secret' here:

Unless you mis-copy the values, or something goes wrong, you'll get another prompt, to authenticate your bot itself to use your app. To do this, login to Twitter as your bot, then follow the instructions:

Please go to the following URL and authorize the bot.
http://api.twitter.com/oauth/authorize?oauth_token=xyz123
Paste your PIN and hit enter when you have completed authorization.

Twitter will show you a screen like this:

If you authorize the app, you'll get a PIN number:

Paste that into chatterbot and hit Enter. Chatterbot will take that PIN, and use it to get the key/secret the bot needs to use the Twitter API. That's it! Chatterbot will save your config entries to a settings file, and you shouldn't need to do this again. If you want to setup multiple bots, you can re-use the app key/secret again, but you will need to go through the app authorization process and get a new PIN key.

This is all a bit of a pain, but after you've done it once or twice, it's not too big of a deal.

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

Copyright (C) 2011 Colin Mitchell 
Derived from WTFPL, Copyright (C) 2004 Sam Hocevar 

 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

  0. You just DO WHAT THE FUCK YOU WANT TO.
  1. 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.

Interesting post on Lawyers, Guns and Money called The Dustbin of Twistory, about a dataset of all the tweets from last Sunday night, before Obama's speech about bin Laden. Apparently Twitter is claiming a violation of their terms of service, which prohibit distributing any Tweets without their permission -- as the blog post says, every time a blogger takes a screenshot for a tweet, they are in violation of this clause.

As a provider of a service that aggregates tweets, and also some bots, this is a little disturbing. Twitter has built a powerful service on the backs of developers who made interesting and useful tools via their API. Now they are slowly pulling back on this, and restricting access to their data, and telling developers that they should basically drop dead and stop making other clients. It's really frustrating to see a relatively cool service piss on all the people who have tried to make it just a little bit better.