Welcome to ResponseBot’s documentation!¶
Contents:
Getting Started¶
Introduction¶
A framework to quickly develop listen-and-answer twitter bots. You can define multiple actions to be executed every time a tweet arrives.
Installation¶
$ pip install responsebot
Quick start¶
Authenticate¶
Create a .responsebot
file in your project root with your Twitter API credentials (which can be obtained after you created a Twitter application here).
[auth]
consumer_key = <consumer_key>
consumer_secret = <consumer_secret>
token_key = <token_key>
token_secret = <token_secret>
Create a handler¶
from responsebot.handlers import BaseTweetHandler, register_handler
@register_handler
class MyTweetHandler(BaseTweetHandler):
def get_filter(self):
return TweetFilter(track=['Donald Trump'], follow=['<your personal Twitter id>'])
def on_tweet(self, tweet):
print('Received tweet: %s from %s' % (tweet.text, tweet.user.screen_name))
Execute¶
$ start_responsebot --handlers-package <python path to your package/module>
Test¶
The bot should now receive tweets containing ‘Donald Trump’ or tweets posted by you. You should see ResponseBot outputs
Received tweet: <your tweet content> from <your sender tweet account>
Handler¶
For a list of methods you can define in your custom handlers, see handler reference.
Reply to tweets¶
You can reply to received tweets, see more in the tutorial’s client section
Tutorial¶
Authenticate¶
ResponseBot uses Twitter API, which requires authentication. To do so, you need to register an application with Twitter
here. Twitter will provide your app with a consumer key & secret pair, you need to
generate an additional app token key & secret pair from your app management panel. After you have the credentials,
put it under the [auth]
section in the .responsebot
configuration file in your project root (or
whichever directory you run ResponseBot from).
[auth]
consumer_key = <consumer_key>
consumer_secret = <consumer_secret>
token_key = <token_key>
token_secret = <token_secret>
If the credentials you provided are correct, when you run ResponseBot it should show like below
$ start_responsebot --handlers-package <path_to_handler>
[INFO] 2016-05-04 10:54:13 ResponseBot started
[INFO] 2016-05-04 10:54:16 Successfully authenticated as <twitter_screen_name>
Otherwise it should show an error
[ERROR] 2016-05-04 10:52:17 Could not authenticate.
You can pass the credentials as a start_responsebot
‘s option instead of using a config file:
$ start_responsebot --auth <consumer_key> <consumer_secret> <token_key> <token_secret>
Listen to public stream or user stream¶
The bot can listen to every tweets in the world (that match some keywords) or it can listen to its authenticated user’s timeline, as if it is that user. By default, the bot listen to the public stream, you can tell it to listen to the user stream as follow:
$ start_responsebot --user-stream
See more about stream and filters here.
Handler¶
To receive an incoming tweet, you need to subclass BaseTweetHandler
and implement the on_tweet
method.
You can specify what kind of tweets the bot should listen to by returning an appropriate
TweetFilter in the get_filter
method.
class MyTweetHandler(BaseTweetHandler):
def on_tweet(self, tweet):
print('Received tweet: %s from %s' % (tweet.text, tweet.user.screen_name))
def get_filter(self):
return TweetFilter(track=['Donald Trump'], follow=['<your personal Twitter id>'])
See what tweet
object contains in reference.
If you’re listening on user stream, you can catch non-tweet events (user following, etc.) as in this tutorial.
Client¶
If your application want to post a reply to the received tweet, you can use ResponseBot’s Twitter client to do so:
class MyTweetHandler(BaseTweetHandler):
def on_tweet(self, tweet):
self.client.tweet('Howdy @%s' % tweet.user.screen_name)
The client
object can also retweet, get or delete a specific tweet by ID. See reference.
Streams and filters¶
Streams¶
Twitter has three stream APIs to listen to. ResponseBot currently implement the public stream and user stream listening methods. By default the bot listen to public stream, you can tell the bot to listen to user stream by setting it in the config file:
[stream]
user_stream=true
or pass in a flag in the start command:
$ start_responsebot --user-stream
Filters¶
The public stream utilize two parameters: track
and follow
, to filter global streams (you cannot listen
to every tweets in the world, you must have either 1 keyword to track or 1 user to follow). You provide these parameters
in your handlers’ get_filter
method as follow:
def get_filter(self):
return TweetFilter(track=['keyword'], follow=['user_id'])
By default the BaseTweetHandler
returns a filter with the follow
parameter set as the bot’s authenticated user and an empty track
parameter.
The follow
parameter will not be used if you use user_stream
. See more about
TweetFilter
User event handling¶
If you’re listening to user stream, you can catch non-tweet events (user following, etc.) by subclassing the BaseEventHandler class and set it in your tweet handler, as follow:
class MyEventHandler(BaseEventHandler):
def on_follow(self, event):
pass
def handle(self, event):
super(MyEventHandler, self).handle(event)
# do sth
class MyTweetHandler(BaseTweetHandler):
event_handler_class = MyEventHandler
Currently we support callbacks on_<event>
so you can easily implementing them. You can override handle
for more customization if needed.
For a list of Twitter user events, visit this docs.
Reference¶
responsebot.handlers.base |
|
responsebot.handlers.event |
|
responsebot.responsebot_client |
|
responsebot.models |
Entity classes for various entity types for ResponseBot |
responsebot.common.exceptions |
Exceptions and errors used by Tweet Bot |