Introduction

HippyBot is a Hipchat.com chatroom bot written in Python. It is technically just a Jabber/XMPP bot, but it has customised features for connecting to and working on Hipchat.

HippyBot includes a simple plugin API for adding commands.

Installation

There a few ways you can install Hippybot:

Download and install with setup.py::

python setup.py install

Install from PyPi::

pip install hippybot
# or using setuptools
easy_install hippybot

Configuration

There is an example configuration file distributed with HippyBot called hippybot.conf.example, copy this and edit it. You will need to add an account to your Hipchat group for the bot to connect as. While logged in as the account go to the XMPP <https://boxedice.hipchat.com/account/xmpp>_ settings page to get the details you'll need to edit the config file.

Usage

Run HippyBot from a terminal like so::

hippybot -c path/to/your/config/file.conf

To run as a background daemon use -d or -daemon::

hippybot -c path/to/your/config/file.conf -d

Optionally you can provide a path to a PID file to use with -p or --pid. Note: at present you will have to provide your own control script, e.g. for use with init.d or upstart.

You should see the bot join any channels listed in the config file. You can then target the bot with commands using the at-sign notation, e.g.::

@botname rot13 hello world

If you have the rot13 example plugin set to load (via the plugins section of the config file) then the bot will reply to you using at-sign notation with a ROT13'd (each character offset by 13) version of the text "hello world".

The bot has 2 inbuilt commands:

load_plugins: this will reload any updated plugins (note it will also reset the internal state of any loaded plugins, e.g. the counter in the mexican wave plugin). Note it does not reload the bot's configuration file and so will not load new plugins.
reload: this will reload the bot itself, reloading the configuration file, reconnecting to HipChat and reloading any plugins, in the process. Note: it does not end the main process, you would have to do that yourself from the terminal (for example if HippyBot were updated).

Plugins

There are 3 plugins currently distributed with HippyBot:

rot13: this is mostly included as an example, it ROT13s, any text spoken directly to the bot, back at the speaker.
mexican_wave: this is a fun plugin that completes a mexican wave if 2 people in a row say \o/ in a channel, e.g.::

John Smith: \o/ Joe Bloggs: \o/ Hippy Bot: \o/
udefine: look up a term on Urban Dictionary <http://urbandictionary.com/>_, the first 3 definitions will be posted back to the channel. Warning: many terms are NSFW.

To instruct the bot to load a plugin include the plugin's module path in the load field of the plugins section of the config file, e.g. to load the mexican_wave plugin which is located in the file mexican_wave.py in hippybot/plugins/, you would write it as::

[plugins]
load = hippybot.plugins.mexican_wave

To load a plugin named my_custom_plugin that you have installed into your python path under myhippybotplugins in a filename (or module) named my_custom_plugin.py you would append (on a new line, notice the indentation)::

[plugins]
load = hippybot.plugins.mexican_wave
       myhippybotplugins.my_custom_plugin

To search for plugins in paths outside of hippybot, you can use the load_path option::

[plugins]

load_path = /absolute/path/plugins
    hippybot/plugins
    plugins
    another/relative/path

Plugin API

HippyBot includes a very simple plugin API. To add commands to HippyBot you just need an importable Python package (e.g. a directory in the PYTHON_PATH that includes a file named __init__.py), and place your plugin in it's own Python file (the ROT13 plugin lives in rot13.py).

You then can include a function that matches the same name as the file and is the same command you want to register, and use either the botcmd or directcmd decorators::

hello_world.py

from hippybot.decorators import directcmd

@directcmd def hello_world(bot, mess, args): return u'Hello world!'

This registers the command hello world as a direct command, that means the text "Hello world!" will be directly spoken back to the user using at-sign notation. The botcmd decorator on the other hand will respond in the channel without targetting the original speaker. By default these function based plugins only support direct commands (spoken to the bot using at-sign notation), however you can create more complex plugins with greater control using class based plugins.

To create class based plugins create the Python module as normal, with any descriptive name you want, and include a class named Plugin in the module, for example the hello world plugin can be written like::

# hello_world.py
from hippybot.decorators import botcmd, directcmd

class Plugin(object):
    global_commands = ['hello_world']
    command_aliases = {'hi!': 'hello'}

    @botcmd
    def hello_world(self, mess, args):
        return u'Hello world!'

    @directcmd
    def hello(self, mess, args):
        return u'Well hello there..'

This uses 2 special properties:

global_commands: a list of command method names that can be triggered without targetting the bot using at-sign notation (just say the command in the channel without mentioning the bot).
command_aliases: dict of command aliases and the methods they map to, this is a way of triggering a command from a string that can't be used as a Python method name (e.g. using special symbols such as the "\o/" trigger used in the mexican wave plugin).
all_msg_handlers: a list of handler method names that will be passed all incoming XMPP message objects regardless of type as. This can be used for low-level hanbdling of Jabber messages without using the higher level message handling of jabberbot or hippybot.

HipChat API

HippyBot includes a very simple object orientated wrapper for the HipChat API <https://www.hipchat.com/docs/api>. To make use of the API you need to create an API key <https://www.hipchat.com/groups/api> and enter that into the config file under the section hipchat, as an option called api_auth_token, e.g.::

[hipchat]
api_auth_token = xxxxxxxxxxxxxxxxxxxxxxxx

If you are using self-hosted Hipchat service, set up something like this::

[hipchat]
api_server = api.example.com
api_auth_token = xxxxxxxxxxxxxxxxxxxxxxxx

Then you can access the wrapper via the api attribute on the bot instance, e.g. from within a command method on a plugin class::

# hello_world.py
from hippybot.decorators import botcmd

class Plugin(object):
    global_commands = ['hello']

    @botcmd
    def hello(self, mess, args):
        channel = unicode(mess.getFrom()).split('/')[0]
        # Say hello world as a room notification
        # Params to the API wrapper are sent as dicts
        self.bot.api.rooms.message({
            'room_id': channel,
            'from': self.bot._config['connection']['nickname'],
            'message': 'Hello world!'
        })

1stvamp / hippybot

readme