Debian Codegraph @

docs/services/chat/matrix/index.md

raw
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 ```