errbot

.. 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 <https://www.telegram.org/>`_
- `XMPP support <http://xmpp.org>`_

**With add-ons**

- `Slack support <https://slack.com/>`_ (See `instructions <https://github.com/errbotio/err-backend-slackv3>`__)
- `Discord <https://www.discordapp.com/>`_ (See `instructions <https://github.com/errbotio/err-backend-discord>`__)
- `Gitter support <https://gitter.im/>`_ (See `instructions <https://github.com/errbotio/err-backend-gitter>`__)
- `Webex <https://www.webex.com/>`_ (See `instructions <https://github.com/marksull/err-backend-cisco-webex-teams>`__)
- `Mattermost <https://about.mattermost.com/>`_ (See `instructions <https://github.com/Vaelor/errbot-mattermost-backend>`__)
- `RocketChat <https://rocket.chat/>`_ (See `instructions <https://github.com/cardoso/errbot-rocketchat>`__)
- `Skype <https://www.skype.com/>`_ (See `instructions <https://github.com/errbotio/errbot-backend-skype>`__)
- `TOX <https://tox.im/>`_ (See `instructions <https://github.com/errbotio/err-backend-tox>`__)
- `VK <https://vk.com/>`_ (See `instructions <https://github.com/Ax3Effect/errbot-vk>`__)
- `Zulip <https://zulipchat.com/>`_ (See `instructions <https://github.com/zulip/errbot-backend-zulip>`__)


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 <https://markdown-extra.readthedocs.io/>`_ 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 <https://gitter.im/errbotio/errbot>`_.
- a plugin development question please use `Stackoverflow <http://stackoverflow.com/questions/tagged/errbot>`_ with the tags `errbot` and `python`.
- a bug to report or a feature request, please use our `GitHub project page <https://github.com/errbotio/errbot/issues>`_.

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


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

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

Errbot runs under Python 3.6+ 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 <https://pypi.python.org/pypi/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 <https://raw.githubusercontent.com/errbotio/errbot/master/errbot/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 <name of repo>


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 <https://errbot.io/en/latest/user_guide/plugin_development/>`_.

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

Feel free to fork and propose changes on `github <https://www.github.com/errbotio/errbot>`_


v6.2.0 (2024-01-01)
-------------------

breaking:

