| 1 |
# Matrix |
| 2 |
|
| 3 |
Matrix is an open protocol for real-time communication. It is designed to allow users with accounts at one communications service provider to communicate with users of a different service provider via online chat. Upstream docs: <https://matrix.org/> |
| 4 |
|
| 5 |
## Features |
| 6 |
|
| 7 |
- __Matrix API v3 Compliance__: Implements the Matrix Client-Server API v3 specification |
| 8 |
- __Token-based Authentication__: Use pre-generated access tokens or password-based login |
| 9 |
- __Room Management__: Send messages to specific rooms or all joined rooms |
| 10 |
- __Auto-Join__: Automatically accepts room invites when rooms are explicitly specified in the configuration |
| 11 |
- __TLS Support__: Secure connections with optional TLS disabling |
| 12 |
- __Idempotent Sending__: Uses transaction IDs to prevent duplicate messages |
| 13 |
|
| 14 |
## URL Format |
| 15 |
|
| 16 |
!!! Info "" |
| 17 |
matrix://[__`user`__:__`password`__@]__`host`__[:__`port`__]/[?rooms=__`!roomID1`__[,__`roomAlias2`__]][&disableTLS=yes] |
| 18 |
|
| 19 |
If the port is omitted, the default port 443 (HTTPS) is used. |
| 20 |
|
| 21 |
--8<-- "docs/services/chat/matrix/config.md" |
| 22 |
|
| 23 |
## Authentication |
| 24 |
|
| 25 |
The Matrix service supports two authentication methods: |
| 26 |
|
| 27 |
### Token-based Login (Default) |
| 28 |
|
| 29 |
If no `user` is specified, the `password` is treated as an authentication token. |
| 30 |
This allows you to use a pre-generated access token from your Matrix server, which is useful for CI/CD pipelines or when you don't want to store your password. |
| 31 |
Simply omit the `user` parameter and provide your access token as the `password`. |
| 32 |
|
| 33 |
### Password Login |
| 34 |
|
| 35 |
If a `user` and `password` are both supplied, the service will attempt to authenticate using the `m.login.password` flow (if supported by your server). |
| 36 |
|
| 37 |
## Matrix API v3 Compliance |
| 38 |
|
| 39 |
The Matrix service implements the Matrix Client-Server API v3 specification. |
| 40 |
All API calls use v3 endpoints: |
| 41 |
|
| 42 |
```text |
| 43 |
/_matrix/client/v3/... |
| 44 |
``` |
| 45 |
|
| 46 |
### HTTP Method |
| 47 |
|
| 48 |
Messages are sent using the __PUT__ method to `/_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}`. This follows the v3 specification for idempotent message sending, ensuring that retrying a request due to network issues won't result in duplicate messages. |
| 49 |
|
| 50 |
### Transaction IDs |
| 51 |
|
| 52 |
The service automatically generates and includes a transaction ID (`txnId`) with each message send request. |
| 53 |
|
| 54 |
This provides: |
| 55 |
|
| 56 |
- __Deduplication__: If a request is retried, the server recognizes the same transaction ID and doesn't create duplicate messages |
| 57 |
- __Reliability__: Safe to retry failed requests without worrying about message duplication |
| 58 |
|
| 59 |
### Authorization Header |
| 60 |
|
| 61 |
The service passes the access token via the `Authorization: Bearer <token>` HTTP header, which is the recommended method per the v3 specification. |
| 62 |
|
| 63 |
!!! Note "Matrix v3 Compliance" |
| 64 |
As of Matrix Client-Server API v1.11, passing the access token via query parameter is deprecated. The service now exclusively uses the `Authorization: Bearer` header for all API requests. This ensures compliance with the latest specification and compatibility with Matrix Authentication Service (MAS). |
| 65 |
|
| 66 |
!!! Example "Authorization Header" |
| 67 |
```bash |
| 68 |
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
| 69 |
``` |
| 70 |
|
| 71 |
## Title Parameter |
| 72 |
|
| 73 |
The Matrix service now supports the `title` parameter. When provided, the title is prepended to the message body. |
| 74 |
|
| 75 |
!!! Example "With Title" |
| 76 |
|
| 77 |
```bash |
| 78 |
shoutrrr send --title "Notification Title" --message "This is the message body" matrix://... |
| 79 |
``` |
| 80 |
|
| 81 |
Output in Matrix: |
| 82 |
|
| 83 |
```text |
| 84 |
Notification Title |
| 85 |
|
| 86 |
This is the message body |
| 87 |
``` |
| 88 |
|
| 89 |
## Rooms |
| 90 |
|
| 91 |
If `rooms` are *not* specified, the service will send the message to all the rooms that the user has currently joined. |
| 92 |
|
| 93 |
Otherwise, the service will only send the message to the specified rooms. |
| 94 |
If the user is *not* in any of those rooms, but has been invited to any of those rooms, it will automatically accept that invite. |
| 95 |
|
| 96 |
!!! Warning "Room Joining" |
| 97 |
The service will __not__ join any rooms unless they are explicitly specified in `rooms`. |
| 98 |
If you need the user to join those rooms, you can send a notification with `rooms` explicitly set once. |
| 99 |
|
| 100 |
### Room Lookup |
| 101 |
|
| 102 |
Rooms specified in `rooms` will be treated as room IDs if they start with a `!` and used directly to identify rooms. |
| 103 |
If they have no such prefix (or use a *correctly escaped* `#`) they will instead be treated as aliases, and a directory lookup will be used to resolve their corresponding IDs. |
| 104 |
|
| 105 |
__Auto-prepending__: For convenience, rooms that don't start with `#` or `!` will automatically have `#` prepended. |
| 106 |
For example, `rooms=general` becomes `rooms=#general`. |
| 107 |
This allows you to use simple channel names without worrying about the prefix. |
| 108 |
|
| 109 |
You can use either `rooms` (for multiple rooms) or `room` (for a single room) - both parameters work identically. |
| 110 |
|
| 111 |
!!! Note "URL Encoding" |
| 112 |
Don't use unescaped `#` for the channel aliases as that will be treated as the `fragment` part of the URL. |
| 113 |
Either omit them or URL encode them, i.e. `rooms=%23alias:server` or `rooms=alias:server` |
| 114 |
|
| 115 |
## TLS |
| 116 |
|
| 117 |
If you do not have TLS enabled on the server you can disable it by providing `disableTLS=yes`. |
| 118 |
This will effectively use `http` instead of `https` for the API calls. |
| 119 |
|
| 120 |
!!! Warning "Security Risk" |
| 121 |
Disabling TLS exposes your credentials and messages in plain text over the network. |
| 122 |
Only use this option in trusted local networks or testing environments. |
| 123 |
|
| 124 |
## Examples |
| 125 |
|
| 126 |
!!! Example "Basic Notification" |
| 127 |
```uri |
| 128 |
matrix://user:[email protected] |
| 129 |
``` |
| 130 |
|
| 131 |
!!! Example "To Specific Room" |
| 132 |
```uri |
| 133 |
matrix://user:[email protected]?rooms=!roomID:matrix.example.com |
| 134 |
``` |
| 135 |
|
| 136 |
!!! Example "With Room Alias" |
| 137 |
```uri |
| 138 |
matrix://user:[email protected]?rooms=%23general:matrix.example.com |
| 139 |
``` |
| 140 |
|
| 141 |
!!! Example "Multiple Rooms" |
| 142 |
```uri |
| 143 |
matrix://user:[email protected]?rooms=!room1:matrix.example.com,%23room2:matrix.example.com |
| 144 |
``` |
| 145 |
|
| 146 |
!!! Example "With Custom Port" |
| 147 |
```uri |
| 148 |
matrix://user:[email protected]:8448?rooms=!roomID:matrix.example.com |
| 149 |
``` |
| 150 |
|
| 151 |
!!! Example "Without TLS (Not Recommended)" |
| 152 |
```uri |
| 153 |
matrix://user:[email protected]?disableTLS=yes&rooms=!roomID:matrix.example.com |
| 154 |
``` |