Errbot Matrix Backend

A fully functional, modern Matrix backend for Errbot built using matrix-nio.

Features

• Connection to any Matrix homeserver via username/password or access token.
• Automatic acceptance of room invitations.
• Formatted messages (HTML/xhtml and markdown) sent and received natively.
• Full support for threaded replies using standard Matrix relations.
• Support for End-to-End Encryption (E2EE) using matrix-nio's database storage.

Requirements

• Python 3.11 - 3.14
• errbot >= 6.2.0
• matrix-nio >= 0.24.0

Installation

Local Installation for Development

You can install the backend locally inside your Errbot virtual environment:

pip install -e .

Creating a Bot Account on Matrix

Errbot connects to the Matrix network using a standard Matrix user account. To set up an account for your bot:

1. Register the User Account:

   • Open a Matrix client such as Element.
   • Register a new account on your desired homeserver (e.g., matrix.org or a self-hosted instance).
   • Save the bot's full User ID (MXID, e.g., @my_errbot:matrix.org) and password.

2. (Optional) Obtain an Access Token:

   • If you prefer to authenticate using a login token rather than storing a plaintext password in config.py:
     • Log in to Element using the bot account.
     • Open Settings -> Help & About -> scroll down to the Advanced section and copy the Access Token.
     • Paste this token into the BOT_IDENTITY dictionary under the token key.

3. Invite the Bot:

   • Start a chat with the bot's MXID or invite the bot to a room. The backend is configured to automatically accept invites by default.

Configuration

To use the Matrix backend, update your Errbot config.py file with the following settings:

# Set the backend to 'Matrix'
BACKEND = 'Matrix'

# Provide connection credentials and settings
BOT_IDENTITY = {
    # The Matrix homeserver URL
    'homeserver': 'https://matrix.org',
    
    # The full Matrix user ID (MXID) of the bot
    'username': '@my_errbot:matrix.org',
    
    # Authentication (use either password OR token)
    'password': 'my-secure-password',
    # 'token': 'syt_your_access_token_here...',
    
    # Optional settings:
    # 'device_id': 'ERRBOT_DEVICE',
    # 'ssl': True,
    # 'proxy': 'http://proxy.example.com:8080',
    # 'auto_join_on_invite': True,
    
    # To enable End-to-End Encryption (E2EE), provide a path for the database store:
    # 'store_path': '/path/to/errbot/matrix_store'
}

End-to-End Encryption (E2EE) Support

To use End-to-End Encryption in rooms, you must:

1. Ensure the libolm system library is installed (on macOS, brew install libolm; on Debian/Ubuntu, apt-get install libolm-dev).
2. Specify a 'store_path' inside BOT_IDENTITY in config.py where matrix-nio can store its encryption keys.

Running the Bot

Start Errbot normally:

errbot

Publishing to PyPI

This project uses modern PEP 517/518 build standards. To publish the package to PyPI:

1. Install build and upload tools:

   pip install build twine
   

2. Build the package distribution files:

   python -m build
   

   This will generate a .tar.gz source archive and a .whl wheel file inside the dist/ directory.

3. Verify the built packages:

   twine check dist/*
   

4. Upload to PyPI:

   twine upload dist/*
   

   (Note: You will be prompted to enter your PyPI API token. Use __token__ as the username and your token string starting with pypi- as the password).