Matrix-Commander

The Matrix-Commander is a simple bot for the Matrix protocol. You may invite the bot into a room and execute common administrative actions by talking to it.

Communication is rather simple:

# request
!grouprise user show alice

# response
Username: alice
Email: alice@example.org
Contributions: 403
Group memberships: 27
Latest contribution: 2021-07-12 15:02:33+00:00

This Matrix bot is not related to the matrix_chat feature of grouprise. The Matrix bot can either be an account on your local Matrix server or on any external Matrix homeserver somewhere else.

You should take care, that only trusted people (responsible for content maintenance of your grouprise instance) are in the same room as the bot.

Configuration

Follow these steps:

  1. Generate a bot account and retrieve its access token:

    • In case you are running a local Matrix server for the matrix_chat feature:

      GROUPRISE_USER=root grouprisectl matrix_register_grouprise_bot --print-only --bot-username=grouprise-commander-bot

    • If you are not running a local Matrix server, you may just register an account on any Matrix server and retrieve this account‘s access token (e.g. in the element web client below Profile -> Help and About).

  2. Invite the bot (@grouprise-commander-bot:example.org) into a new matrix room (e.g. via the element web client)

    • Please note, that the matrix room may not be encrypted. At the moment the bot cannot handle encryption.

  3. Create the matrix-commander configuration (e.g. /etc/grouprise/conf.d/300-matrix_commander.yaml):

    matrix_commander:
        enabled: true
        bot_id: "@grouprise-commander-bot:example.org"
        bot_access_token: "ACCESS_TOKEN_GENERATED_ABOVE"
        admin_rooms:
                - "!lTcmhpFGnyuvwYyeCH:example.org"
        backend: nio

    • The room ID (see above admin_rooms) can be found in the Room Settings within the Advanced tab.

    • The backend can be nio (default value, a Matrix client library) or console (a dummy implementation for debugging).

  4. Try to run the bot manually (with verbose logging; stop it via CTRL-C):

    grouprisectl matrix_commander --log-level info

  5. enable and start the service:

    # systemd
systemctl enable grouprise-matrix-commander
systemctl start grouprise-matrix-commander
# sysvinit
update-rc.d grouprise-matrix-commander defaults
service grouprise-matrix-commander start

Usage

Matrix Client

Whenever you want to talk to the matrix-commander bot, you need to start the message with one of the supported prefixes:

  • generic command prefix: !grouprise help

  • the bot‘s Matrix ID (optionally followed by a colon): @grourise-commander-bot@example.org

  • local part of the bot‘s Matrix ID (optionally followed by a colon): grourise-commander-bot

The Matrix ID of the bot can be easily entered by relying on the auto-completion feature of your Matrix client (e.g. typing gro followed by the tabulator key).

All available actions of the bot are explained in the output of the help command:

!grouprise help

Local Console

Instead of using a Matrix client for issuing commands, you can also run Matrix Commander locally in a shell:

grouprisectl matrix_commander --console

Change Visible Name of Bot

You may want to improve your emotional relationship with your bot by giving it a better name.

curl \
    --header "Authorization: Bearer <bot_access_token>" \
    -X PUT \
    --data '{"displayname": "Commander example.org"}' \
    "https://example.org:8448/_matrix/client/v3/profile/@grouprise-commander-bot:example.org/displayname"