README.markdown in chatterbot-0.5.1 vs README.markdown in chatterbot-0.6.1
- old
+ new
@@ -5,18 +5,33 @@
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.
+[](http://travis-ci.org/muffinista/chatterbot)
+
+
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
+Is Writing Bots a Good Use of My Time?
+======================================
+
+Quick answer: if you're planning on being spammish on Twitter, you
+should probably find something else to do. If you're planning on
+writing a bot that isn't too rude or annoying, or that expects a
+certain amount of opt-in from users, then you're probably good. I've
+written a blog post about bots on Twitter here:
+http://muffinlabs.com/2012/06/04/the-current-state-of-bots-on-twitter/
+
+
+
Using Chatterbot
================
Make a Twitter account
----------------------
@@ -52,10 +67,76 @@
bot.reply "@#{tweet_user(tweet)} I am serious, and don't call me Shirley!", tweet
end
That's it!
+Chatterbot uses the the Twitter gem
+(https://github.com/sferik/twitter) to handle the underlying API
+calls. Any calls to the search/reply methods will return
+Twitter::Status objects, which are basically extended hashes.
+
+What Can I Do?
+--------------
+
+Here's a list of the important methods in the Chatterbot DSL:
+
+**search** -- You can use this to perform a search on Twitter:
+
+ search("'surely you must be joking'") do |tweet|
+ reply "@#{tweet_user(tweet)} I am serious, and don't call me Shirley!", tweet
+ end
+
+**replies** -- Use this to check for replies and mentions:
+
+ replies do |tweet|
+ reply "#USER# Thanks for contacting me!", tweet
+ end
+
+Note that the string #USER# will be replaced with the username of the person who sent the original tweet.
+
+**tweet** -- send a Tweet out for this bot:
+
+ tweet "I AM A BOT!!!"
+
+**reply** -- reply to another tweet:
+
+ reply "THIS IS A REPLY TO #USER#!", original_tweet
+
+**retweet** -- Chatterbot can retweet tweets as well:
+
+```rb
+ search "xyzzy" do |tweet|
+ retweet(tweet[:id])
+ end
+```
+
+
+**blacklist** -- you can use this to specify a list of users you don't
+ want to interact with. If you put the following line at the top of
+ your bot:
+
+ blacklist "user1, user2, user3"
+
+None of those users will trigger your bot if they come up in a
+search. However, if a user replies to one of your tweets or mentions
+your bot in a tweet, you will receive that tweet when calling the
+reply method.
+
+**exclude** -- similarly, you can specify a list of words/phrases
+ which shouldn't trigger your bot. If you use the following:
+
+ exclude "spam"
+
+Any tweets or mentions with the word 'spam' in them will be ignored by
+the bot. If you wanted to ignore any tweets with links in them (a wise
+precaution if you want to avoid spreading spam), you could call:
+
+ exclude "http://"
+
+For more details, check out dsl.rb in the source code.
+
+
Authorization
-------------
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
@@ -160,22 +241,11 @@
**NOTE:** You need to call `update_config` to update the last tweet your script
has processed -- if you don't have this call, you will get duplicate
tweets.
-Retweet
--------
-Chatterbot can retweet the tweets found based upon the search:
-
-```rb
- search "xyzzy" do |tweet|
- retweet(tweet[:id])
- 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
@@ -208,10 +278,9 @@
TODO
====
* document DSL methods
* document database setup
-* consider switching to Twitter gem for API
* 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