Send notifications via Matrix

ℹ️️ Info: This module can not be used on its own but requires the base installation. See main README for details.

Description

This module adds support for sending notifications via Matrix via client server api. A queue is used to make sure notifications are not lost on failure but sent later.

Requirements and installation

Just install the module:

$ScriptInstallUpdate mod/notification-matrix;

Also install a Matrix client on at least one of your mobile and/or desktop devices. As there is no privilege separation you should create a dedicated notification account, in addition to your general user account.

Configuration

Edit global-config-overlay, add MatrixHomeServer, MatrixAccessToken and MatrixRoom - see below on hints how to retrieve this information. Then reload the configuration.

ℹ️ Info: Copy relevant configuration from global-config (the one without -overlay) to your local global-config-overlay and modify it to your specific needs.

Home server

Matrix user accounts are identified by a unique user id in the form of @localpart:domain. The domain part is not necessarily your home server address, you have to resolve it with the procedure described in the Matrix specification.

Your best bet is to query the server at domain with the well-known uri. For "matrix.org" this query is:

/tool/fetch "https://matrix.org/.well-known/matrix/client" output=user;

home server

So the home server for "matrix.org" is "matrix-client.matrix.org". Please strip the protocol ("https://") for MatrixHomeServer if given.

Access token

After discovering the correct home server an access token has to be created. For this the login credentials (username and password) of the notification account must be sent to the home server via client server api.

We use the home server discovered above, "matrix-client.matrix.org". The user is "example" and password is "v3ry-s3cr3t".

/tool/fetch "https://matrix-client.matrix.org/_matrix/client/r0/login" http-method=post http-data="{\"type\":\"m.login.password\", \"user\":\"example\", \"password\":\"v3ry-s3cr3t\"}" output=user;

access token

The server replied with a JSON object containing the access_token, use that for MatrixAccessToken.

Room

Every Matix chat is a room, so we have to create one. Do so with your general user, this makes sure your general user is the room owner. Then join the room and invite the notification user by its user id "@example:matrix.org". Look up the room id within the Matrix client, it should read like "!WUcxpSjKyxSGelouhA:matrix.org". Use that for MatrixRoom.

Finally join the notification user to the room by accepting the invite. Again, this can be done with client server api. Make sure to replace room id ("!" is escaped with "%21") and access token with your data.

/tool/fetch "https://matrix-client.matrix.org/_matrix/client/r0/rooms/%21WUcxpSjKyxSGelouhA:matrix.org/join?access_token=yt_ZXdvcm0tdGVzdA_NNqUyvKHRhBLZmnzVVSK_0xu6yN" http-method=post http-data="" output=user;

join room

Usage and invocation

There's nothing special to do. Every script or function sending a notification will now send it to your Matrix account.

But of course you can use the function to send notifications directly. Give it a try:

$SendMatrix "Subject..." "Body..."

Alternatively this sends a notification with all available and configured methods:

$SendNotification "Subject..." "Body..."

To use the functions in your own scripts you have to declare them first. Place this before you call them:

:global SendMatrix;
:global SendNotification;