= Chatterbot

Chatterbot is a Ruby library for making bots on Twitter.  It is basic
enough that you can put it into use quickly, but can be used to make
pretty involved bots. It handles searches, replies and tweets, and has
a simple blacklist system to help keep you from spamming people who
don't want to hear from your bot.

== A quick list of features:

* Works via Twitter's OAuth system.
* Handles search queries and replies to your bot
* Use a simple DSL, or extend a Bot class if you need it
* Simple blacklistling system to limit your annoyance of users
* Optionally log tweets to the database for metrics and tracking purposes

== Using Chatterbot

=== 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.

=== 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
on Twitter (http://twitter.com/#!/Dr_Rumack):

  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!

=== Authorize your bot

If you only want to use Chatterbot to search for tweets, it will work
out of the box without any authorization.  However, if you want to
reply to tweets, or check for replies to your bot, you will have to
jump through a few authorization hoops with Twitter. The very
first time you want to setup a bot, you will need to register an
application with Twitter.  Twitter requires all API communication to be via an
app which is registered on Twitter. I would set one up and make it
part of Chatterbot, but unfortunately Twitter doesn't allow developers
to publicly post the OAuth consumer key/secret that you would need to
use.  If you're planning to run more than one bot, you only need to do
this step once -- you can use the same app setup for other bots too.

Chatterbot will walk you through what is needed to get this setup.  If
you run your bot without having an app setup, it will prompt you with
the instructions. Here's the instructions if you want to do it yourself:

1. Setup your own app on Twitter at this URL https://twitter.com/apps/new
2. Choose 'Client' as the app type
3. Choose 'Read & Write' access unless you don't need to send tweets.
4. Take the consumer key/consumer secret values, and either run your
   bot, and enter them in when prompted, or store them in a config
   file for your bot. (See below for details on this).  It should look
   like this:

  --- 
  :consumer_secret: CONSUMER SECRET GOES HERE
  :consumer_key: CONSUMER KEY GOES HERE

Chatterbot will point you at the URL in Step #1, then ask for the
same values as in Step #4.

Once this is done, you will need to setup authorization for the actual
bot with Twitter. At the first run, you'll get a message asking you to go
to a Twitter URL, where you can authorize the bot to post messages for
your account or not.  If you accept, you'll get a PIN number back.
You need to copy this and paste it back into the prompt for the
bot. Hit return, and you should be all set.

This is obviously a bunch of effort, but once you're done, you're
ready to go!

=== Configuration

Chatterbot offers a couple different methods of storing the config for
your bot:

1. In a YAML file with the same name as the bot, so if you have
   botname.rb or a Botname class, store your config in botname.yaml
2. In a global config file at <tt>/etc/chatterbot.yml</tt> -- values stored here
   will apply to any bots you run.
3. In another global config file specified in the environment variable
   <tt>'chatterbot_config'</tt>.
4. In a <tt>global.yml</tt> file in the same directory as your bot.  This
   gives you the ability to have a global configuration file, but keep
   it with your bots if desired.
5. In a database.  You can store your configuration in a DB, and then
   specify the connection string either in one of the global config
   files, or on the command-line by using the <tt>--db="db_uri"</tt>
   configuration option.  Any calls to the database are handled by the
   Sequel gem, and MySQL and Sqlite should work.  The DB URI should
   be in the form of <tt>mysql://username:password@host/database</tt> -- see
   http://sequel.rubyforge.org/rdoc/files/doc/opening_databases_rdoc.html
   for details.

=== Running Your Bot

There's a couple ways of running your bot:

Run it on the command-line whenever you like. Whee!

Run it via cron.  Here's an example of running a bot every two minutes

  */2 * * * * . ~/.bash_profile; cd /path/to/bot/;  ./bot.rb

Run it as a background process.  Just put the guts of your bot in a loop like this:
  loop do
    replies do |tweet|
      # do stuff
    end

    sleep 60
  end

=== Database logging

Chatterbot can log tweet activity to the database if desired.  This
can be handy for tracking what's going on with your bot.  See
<tt>Chatterbot::Logging</tt> for details on this.


=== Blacklists

Not everyone wants to hear from your bot.  To keep annoyances to a
minimum, Chatterbot has a global blacklist option, as well as
bot-specific blacklists if desired.  The global blacklist is stored in
the database, and you can add entries to it by using the
<tt>chatterbot-blacklist</tt> script included with the gem.

You can also specify users to skip as part of the DSL:

  require 'chatterbot'
  blacklist "mean_user, private_user"

There's also an 'exclude' method which can be used to add
words/phrases you might want to ignore -- for example, if you wanted
to ignore tweets with links, you could do something like this:

  exclude "http://"

== TODO

* A skeleton bot generator
* web-based frontend for tracking bot activity
* opt-out system that adds people to blacklist if they reply to a bot
  in the right way

== Contributing to Chatterbot

Since this code is based off of actual Twitter bots, it's mostly
working the way I want it to, and I might prefer to keep it that way.
But please, if there are bugs or things you would like to improve,
fork the project and hack away.  I'll pull anything back that makes
sense if requested.


== Copyright/License

Copyright (c) 2011 Colin Mitchell. Chatterbot is distributed under a
modified WTFPL licence -- it's the 'Do what the fuck you want to --
but don't be an asshole' public license.  Please see LICENSE.txt for
further details. Basically, do whatever you want with this code, but
don't be an asshole about it.  If you spam users inappropriately,
expect your karma to suffer.


http://muffinlabs.com