extern/apprise
1
0
Fork 0
mirror of https://github.com/caronc/apprise.git synced 2024-12-12 18:01:08 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated Notify_matrix (markdown)

Chris Caron 2019-03-10 14:20:07 -04:00
parent daed09d83d
commit b0dd477b71
1 changed files with 28 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
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: <br/>`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
```