twbot2.rb - Twitter Bot Support Library in Ruby

[Japanese]

Download

twbot2.rb (new version)

twbot.rb (old version)

News

twbot2.rb, the renewed version of twbot.rb, has released. As old twbot.rb does not support OAuth, It will not work from August 31st, 2010. You can change the library from old twbot.rb to twbot2.rb with a little work. (2010.5.16)

Overview

twbot2.rb is a library for Ruby programming language, which supports making Twitter bots. This program might be said a framework.

twbot.rb especially help you make Twitter bots that get data periodically from certain place (RSS, Twitter timeline, etc.) and create updates from that data.

Requirements

A PC for executing program repeatedly with Ruby interpreter

Basis of using twbot.rb

In twbot.rb, there is a class definition of class TwBot. Class TwBot can not be used by itself, but be used with following step:

  1. Define a class inheriting TwBot.
  2. Re-define the method load_data in the new class.
    • "load_data" method have to return an array of strings. Each of array item is one message in Twitter. Messages are posted in order of array order. (That is, messages are stored in a queue.)
    • You can set arrays to the returned array's elements instead of string.(The item-of-array arrays are called "internal arrays" for convenience.) If you do so, first element of an internal array is treated as the message, and second element of the internal array is treated as the value of "in_reply_to_status_id" (message ID to be replied).
  3. Generate an instance of the new class. Arguments for the constructor("new" method) decides what to do.
    • If the first argument of method "new" is "init", twbot2.rb leads the procedure to authenticate the bot account.
    • If the first argument of method "new" is "load", messages that the bot will post to Twitter are added to list (not posted to Twitter at this time).
    • If the first argument of method "new" is "post", a message (top of the list) is posted to Twitter.

Sample code

This is a sample program of Twitter bot with twbot.rb, which posts how many replies came to the bot. (This is attached to the zip archive.)

#!/usr/bin/env ruby
# -*- coding: utf-8 -*-

$: << File.dirname(__FILE__)

require "twbot2"
require "rexml/document"

class SimpleBot < TwBot
  def load_data
    # =============================================================
    # What the bot talks should be defined in 'load_data' method.
    # This example is to fetch mentions to the bot and notify them.
    # =============================================================
    
    # ---------- fetch replies ----------
    
    # downloading the XML
    response = auth_http.get("/1/statuses/mentions.xml")
    xml = REXML::Document.new(response.body)
    
    # extracting only message IDs of the XML
    mentions_ids = xml.elements.to_a("/statuses/status/id")
    mentions_ids.map!{ |x| x.text.to_i }
    
    # ---------- exclude old replies ----------
    
    # If you create a new key in the Hash @config,
    # this will be kept in the config file.
    @config['last_id'] ||= 0
    
    # keeping the newest ID among the downloaded mentions
    new_last_id = mentions_ids.first
    
    # excluding the IDs representing old messages
    mentions_ids.reject!{ |m_id| m_id < @config['last_id'] }
    
    # renewing the newest ID
    @config['last_id'] = new_last_id
    
    # ---------- return the message to be posted ----------
    
    # The return value must be an array.
    # If you specify strings as the return value,
    # the bot will talk it as it is,
    # when you run 'ruby simplebot.rb post'.
    
    ["#{mentions_ids.size} new replies found!"]
  end
end

self_path = File.dirname(__FILE__)
ARGV.each do |mode|
  SimpleBot.new mode, "#{self_path}/config.yml", "#{self_path}/error.log"
end

This program is run by:

  1. Locate the code above (simplebot.rb), file "twbot2.rb" and directory "twbot2" in the same directory.
  2. Execute the command in a command line "ruby simplebot.rb init" to authenticate the bot account.
  3. Execute the command in a command line like "ruby simplebot.rb load" or "ruby simplebot.rb post". To add a message of reply count, specify "load". To post the message, specify "post".

What is important is that you have to write code for creating messages posted by the bot.

Reference

Additional Information

Revisions

Version 0.10(2008.10.26)
First version
Version 0.11(2008.12.14)
Being able to post same messages successively (As this change, key ["last_post/"] is added to the variable @config)
Version 0.12(2008.12.18)
Showing "from twbot.rb" with twbot.rb's post (since Maraigue got permission from Twitter administrator)
Version 0.13(2009.03.09)
  • Being able to work with Ruby 1.9
  • Being able to post messages with "in_reply_to_status_id" status
Version 0.14(2009.04.14)
  • Extending the format of the 1st parameter of TwBot#new (Format like "post=5,2" is available instead of "post".)
  • Adding a class method TwBot.remove_reply for Renewed specification of Twitter replying
Version 0.15(2009.12.10)
  • Updating TwBot.remove_reply as full-width "@"'s begins specifing replies
  • Added methods for following management (TwBot#get_followers, TwBot#get_friends, TwBot#follow, TwBot#unfollow, TwBot#following_status, TwBot.retrieve_followers, TwBot.retrieve_friends, TwBot.make_following, TwBot.make_unfollowing, TwBot.check_following)
Version 0.20(2010.05.16)
Newly written to use OAuth

Copyright

(C)2008- H.Hiro(Maraigue)

twbot.rb can be copied and changed under (new) BSD License. BSD License
Simply, this script is distributed under no warranty, and re-distributed version have to contain original copyright information.

To report about this script, talk to Twitter/h_hiro, or send mail to main (AT) hhiro.net .

Back to top
(C)2008- H.Hiro (Maraigue / Sinryow)