diff options
| -rw-r--r-- | doc/mod/notification-matrix.d/01-home-server.avif | bin | 0 -> 2402 bytes | |||
| -rw-r--r-- | doc/mod/notification-matrix.d/02-access-token.avif | bin | 0 -> 4278 bytes | |||
| -rw-r--r-- | doc/mod/notification-matrix.d/03-join-room.avif | bin | 0 -> 3143 bytes | |||
| -rw-r--r-- | doc/mod/notification-matrix.md | 59 |
4 files changed, 57 insertions, 2 deletions
diff --git a/doc/mod/notification-matrix.d/01-home-server.avif b/doc/mod/notification-matrix.d/01-home-server.avif Binary files differnew file mode 100644 index 0000000..8a79ae6 --- /dev/null +++ b/doc/mod/notification-matrix.d/01-home-server.avif diff --git a/doc/mod/notification-matrix.d/02-access-token.avif b/doc/mod/notification-matrix.d/02-access-token.avif Binary files differnew file mode 100644 index 0000000..8a0b647 --- /dev/null +++ b/doc/mod/notification-matrix.d/02-access-token.avif diff --git a/doc/mod/notification-matrix.d/03-join-room.avif b/doc/mod/notification-matrix.d/03-join-room.avif Binary files differnew file mode 100644 index 0000000..c7fad4e --- /dev/null +++ b/doc/mod/notification-matrix.d/03-join-room.avif diff --git a/doc/mod/notification-matrix.md b/doc/mod/notification-matrix.md index e357b5b..91a39e5 100644 --- a/doc/mod/notification-matrix.md +++ b/doc/mod/notification-matrix.md @@ -21,13 +21,68 @@ Just install the module: $ScriptInstallUpdate mod/notification-matrix; Also install a Matrix client on at least one of your mobile and/or desktop -devices and create an account. +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`. Then reload the configuration. +`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: + + / tool fetch "https://matrix.org/.well-known/matrix/client" output=user; + + + +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*". + + / 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; + + + +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. + + / 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; + + Usage and invocation -------------------- |
