errbot: Open Source AI Interaction & Interfaces

What is errbot?

Errbot is a chatbot daemon written in Python and released under the GPL-3.0 licence that connects to a chat service and lets people start scripts, plugins and operational tasks directly from the conversation, aimed at developers and operations teams who want ChatOps inside the chat tools they already use.

What it is

Errbot is a chatbot daemon written and extensible in Python, distributed from PyPI and running under Python 3.10+ on Linux, Windows and Mac. It connects to a chat service and turns the room itself into a control surface, so scripts can be started interactively for builds, commit monitoring, alerts or plain humour. IRC, Telegram and XMPP are built in; Slack, Discord, Gitter, Webex, Mattermost, RocketChat, Skype, TOX, VK and Zulip are supported through add-ons. The project lives in the Python packaging and plugin ecosystem, with plugins hosted on git, and its topic list places it squarely in chatops, devops and automation.

The concrete problem it solves is the gap between the room where something is discussed and the shell where it is actually done. Instead of someone opening a terminal and running a script by hand, Errbot lets a chat participant start that script as a command, with ACL rules deciding who may run which command. Plugins can be installed, uninstalled, updated, enabled and disabled from chat against git-hosted public or private repositories, so the bot's behaviour changes without logging into the host. It replaces the manual, out-of-band invocation of operational scripts by whoever happens to hold shell access.

Key capabilities

Start scripts interactively from chatrooms for builds, commit monitoring, alerts and humour.
Built-in IRC, Telegram and XMPP backends; Slack, Discord, Gitter, Webex, Mattermost, RocketChat, Skype, TOX, VK and Zulip via add-ons.
ChatOps administration: install, uninstall, update, enable and disable public or private plugins hosted on git, and configure plugins from chat.
Security through ACL control, giving admin and user rights per command.
!backup creates a full export of persisted data; logs can be inspected from chat or streamed to Sentry.
Python plugin API with presetup storage (self['foo'] = 'bar'), conversation flows, webhook callbacks, polling, subcommands and several argument parsing options, plus markdown extras formatting with tables, embedded images and links.
Docstrings become help automatically; text development and debug consoles, an end-to-end test backend, and card rendering under Slack.

Who uses it and how

DevOps and platform teams use it as the chatops layer for a room, triggering builds, watching commits and firing alerts from the same place the discussion happens.
Teams whose chat system is not built in — Slack, Discord, Mattermost, RocketChat, Webex, Zulip, Gitter, Skype, TOX or VK — add the relevant backend and run the daemon wherever they host services.
Plugin developers extend it in Python, with plugin development questions directed to Stack Overflow under the errbot and python tags.
Administrators delegating operational power use per-command ACL rights, chat-driven plugin management, and !backup to export persisted data.

Getting started

Install from pip, create a data directory, and initialise it: pip install errbot, mkdir errbot; cd errbot, errbot --init, then run errbot to reach the >>> prompt and try !help. A virtualenv is recommended, and backend extras are installed the same way, for example pip install "errbot[irc]".

How it compares

No comparable chatbot projects are named in the facts supplied for this entry, and no list of paid products it replaces is provided, so by the available material Errbot stands alone in this registry. Its positioning here rests on being a general-purpose, self-hosted, GPL-3.0 Python chatbot daemon rather than on any stated head-to-head comparison. Any evaluation against other chatops tools would have to come from outside these facts.

When to use it — and when not to

Choose Errbot when a team already lives in a chat service and wants commands, plugin management and backups driven from that room, and is willing to run and secure a Python daemon plus a bot account and key for the chosen chat system. A self-hoster must operate the daemon, the persisted plugin data, the git-hosted plugins and any log streaming to Sentry, and the external backends require following their own add-on instructions rather than core installation alone. It is a poor fit for anyone who wants a hosted service with nothing to run, or who needs a formally documented operational runbook, since the README is a feature and developer reference first; the repository also carries 45 open issues, so prospective adopters should check activity in the areas they depend on.

project readme (upstream, from github) — read inline

.. image:: https://errbot.readthedocs.org/en/latest/_static/errbot.png :target: http://errbot.io

.. image:: https://github.com/errbotio/errbot/workflows/Python%20package/badge.svg :target: https://github.com/errbotio/errbot/actions

.. image:: https://img.shields.io/pypi/v/errbot.svg :target: https://pypi.python.org/pypi/errbot :alt: Latest Version

.. image:: https://img.shields.io/badge/License-GPLv3-green.svg :target: https://pypi.python.org/pypi/errbot :alt: License

.. image:: https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg :target: https://gitter.im/errbotio/errbot?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge :alt: Join the chat at https://gitter.im/errbotio/errbot

Errbot

Errbot is a chatbot. It allows you to start scripts interactively from your chatrooms for any reason: random humour, chatops, starting a build, monitoring commits, triggering alerts...

It is written and easily extensible in Python.

Errbot is available as open-source software and released under the GPL v3 license.

Features

Chat servers support


**Built-in**

- IRC support
- `Telegram support `_
- `XMPP support `_

**With add-ons**