- backend/slack: remove slack and slack_rtm built-in backends (#1581)
- core/logging: deprecate SENTRY_TRANSPORT config (#1604)
- core: removing py37 support (#1652)

features:

- core/plugins: detect plugins using entrypoints (#1590)
- core/logging: add new SENTRY_OPTIONS config (#1597)
- core/plugins: make slack, mattermost and discord backends available as install requirements (#1611)

fixes:

- docs: add unreleased section (#1576)
- docs: update broken URL for Markdown Extra (#1572)
- chore: bump actions/setup-python version (#1575, #1593, #1609, #1626, #1642, #1650, #1659, #1674)
- backend/telegram: fix missing imports (#1574)
- chore: ci improvements (#1577, #1583)
- chore: add docs build to ci (#1582)
- backend/xmpp: fix forward type references (#1578)
- chore: remove campfire references (#1584)
- chore/setup: fix exception when installing on python <3.7 (#1585)
- docs: typos (#1589, #1594)
- chore: simplify isort config using black (#1595)
- fix: detecting entrypoint module paths (#1603)
- chore: fix Docker build to use local tree (#1608)
- chore: bump actions/checkout version (#1610, #1625, #1637, #1644, #1653, #1656, #1658, #1663)
- docs: link to external Discord plugin documentation (#1615)
- chore: add ARG to Dockerfile and add proper stop signal (#1613)
- fix: update module versions and build (#1627)
- chore: update setuptools version (#1628)
- refactor: detecting entry point plugins (#1630)
- chore: bump mr-smithers-excellent/docker-build-push version (#1633)
- docs: fix example code in the testing section (#1643)
- chore: update all core dependencies (#1651)
- fix: use template file for webserver plugin echo output (#1654)
- chore: update repos.json (#1660)
- docs: add readthedocs yaml config (#1661)
- fix: broken integration tests (#1668)
- style: replace format() with f-strings (#1667)
- migrate from external mock package to stdlib unittest.mock (#1673)
- fix: import of Mapping from collections.abc (#1675)
- backend: update irc, telegram and xmpp dependencies (#1655)


v6.1.9 (2022-06-11)
-------------------

features:

- core: set default backend to Text (#1522)
- core: option to divert all commands to private or thread (#1528)
- core: add type hints to core and backend functions (#1542)
- docs: add ACL and numerous backends to official documentation (#1552)
- core: add Python 3.10 to automated tests (#1539)
- core: add room acl attribute (#1530)
- chore: refactor Dockerfile errbot install and python version bump (#1571)

fixes:

- core: success handling for update_repos (#1520)
- core/plugins: cascade dependency plugins (#1519)
- core/plugins: reload all repo plugins when updating a repo (#1521)
- plugin_manager: correct syntax error (#1524)
- backend/text: add stub send_stream_request method (#1527)
- backend/hipchat: remove HipChat backend (#1525)
- backend/test: shutdown sequence to address test failure (#1535)
- core: various minor logging improvements (#1536)
- chore: various minor formatting improvements (#1541)
- docs: update spark plugin reference (#1546)
- fix: python 2 version references in docs and init template (#1543)
- backends: deprecate built-in Slack and SlackRTM (#1526)
- chore: remove python 3.6 checks and test environment (#1540)
- chore: add/update issue templates (#1554)
- chore: pin all package dependencies (#1553, #1559)
- core/webserver: use errbot loglevel for consistent logging. (#1556)
- fix/core: prevent infinite loop when only BOT_PREFIX is passed (#1557)
- chore: bump actions/setup-python from 2 to 3.1.0 (#1563)
- chore: Set permissions for GitHub actions (#1565)
- fix: removed deprecated argument reconnection_interval for irc v20.0 (#1568)
- docs: Add Gentoo packages (#1567)
- chore: bump actions/setup-python from 3.1.0 to 3.1.2 (#1564)
- fix: circular dependencies error when there are none (#1505)

v6.1.8 (2021-06-21)
-------------------

features:

- core/plugin: method to append argparse options to Command object (#1394)
- backends: Add identifier for room join and room leave callbacks (#1500)
- backends/test: allow attachments to pytest messages as extras (#1489)
- core/acl: Add allowargs / denyargs filters to ACL (#1509)
- core/bootstrap: Small logging fixes to BOT_LOG_FILE and FORMATTER (#1513)
- core/plugin: Support room names with spaces (#1262)

fixes:

- core/cli: failure when passing relative directory during --init (#1511)
- backend/xmpp: include message delayed for send/received messages (#1270)
- backend/xmpp: "unexpected keyword argument 'wait'" when connecting (#1507)
- docs: update broken readme link to plugin development docs (#1504)
- close threadpool on exit (#1486)
- docs: remove matrix link (#1502)
- docs: Update backend screenshots (#1499)
- docs: Remove Google+ references (#1497)
- core: Split messages using `split()` instead of whitespace (#1496)
- chore/plugin: whoami formatting (#1459)
- backend/GUI: Remove GUI backend (#1495)

v6.1.7 (2020-12-18)
-------------------

features:

- core: Add support for python3.9 (#1477)
- chore: Allow dependabot to check GitHub actions weekly (#1464)
- chore: Add Dockerfile (#1482)

fixes:

- core: AttributeError on Blacklisted plugins (#1369)
- chore: Remove travis configuration (#1478)
- chore: minor code cleanup (#1465)
- chore: Use black codestyle (#1457, #1485)
- chore: Use twine to check dist (#1485)
- chore: remove codeclimate and eslint configs (#1490)

v6.1.6 (2020-11-16)
-------------------

features:

- core: Update code to support markdown 3 (#1473)

fixes:

- backends: Set email property as non-abstract (#1461)
- SlackRTM: username to userid method signature (#1458)
- backends: AttributeError in callback_reaction (#1467)
- docs: webhook examples (#1471)
- cli: merging configs with unknown keys (#1470)
- plugins: Fix error when plugin plug file is missing description (#1462)
- docs: typographical issues in setup guide (#1475)
- refactor: Split changelog by major versions (#1474)

v6.1.5 (2020-10-10)
-------------------

features:

-  XMPP: Replace sleekxmpp with slixmpp (#1430)
-  New callback for reaction events (#1292)
-  Added email property foriPerson object on all backends (#1186, #1456)
-  chore: Add github actions (#1455)

fixes:

-  Slack: Deprecated method calls (#1432, #1438)
-  Slack: Increase message size limit. (#1333)
-  docs: Remove Matrix backend link (#1445)
-  SlackRTM: Missing 'id\_' in argument (#1443)
-  docs: fixed rendering with double hyphens (#1452)
-  cli: merging configs via ``--storage-merge`` option (#1450)

v6.1.4 (2020-05-15)
-------------------

fixes:

-  403 error when fetching plugin repos index (#1425)

v6.1.3 (2020-04-19)
-------------------

features:

-  Add security linter (#1314)
-  Serve version.json on errbot.io and update version checker plugin (#1400)
-  Serve repos.json on errbot.io (#1403, #1406)
-  Include SlackRTM backend (beta) (#1416)

fixes:

-  Make plugin name clashes deterministic (#1282)
-  Fix error with Flows missing descriptions (#1405)
-  Fix ``!repos update`` object attribute error (#1410)
-  Fix updating remove repos using ``!repos update`` (#1413)
-  Fix deprecation warning (#1423)
-  Varios documentation fixes (#1404, #1411, #1415)

v6.1.2 (2019-12-15)
-------------------

fixes:

-  Add ability to re-run –init safely (#1390)
-  fix #1375 by managing errors on lack of version endpoint.
-  Fixed a deprecation warning for 3.9 on Mapping.
-  removing the intermediate domain requiring a certificate.
-  Fix package name for sentry-sdk flask integration
-  Add support to sentry FlaskIntegration
-  Migrate from raven (deprecated) to new sentry-sdk
-  fix: Log errors when present
-  Make chatroom log more descriptive
-  Set admin check log as debug
-  Add admin warnings to log
-  Fix: Advanced loop graph does not reflect the image
-  make the TestBot start timeout parameterized
-  errbot/plugin_manager: only check for /proc/1/cgroup if path exists to fix warning
-  removed (c) Apple asset we completely missed.
-  fix double threading in slack backend if DIVERT_TO_THREAD is used
-  pop up the timeout for travis
-  Makes the timeout feedback better on tests. (#1366)
-  Move all tox environments to use py37 (#1342)
-  Remove empty "text" body on Slack send_card (#1336)
-  Load class source in reloading plugins (#1347)
-  test: Rename assertCommand -> assertInCommand (#1351)
-  Enforce BOT_EXTRA_BACKEND_DIR is a list type. (#1358)
-  Fix #1360 Cast pathlib.Path objects to strings for use with sys.path
   (#1361)

v6.1.1 (2019-06-22)
-------------------

fixes:

-  Installation using wheel distribution on python 3.6 or older

v6.1.0 (2019-06-16)
-------------------

features:

-  Use python git instead of system git binary (#1296)

fixes:

-  ``errbot -l`` cli error (#1315)
-  Slack backend by pinning slackclient to supported version (#1343)
-  Make –storage-merge merge configs (#1311)
-  Exporting values in backup command (#1328)
-  Rename Spark to Webex Teams (#1323)
-  Various documentation fixes (#1310, #1327, #1331)

v6.0.0 (2019-03-23)
-------------------

features:

-  TestBot: Implement inject_mocks method (#1235)
-  TestBot: Add multi-line command test support (#1238)
-  Added optional room arg to inroom
-  Adds ability to go back to a previous room
-  Pass telegram message id to the callback

fixes:

-  Remove extra spaces in uptime output
-  Fix/backend import error messages (#1248)
-  Add docker support for installing package dependencies (#1245)
-  variable name typo (#1244)
-  Fix invalid variable name (#1241)
-  sanitize comma quotation marks too (#1236)
-  Fix missing string formatting in "Command not found" output (#1259)
-  Fix webhook test to not call fixture directly
-  fix: arg_botcmd decorator now can be used as plain method
-  setup: removing dnspython
-  pin markdown <3.0 because safe is deprecated

v6.0.0-alpha (2018-06-10)
-------------------------

major refactoring:

-  Removed Yapsy dependency
-  Replaced back Bottle and Rocket by Flask
-  new Pep8 compliance
-  added Python 3.7 support
-  removed Python 3.5 support
-  removed old compatibility cruft
-  ported formats and % str ops to f-strings
-  Started to add field types to improve type visibility across the codebase
-  removed cross dependencies between PluginManager & RepoManager

fixes:

-  Use sys.executable explicitly instead of just 'pip' (thx Bruno Oliveira)
-  Pycodestyle fixes (thx Nitanshu)
-  Help: don't add bot prefix to non-prefixed re cmds (#1199) (thx Robin Gloster)
-  split_string_after: fix empty string handling (thx Robin Gloster)
-  Escaping bug in dynamic plugins
-  botmatch is now visible from the errbot module (fp to Guillaume Binet)
-  flows: hint boolean was not forwarded
-  Fix possible event without bot_id (#1073) (thx Roi Dayan)
-  decorators were working only if kwargs were empty
-  Message.clone was ignoring partial and flows

features:

-  partial boolean to flag partial mesages (thx Meet Mangukiya)
-  Slack: room joined callback (thx Jeremy Kenyon)
-  XMPP: real_jid to get the jid the users logged in (thx Robin Gloster)
-  The callback order set in the config is not globally respected
-  Added a default parameter to the storage context manager

.. v9.9.9 (leave that there so master doesn't complain)