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

Indices and tables