19. Backend-specifics

Errbot uses external libraries for most backends, which may offer additional functionality not exposed by Errbot in a generic, backend-agnostic fashion.

It is possible to access the underlying client used by the backend you are using in order to provide functionality that isn’t otherwise available. Additionally, interacting directly with the bot internals gives you the freedom to control Errbot in highly specific ways that may not be officially supported.

Warning

The following instructions describe how to interface directly with the underlying bot object and clients of backends. We offer no guarantees that these internal APIs are stable or that a given backend will continue to use a given client in the future. The following information is provided as-is without any official support. We can give no guarantees about API stability on the topics described below.

19.1. Getting to the bot object

From within a plugin, you may access self._bot in order to get to the instance of the currently running bot class. For example, with the Telegram backend this would be an instance of TelegramBackend:

>>> type(self._bot)
<class 'errbot.backends.TelegramBackend'>

To find out what methods each bot backend has, you can take a look at the documentation of the various backends in the errbot.backends package.

Plugins may use the self._bot object to offer tailored, backend-specific functionality on specific backends. To determine which backend is being used, a plugin can inspect the self._bot.mode property. The following table lists all the values for mode for the official backends:

Backend Mode value
hipchat hipchat
irc irc
slack slack
telegram_messenger telegram
test test
text text
xmpp xmpp

Here’s an example of using a backend-specific feature. In Slack, emoji reactions can be added to messages the bot receives using the add_reaction and remove_reaction methods. For example, you could add an hourglass to messages that will take a long time to reply fully to.

from errbot import BotPlugin, botcmd

class PluginExample(BotPlugin):
    @botcmd
    def longcompute(self, mess, args):
        if self._bot.mode == "slack":
            self._bot.add_reaction(mess, "hourglass")
        else:
            yield "Finding the answer..."

        time.sleep(10)

        yield "The answer is: 42"
        if self._bot.mode == "slack":
            self._bot.remove_reaction(mess, "hourglass")

19.2. Getting to the underlying client library

Most of the backends use a third-party library in order to connect to their respective network. These libraries often support additional features which Errbot doesn’t expose in a generic way so you may wish to make use of these in order to access advanced functionality.

Backends set their own attribute(s) to point to the underlying libraries’ client instance(s). The following table lists these attributes for the official backends, along with the library used by the backend:

Backend Library Attribute(s)
hipchat sleekxmpp + hypchat self._bot.conn self._bot.conn.hypchat
irc irc self._bot.conn self._bot.conn.connection
slack slackclient self._bot.sc
telegram_messenger telegram-python-bot self._bot.telegram
xmpp sleekxmpp self._bot.conn