2021-11-16 15:03:25 +00:00
|
|
|
|
Send notifications via Matrix
|
|
|
|
|
|
=============================
|
|
|
|
|
|
|
|
|
|
|
|
[◀ Go back to main README](../../README.md)
|
|
|
|
|
|
|
|
|
|
|
|
> ℹ️️ **Info**: This module can not be used on its own but requires the base
|
|
|
|
|
|
> installation. See [main README](../../README.md) for details.
|
|
|
|
|
|
|
|
|
|
|
|
Description
|
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
|
|
This module adds support for sending notifications via
|
|
|
|
|
|
[Matrix](https://matrix.org/) 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
|
2022-02-21 17:21:26 +00:00
|
|
|
|
devices. As there is no privilege separation you should create a dedicated
|
|
|
|
|
|
notification account, in addition to your general user account.
|
2021-11-16 15:03:25 +00:00
|
|
|
|
|
|
|
|
|
|
Configuration
|
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
|
|
Edit `global-config-overlay`, add `MatrixHomeServer`, `MatrixAccessToken` and
|
2022-02-21 17:21:26 +00:00
|
|
|
|
`MatrixRoom` - see below on hints how to retrieve this information. Then
|
|
|
|
|
|
reload the configuration.
|
|
|
|
|
|
|
|
|
|
|
|
### 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](https://spec.matrix.org/latest/client-server-api/#server-discovery).
|
|
|
|
|
|
|
|
|
|
|
|
Your best bet is to query the server at `domain` with the
|
|
|
|
|
|
[well-known uri](https://spec.matrix.org/latest/client-server-api/#well-known-uri).
|
|
|
|
|
|
For "*matrix.org*" this query is:
|
|
|
|
|
|
|
2022-05-11 08:15:25 +00:00
|
|
|
|
/tool/fetch "https://matrix.org/.well-known/matrix/client" output=user;
|
2022-02-21 17:21:26 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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](https://matrix.org/docs/guides/client-server-api#login).
|
|
|
|
|
|
|
|
|
|
|
|
We use the home server discovered above, "*matrix-client.matrix.org*".
|
|
|
|
|
|
The user is "*example*" and password is "*v3ry-s3cr3t*".
|
|
|
|
|
|
|
2022-05-11 08:15:25 +00:00
|
|
|
|
/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;
|
2022-02-21 17:21:26 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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](https://matrix.org/docs/guides/client-server-api#joining-a-room-via-an-invite).
|
|
|
|
|
|
Make sure to replace room id ("*!*" is escaped with "*%21*") and access token
|
|
|
|
|
|
with your data.
|
|
|
|
|
|
|
2022-05-11 08:15:25 +00:00
|
|
|
|
/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;
|
2022-02-21 17:21:26 +00:00
|
|
|
|
|
|
|
|
|
|
|
2021-11-16 15:03:25 +00:00
|
|
|
|
|
|
|
|
|
|
Usage and invocation
|
|
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
|
|
|
|
There's nothing special to do. Every script or function sending a notification
|
|
|
|
|
|
will now send it to your Matrix account.
|
|
|
|
|
|
|
2022-06-05 20:50:23 +00:00
|
|
|
|
But of course you can send notifications directly or use a function in your
|
|
|
|
|
|
own scripts. Give it a try:
|
|
|
|
|
|
|
|
|
|
|
|
$SendMatrix "Subject..." "Body..."
|
|
|
|
|
|
|
|
|
|
|
|
Alternatively this sends a notification with all available and configured
|
|
|
|
|
|
methods:
|
|
|
|
|
|
|
|
|
|
|
|
$SendNotification "Subject..." "Body..."
|
|
|
|
|
|
|
2021-11-16 15:03:25 +00:00
|
|
|
|
See also
|
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
|
|
* [Send notifications via Telegram](notification-telegram.md)
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
[◀ Go back to main README](../../README.md)
|
|
|
|
|
|
[▲ Go back to top](#top)
|
