twbot2.rb README(English)

About twbot2.rb

twbot2.rb is a Twitter bot framework combined with OAuth token manager.

Since version 0.21, the program was remade to be used non-Twitter-bot Twitter program, where twbot2.rb works as only an OAuth token manager.

Installation

gem install json    # needed in Ruby 1.8 or before
gem install oauth
gem install devnull

Then, download twbot2.rb here and put it in the same directory as the bot program's location.

Needed with version 0.23 or later

Until version 0.22, the application key/secret (application-specific strings needed for accessing Twitter API) for twbot2.rb is sepcified by default.
Since version 0.23, it is not specified by default since Twitter will introduce the limitation of tweets per application (in addition to the existing limitation of tweets per account) on September 10th, 2018.
New developer requirements to protect our platform (Developer Blog, Twitter)

1. Register an application for Twitter. Then retrieve the pair of "Consumer Key" and "Consumer Secret".
2. Open twbot2.rb, find the code set_consumer("", ""), and then input the key and the secret here.

For just trial, instead of registering the application, use the code described in the comment.

Example

We have only to define what the bot tweets as the following format:

$ cat greeting_bot.rb

require "./twbot2"
TwBot.create("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 array
end

To add the content to be tweeted to the configuration file, call with the parameter "load".

$ ruby greeting_bot.rb load

Running mode 'load'...
[2000-00-00 00:00:00 +0000]
[cui_menu:mode=load]

To post a tweet stored in "load" mode, call with the parameter "load".

$ ruby greeting_bot.rb post

Running mode 'post'...
[2000-00-00 00:00:00 +0000]
[cui_menu:mode=post]<Error in updating> A String (user name) or Hash
(parameters) is required as the argument (NilClass given)
* Perhaps you have not finished authentication. Try 'greeting_bot.rb init' to
register the default user.
ArgumentError: A String (user name) or Hash (parameters) is required as the
argument (NilClass given)
* Perhaps you have not finished authentication. Try 'greeting_bot.rb init' to
register the default user.
(snipped)

However, it fails since no user is registered in the configuration file yet. So let's initialize the configuration file with a default user.

$ ruby greeting_bot.rb init

Running mode 'init'...
============================================================
Here I help you register your bot account to the setting file.
Please prepare a browser to retrieve OAuth tokens.

Input the screen name of your bot account.
============================================================
User name >h_hiro_
============================================================
To retrieve OAuth token of user "h_hiro_":
(1) Log in Twitter with a browser for user "h_hiro_".
(2) Access the URL below with same browser:
    https://api.twitter.com/oauth/authorize?oauth_token=****
(3) Check the application name is "twbot2.rb" and
    click "Allow" link in the browser.
(4) Input the shown number (PIN number).
    To cancel, input nothing and press enter key.
============================================================
PIN number >*******
User "h_hiro_" is successfully registered.
Default user is set to @h_hiro_.
[2000-00-00 00:00:00 +0000]
[cui_menu:mode=init]

Then try again "post" mode. A tweet will be appear in Twitter.

$ ruby greeting_bot.rb post

Running mode 'post'...
[Updated!] Good afternoon
[2000-00-00 00:00:00 +0000]
[cui_menu:mode=post](A tweet has been posted)

Reference

• Constructors
  • TwBot.create - Creates an instance of TwBot
  • TwBot.new - Creates an instance of TwBot and run an action
• Running bot program
  • TwBot#cui_menu - Generates a CUI menu for program running
  • TwBot#run{ ... } - Runs the specified block
  • TwBot#load_tweet{ ... } - Runs the specified block returning a list of tweets
  • TwBot#post_tweet - Post a tweet loaded in TwBot#load_tweet
• Variables for writing bot definitions
  • @config - Contents in the configuration file
  • @logmsg - Log message to be stored in log file
  • @list - List name of tweets
• Methods for writing bot definitions
  • TwBot#user_registered? - Examines whether specified user is registered in the configuration file
  • TwBot#auth_http - Retrieves OAuth-authenticated HTTP accessor
  • TwBot#get_followers, TwBot#get_followers_ids - Retrieves followers
  • TwBot#get_friends, TwBot#get_friends_ids - Retrieves friends
  • TwBot#follow_by_screen_name, TwBot#follow_by_user_id - follows a user
  • TwBot#unfollow_by_screen_name, TwBot#unfollow_by_user_id - follows a user
  • TwBot#following_status - Retrieves whether the authenticated user follows/is followed by another user
• Utilities
  • TwBot.set_consumer - Set a consumer token
  • TwBot.remove_reply - Removes replying format from a text ("Hi, @h_hiro_" -> "Hi, @ h_hiro_")
  • TwBot.user_details - Retrieves detailed user information from a list of user IDs
  • TwBot.truncate_to_length - Truncates the end of the string if it is longer than specified length