- `Slack support `_ (See `instructions `__)
- `Discord `_ (See `instructions `__)
- `Gitter support `_ (See `instructions `__)
- `Webex `_ (See `instructions `__)
- `Mattermost `_ (See `instructions `__)
- `RocketChat `_ (See `instructions `__)
- `Skype `_ (See `instructions `__)
- `TOX `_ (See `instructions `__)
- `VK `_ (See `instructions `__)
- `Zulip `_ (See `instructions `__)


Administration
~~~~~~~~~~~~~~

After the initial installation and security setup, Errbot can be administered by just chatting to the bot (chatops).

- install/uninstall/update/enable/disable private or public plugins hosted on git
- plugins can be configured from chat
- direct the bot to join/leave Multi User Chatrooms (MUC)
- Security: ACL control feature (admin/user rights per command)
- backup: an integrated command !backup creates a full export of persisted data.
- logs: can be inspected from chat or streamed to Sentry.

Developer features
~~~~~~~~~~~~~~~~~~

- Very easy to extend in Python! (see below)
- Presetup storage for every plugin i.e. ``self['foo'] = 'bar'`` persists the value.
- Conversation flows to track conversation states from users.
- Webhook callbacks support
- supports `markdown extras `_ formatting with tables, embedded images, links etc.
- configuration helper to allow your plugin to be configured by chat
- Text development/debug consoles
- Self-documenting: your docstrings become help automatically
- subcommands and various arg parsing options are available (re, command line type)
- polling support: your can setup a plugin to periodically do something
- end to end test backend
- card rendering under Slack

Community and support
---------------------

If you have:

- a quick question feel free to join us on chat at `errbotio/errbot on Gitter `_.
- a plugin development question please use `Stackoverflow `_ with the tags `errbot` and `python`.
- a bug to report or a feature request, please use our `GitHub project page `_.

You can also ping us on Twitter with the hashtag ``#errbot``.


Installation
------------

Prerequisites
~~~~~~~~~~~~~

Errbot runs under Python 3.10+ on Linux, Windows and Mac. For some chatting systems you'll need a key or a login for your bot to access it.

Quickstart
~~~~~~~~~~

We recommend to setup a `virtualenv `_.

1. Install `errbot` from pip
2. Make a directory somewhere (here called `errbot`) to host Errbot's data files
3. Initialize the directory
4. Try out Errbot in text mode

.. code:: bash

    $ pip install errbot
    $ mkdir errbot; cd errbot
    $ errbot --init
    $ errbot

It will show you a prompt `>>>` so you can talk to your bot directly! Try `!help` to get started.

Adding support for a chat system

For the built-ins, just use one of those options telegram, IRC, XMPP with pip, you can still do it after the initial installation to add the missing support for example ::

$ pip install "errbot[irc]"

For the external ones (Slack, Discord, Gitter, Skype, etc ...), please follow their respective github pages for instructions.

Configuration


In order to configure Errbot to connect to one of those chat systems you'll need to tweak the `config.py` file generated
by `errbot --init`.

To help you, we have a documented template available here: `config-template.py `_.

Note: even if you changed the BACKEND from the configuration, you can still use `errbot -T` to test
out your instance locally in text mode.

Starting Errbot as a daemon

If all that worked, you can now use the -d (or --daemon) parameter to run it in a detached mode:

.. code:: bash

errbot --daemon

Interacting with the Bot

After starting Errbot, you should add the bot to your buddy list if you haven't already. You'll need to invite the bot explicitly to chatrooms on some chat systems too. You can now send commands directly to the bot!

To get a list of all available commands, you can issue:

.. code:: bash

!help

If you just wish to know more about a specific command you can issue:

.. code:: bash

!help command

Managing plugins


You can administer the bot in a one-on-one chat if your handle is in the BOT_ADMINS list in `config.py`.

For example to keyword search in the public plugin repos you can issue:

.. code:: bash

    !repos search jira

To install a plugin from this list, issue:

.. code:: bash

    !repos install 


For example `!repos install errbotio/err-imagebot`.

Writing plugins
---------------

Writing your own plugins is extremely simple. `errbot --init` will have installed in the `plugins` subdirectory a plugin
called `err-example` you can use as a base.

As an example, this is all it takes to create a "Hello, world!" plugin for Errbot:

.. code:: python

    from errbot import BotPlugin, botcmd

    class Hello(BotPlugin):
        """Example 'Hello, world!' plugin for Errbot"""

        @botcmd
        def hello(self, msg, args):
            """Return the phrase "Hello, world!" to you"""
            return "Hello, world!"

This plugin will create the command "!hello" which, when issued, returns "Hello, world!"
to you. For more info on everything you can do with plugins, see the
`plugin development guide `_.

Contribution to Errbot itself
-----------------------------

Feel free to fork and propose changes on `github `_

Frequently asked questions

Is errbot free to use?

errbot is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does errbot do?

Errbot is a chatbot, a daemon that connects to your favorite chat service and bring your tools and some fun into the conversation.

What is errbot written in?

errbot is primarily written in Python. Its source is publicly available at https://github.com/errbotio/errbot, and it has 3,310 GitHub stars.