twbot3.rb - Twitter Bot Support Library in Ruby



"Twitter" was renamed to "X", but in this document it is called "Twitter" for higher identifiability.


Current versions

Defunct versions (no longer accessible to Twitter)


twbot3.rb is newly released, after most of Twitter API v1 features are unavailable. (2024.6.8)

twbot2.rb version 0.21 is released, working with Twitter API v1.1. APIs of twbot2.rb are refined, however, programs for library version 0.20 still works with library version 0.21. The document for version 0.21 is available at GitHub wiki page. (2013.2.5)

Since direct message APIs will be unavailable with old OAuth tokens since July 2011, please re-authenticate accounts if you use direct message APIs. To re-authenticate a user USERNAME, first remove 'users/USERNAME' entry (including 'token', 'secret' or like section under it) from config.yml, then execute 'ruby BOT_SCRIPT_NAME.rb add=USERNAME'. (2011.6.28)

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)


twbot3.rb is a library for Ruby programming language, which supports making Twitter bots: mainly managing OAuth tokens. This program might be said a framework.

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


A PC for executing program repeatedly with Ruby interpreter

Sample code

A bot tweeting random greetings

require "./twbot3""config-file.yml", "log-file.log").cui_menu do
  # Define what the bot tweets here  tweet_list = ["Good morning", "Good afternoon", "Good evening"]
  [tweet_list[rand(tweet_list.size)]] # return as an arrayend

A bot tweeting RSS contents

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

RSS_URL = ""

require "cgi"
require "open-uri"
require "./twbot3"

SELFDIR = File.dirname(__FILE__)"#{SELFDIR}/config-rsspost.yml", "#{SELFDIR}/error-rsspost.log").cui_menu do
  # Download RSS
  buf = nil
  open(RSS_URL){ |file| buf = }
  result = []
  @config["already_retrieved"] ||= ""
  newest_entry = false
  # Retrieve entries in RSS
  # (It is better to use REXML library; this program omits it
  # for simpleness.)]
  buf.scan(/<item.*?>.*?<\/item>/m).each do |entry|
    # Extract titles and URLs of entries from downloaded RSS
    title = nil
    entry.scan(/<title>(.*?)<\/title>/){|tmp| title = CGI.escapeHTML(tmp[0])}
    link = nil
    entry.scan(/<link>(.*?)<\/link>/){|tmp| link = CGI.escapeHTML(tmp[0])}
    # Ignore entries already retrieved by this program
    # NOTE: @config["..."] values are kept for the next running
    # of the program.
    break if link == @config["already_retrieved"]
    # Adds a message to the list to be tweeted later.
    # Because RSS stores entries from newer one, to post messages in the
    # original order, the message have to be added to the bottom of the
    # array 'result'.
    result.unshift(TwBot."[AUTO POST] #{link} #{title}") if title && link
    # Keep the URL of the newest entry in the data retrieved now
    unless newest_entry
      newest_entry = true
      @config["already_retrieved"] = link
  # Set logged message
  @logmsg = "(#{result.size} post added)"
  # Return the result
  # NOTE: the returned value must be an array of tweets when a bot
  # is constructed (called by 'ruby SCRIPTNAME.rb load')
More details: maraigue/twbot3.rb · GitHub


Help for twbot3.rb version 0.30 (English)


Additional Information


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
Version 0.21(2013.02.05)
Remade for Twitter API v1.1.
APIs of twbot2.rb are refined.
Version 0.22(2015.10.30)
File lock for configuration file is added.
Version 0.23(2018.07.29)
  • Removed the application key/secret (application-specific strings needed for accessing Twitter API) of twbot2.rb in the default setup, since Twitter will introduce the limitation of tweets per application (in addition to the existing limitation of tweets per account) on September 10th, 2018. (See New developer requirements to protect our platform (Developer Blog, Twitter))
  • Flushing the standard output when outputting prompt messages.
Version 0.30(2024.06.08)
Updated to use Twitter API v2


(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) .

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

Creative Commons Attribution-Noncommercial-NoDerivs (表示-非営利-改変禁止) 2.1 Japan Otherwise noted, contents in are available under Creative Commons Attribution-Noncommercial-NoDerivs 2.1 Japan.