From b0dd477b7127fe27a5ac57cf0f66aac23f179162 Mon Sep 17 00:00:00 2001 From: Chris Caron Date: Sun, 10 Mar 2019 14:20:07 -0400 Subject: [PATCH] Updated Notify_matrix (markdown) --- Notify_matrix.md | 41 ++++++++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/Notify_matrix.md b/Notify_matrix.md index 7ac8c7e..6dfae2c 100644 --- a/Notify_matrix.md +++ b/Notify_matrix.md @@ -4,29 +4,44 @@ * **Message Format**: Text * **Message Limit**: 1000 Characters per message -To use this plugin, you need to first set yourself up with https://matrix.org. +To use this plugin, you need to first set yourself up with your own matrix synapse s ### Syntax Valid syntaxes are as follows: -* **matrix**://**{token}** -* **matrix**://**{token}**?**mode=slack** -* **matrix**://**{user}**@**{token}**?**mode=slack** +* **matrix**://**{user}**:**{password}**@**{matrixhost}**/**#{room_alias}** +* **matrixs**://**{user}**:**{password}**@**{matrixhost}**/**!{room_id}** -Both **matrix://** and **matrixs://** are both handled in a secure fashion. +You can mix and match as many rooms as you wish: +* **matrixs**://**{user}**:**{password}**@**{matrixhost}**/**!{room_id}**/**#{room_alias}**/ + +**Note:** If no user and/or password is specified, then the matrix registration process is invoked. The matrix servers actually allow this (if enabled to do so in their configuration) to connect as a temporary user with/without a password and/or user-name. Under normal circumstances you should probably always supply a **{user}** and **{password}**. + +**Note:** Federated rooms identifiers are fully supported by Apprise. If no hostname is found in the _{room_id}_ and/or _{room_alias}_ entries specified, then apprise automatically uses the hostname returned to it (internally) upon login. For example, assume the following url:
`matrix://user:pass@localhost/#room/#room:example.com/!abc123/!def456:example.com`: + + * **#room** is internally interpreted as **#room:localhost** before it is accessed. + * **#room:example.com** is not altered and is directly notified as such + * **!abc123** is internally interpreted as **!abc123:localhost** + * **!def456:example.com** is not altered and is directly notified as such ### Parameter Breakdown | Variable | Required | Description | ----------- | -------- | ----------- -| token | Yes | The token you would have gotten after setting up the matrix.org -| user | No | The user to associate with the webhook created on matrix.org. By default, this is set to **apprise** -| port | No | The server port Matrix is listening on. By default the port is **443**. -| mode | No | The message mode to use; but default it uses the built in mode ('**matrix**'). You can additionally set this mode to **slack** to change the notification format. +| hostname | Yes | The matrix server you wish to connect to. +| user | No | The user to authenticate (and/or register) with the matrix server +| password | No | The password to authenticate (and/or register) with the matrix server +| port | No | The server port Matrix is listening on. By default **matrixs://** uses a secure port port of **8448** while **matrix://** uses port **8008**. +| room_alias | No | The room alias you wish to join (if not there already) and broadcast your notification. For ambiguity purposes _you should_ prefix these locations with a pound/hashtag symbol **#** although it is not required. +| room_id | No | The room id you wish to join (if not there already) and broadcast your notification. For ambiguity purposes, _you MUST_ prefix these locations with a exclamation symbol **!** (_otherwise it is interpreted as a room_alias instead_) +| thumbnail | No | Displays an image before each notification is sent that identifies the notification type (warning, info, error, success). By default this option is set to **False**. + +**Note**: If neither a **{room_alias}** or a **{room_id}** is specified on the URL then upon connecting to the matrix server, a list of currently joined channels will be polled. Each and every channel the account is currently part of will automatically be notified. #### Example Send a secure Matrix.org notification to our server ```bash -# Assuming our {token} is 3ccdd113474722377935511fc85d3dd4 -# Assuming our {user} is caronc - -apprise matrix://caronc@3ccdd113474722377935511fc85d3dd4 +# Assuming our {hostname} is matrix.example.com +# Assuming our {user} is nuxref +# Assuming our {password} is abc123 +# Assuming the {room_alias} we want to notify is #general and #apprise +apprise matrixs://nuxref:abc123@matrix.example.com/#general/#apprise ``` \ No newline at end of file