mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-25 03:54:10 +02:00
Compare commits
15 commits
9ac91f6e21
...
b898a29c1e
| Author | SHA1 | Date | |
|---|---|---|---|
|
b898a29c1e | ||
|
|
fda3be5ee3 | ||
|
|
7f4072d993 | ||
|
|
58744f4734 | ||
|
|
dfdb1d09b8 | ||
|
|
f82d8ab15b | ||
|
|
b6a127b5cb | ||
|
|
0a649cb0db | ||
|
|
d8be2ad942 | ||
|
|
21109b4d5b | ||
|
|
d4d31a8894 | ||
|
|
d968774fb7 | ||
|
|
2aacc1feda | ||
|
|
2a8c0bc7b8 | ||
|
|
81a864545f |
|
|
@ -1 +0,0 @@
|
|||
Room IDs can now appear without a domain component in [room version 12](/rooms/v12), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix JSON formatting in the "Server admin style permissions" examples.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Deprecate `m.set_avatar_url` and `m.set_displayname` capabilities, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that `format` is required if `formatted_body` is specified.
|
||||
|
|
@ -1 +0,0 @@
|
|||
The `latest_event` in an aggregated set of thread events uses the same format as the event itself.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add `format` query parameter to `GET /state/{eventType}/{stateKey}` to allow fetching metadata of a specific state event.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
1
changelogs/client_server/newsfragments/2186.removal
Normal file
1
changelogs/client_server/newsfragments/2186.removal
Normal file
|
|
@ -0,0 +1 @@
|
|||
Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add the `use_state_after` query parameter and `state_after` response property to `GET /sync`, as per [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/issues/4222).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that clients should replace events with the most recent replacement by `origin_server_ts`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
When upgrading rooms to [room version 12](/rooms/v12), `additional_creators` may be specified on the [`POST /_matrix/client/v3/rooms/{roomId}/upgrade`](/client-server-api/#post_matrixclientv3roomsroomidupgrade) endpoint, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).
|
||||
|
|
@ -1 +0,0 @@
|
|||
When creating rooms with [room version 12](/rooms/v12), the `trusted_private_chat` preset should merge the invitees into the supplied `content.additional_creators` in the resulting room, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).
|
||||
|
|
@ -1 +0,0 @@
|
|||
In [room version 12](/rooms/v12), the power level of room creators is now infinitely high as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).
|
||||
|
|
@ -1 +0,0 @@
|
|||
In [room version 12](/rooms/v12), room IDs no longer have a domain component as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291).
|
||||
|
|
@ -1 +0,0 @@
|
|||
When creating rooms with [room version 12](/rooms/v12), the initial power levels will restrict the ability to upgrade rooms by default, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix `/sync` flow referencing incorrect parameter to use with `/messages`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify wording around the `world_readable` history visibility setting. Contributed by @HarHarLinks.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add a profile field for a user's time zone, as per [MSC4175](https://github.com/matrix-org/matrix-spec-proposals/pull/4175).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Invites and knocks are now expected to contain the `m.room.create` event in their stripped state entries, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove unintentional intentional mentions in replies, as per [MSC4142](https://github.com/matrix-org/matrix-spec-proposals/pull/4142).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Push rule IDs are globally unique within their kind.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Don't advertise `creator` field in description of room creation.
|
||||
|
|
@ -0,0 +1 @@
|
|||
`room_id` is required for peeking via `/_matrix/client/v3/events`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment.
|
||||
1
changelogs/client_server/newsfragments/2221.feature
Normal file
1
changelogs/client_server/newsfragments/2221.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Add note to each endpoint that uses capability negotiation.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Additional OpenGraph properties can be present in URL previews.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Declare the Application Service Registration schema to follow JSON Schema spec 2020-12.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Declare the event schemas to follow JSON Schema spec 2020-12.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add "placeholder MSC" process definition.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Upgrade the docsy theme to version 0.12.0.
|
||||
|
|
@ -1 +0,0 @@
|
|||
GitHub actions are now building the OpenAPI `spec/identity-service-api/api.json` file.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Minor fixes to JSON schemas.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Specify a correct spelling for "display name".
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix a grammatical typo on the Matrix Spec Process documentation page.
|
||||
1
changelogs/internal/newsfragments/2219.clarification
Normal file
1
changelogs/internal/newsfragments/2219.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Swapped icon for X (fka. twitter) to updated logo in footer.
|
||||
|
|
@ -1 +0,0 @@
|
|||
In room versions 1 through 12, an event's `auth_events` have always needed to belong to the same room as per [MSC4307](https://github.com/matrix-org/matrix-spec-proposals/pull/4307).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add [room version 12](/rooms/v12) as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Room IDs in room version 12 are now the event ID of the create event with the normal room ID sigil (`!`), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Room creators are formalized in room version 12 and have infinitely high power level, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).
|
||||
|
|
@ -1 +0,0 @@
|
|||
State Resolution is updated in room version 12 to reduce the opportunity for "state resets", as per [MSC4297](https://github.com/matrix-org/matrix-spec-proposals/pull/4297).
|
||||
|
|
@ -1 +0,0 @@
|
|||
The default room version is now room version 12, though servers SHOULD keep using room version 11 for a little while, as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add [room version 12](/rooms/v12) as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304).
|
||||
|
|
@ -0,0 +1 @@
|
|||
In room versions 8 through 12, clarify that "sufficient permission to invite users" on restricted joins also includes being a joined member of the room.
|
||||
|
|
@ -1 +0,0 @@
|
|||
`invite_room_state` and `knock_room_state` now have additional requirements and validation depending on the room version, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311).
|
||||
|
|
@ -67,7 +67,7 @@ current_version_url = "https://spec.matrix.org/latest"
|
|||
# The following is used when status = "stable", and is displayed in various UI elements on a released version
|
||||
# of the spec.
|
||||
# major = "1"
|
||||
# minor = "15"
|
||||
# minor = "16"
|
||||
|
||||
# User interface configuration
|
||||
[params.ui]
|
||||
|
|
@ -110,7 +110,7 @@ sidebar_menu_compact = true
|
|||
[[params.links.bottom]]
|
||||
name = "Twitter"
|
||||
url = "https://twitter.com/matrixdotorg"
|
||||
icon = "fab fa-twitter"
|
||||
icon = "fab fa-x-twitter"
|
||||
desc = "Matrix on Twitter"
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -356,6 +356,7 @@ service would like to masquerade as.
|
|||
Inputs:
|
||||
- Application service token (`as_token`)
|
||||
- User ID in the AS namespace to act as.
|
||||
- Device ID belonging to the User ID to act with.
|
||||
|
||||
Notes:
|
||||
- This applies to all aspects of the Client-Server API, except for
|
||||
|
|
@ -375,9 +376,19 @@ service's `user` namespaces. If the parameter is missing, the homeserver
|
|||
is to assume the application service intends to act as the user implied
|
||||
by the `sender_localpart` property of the registration.
|
||||
|
||||
{{% added-in v="1.17" %}} Application services MAY similarly masquerade
|
||||
as a specific device ID belonging the user ID through use of the `device_id`
|
||||
query string parameter on the request. If the given device ID is not known
|
||||
to belong to the user, the server will return a 400 `M_UNKNOWN_DEVICE` error.
|
||||
If no `user_id` is supplied, the `device_id` MUST belong to the user implied
|
||||
by the `sender_localpart` property of the application service's registration.
|
||||
If no `device_id` is supplied, the homeserver is to assume the request is
|
||||
being made without a device ID and will fail to complete operations which
|
||||
require a device ID (such as uploading one-time keys).
|
||||
|
||||
An example request would be:
|
||||
|
||||
GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org
|
||||
GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org&device_id=ABC123
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
|
||||
#### Timestamp massaging
|
||||
|
|
@ -438,8 +449,8 @@ user ID without a password.
|
|||
|
||||
Content:
|
||||
{
|
||||
type: "m.login.application_service",
|
||||
username: "_irc_example"
|
||||
"type": "m.login.application_service",
|
||||
"username": "_irc_example"
|
||||
}
|
||||
|
||||
Similarly, logging in as users needs API changes in order to allow the AS to
|
||||
|
|
@ -454,7 +465,7 @@ log in without needing the user's password. This is achieved by including the
|
|||
|
||||
Content:
|
||||
{
|
||||
type: "m.login.application_service",
|
||||
"type": "m.login.application_service",
|
||||
"identifier": {
|
||||
"type": "m.id.user",
|
||||
"user": "_irc_example"
|
||||
|
|
|
|||
103
content/changelog/v1.16.md
Normal file
103
content/changelog/v1.16.md
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
---
|
||||
title: v1.16 Changelog
|
||||
linkTitle: v1.16
|
||||
type: docs
|
||||
layout: changelog
|
||||
outputs:
|
||||
- html
|
||||
- checklist
|
||||
date: 2025-09-17
|
||||
---
|
||||
|
||||
## Client-Server API
|
||||
|
||||
**Deprecations**
|
||||
|
||||
- Deprecate `m.set_avatar_url` and `m.set_displayname` capabilities, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). ([#2071](https://github.com/matrix-org/matrix-spec/issues/2071))
|
||||
|
||||
**Removed Endpoints**
|
||||
|
||||
- Remove unintentional intentional mentions in replies, as per [MSC4142](https://github.com/matrix-org/matrix-spec-proposals/pull/4142). ([#2210](https://github.com/matrix-org/matrix-spec/issues/2210))
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). ([#2071](https://github.com/matrix-org/matrix-spec/issues/2071))
|
||||
- Add `format` query parameter to `GET /state/{eventType}/{stateKey}` to allow fetching metadata of a specific state event. ([#2175](https://github.com/matrix-org/matrix-spec/issues/2175))
|
||||
- Add the `use_state_after` query parameter and `state_after` response property to `GET /sync`, as per [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/issues/4222). ([#2187](https://github.com/matrix-org/matrix-spec/issues/2187))
|
||||
- When upgrading rooms to [room version 12](/rooms/v12), `additional_creators` may be specified on the [`POST /_matrix/client/v3/rooms/{roomId}/upgrade`](/client-server-api/#post_matrixclientv3roomsroomidupgrade) endpoint, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
- When creating rooms with [room version 12](/rooms/v12), the `trusted_private_chat` preset should merge the invitees into the supplied `content.additional_creators` in the resulting room, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
- In [room version 12](/rooms/v12), the power level of room creators is now infinitely high as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
- In [room version 12](/rooms/v12), room IDs no longer have a domain component as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
- When creating rooms with [room version 12](/rooms/v12), the initial power levels will restrict the ability to upgrade rooms by default, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
- Add a profile field for a user's time zone, as per [MSC4175](https://github.com/matrix-org/matrix-spec-proposals/pull/4175). ([#2206](https://github.com/matrix-org/matrix-spec/issues/2206))
|
||||
- Invites and knocks are now expected to contain the `m.room.create` event in their stripped state entries, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). ([#2207](https://github.com/matrix-org/matrix-spec/issues/2207))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Clarify that `format` is required if `formatted_body` is specified. ([#2167](https://github.com/matrix-org/matrix-spec/issues/2167))
|
||||
- The `latest_event` in an aggregated set of thread events uses the same format as the event itself. ([#2169](https://github.com/matrix-org/matrix-spec/issues/2169))
|
||||
- Fix various typos throughout the specification. ([#2171](https://github.com/matrix-org/matrix-spec/issues/2171), [#2177](https://github.com/matrix-org/matrix-spec/issues/2177), [#2179](https://github.com/matrix-org/matrix-spec/issues/2179))
|
||||
- Clarify that clients should replace events with the most recent replacement by `origin_server_ts`. ([#2190](https://github.com/matrix-org/matrix-spec/issues/2190))
|
||||
- Fix `/sync` flow referencing incorrect parameter to use with `/messages`. ([#2195](https://github.com/matrix-org/matrix-spec/issues/2195))
|
||||
- Clarify wording around the `world_readable` history visibility setting. Contributed by @HarHarLinks. ([#2204](https://github.com/matrix-org/matrix-spec/issues/2204))
|
||||
|
||||
|
||||
## Server-Server API
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- `invite_room_state` and `knock_room_state` now have additional requirements and validation depending on the room version, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). ([#2207](https://github.com/matrix-org/matrix-spec/issues/2207))
|
||||
|
||||
|
||||
## Application Service API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Identity Service API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Push Gateway API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Room Versions
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Room IDs in room version 12 are now the event ID of the create event with the normal room ID sigil (`!`), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
- Room creators are formalized in room version 12 and have infinitely high power level, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
- State Resolution is updated in room version 12 to reduce the opportunity for "state resets", as per [MSC4297](https://github.com/matrix-org/matrix-spec-proposals/pull/4297). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
- The default room version is now room version 12, though servers SHOULD keep using room version 11 for a little while, as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
- Add [room version 12](/rooms/v12) as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193), [#2199](https://github.com/matrix-org/matrix-spec/issues/2199))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- In room versions 1 through 12, an event's `auth_events` have always needed to belong to the same room as per [MSC4307](https://github.com/matrix-org/matrix-spec-proposals/pull/4307). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
|
||||
|
||||
## Appendices
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Room IDs can now appear without a domain component in [room version 12](/rooms/v12), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
|
||||
|
||||
|
||||
## Internal Changes/Tooling
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Add "placeholder MSC" process definition. ([#2157](https://github.com/matrix-org/matrix-spec/issues/2157))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Declare the Application Service Registration schema to follow JSON Schema spec 2020-12. ([#2132](https://github.com/matrix-org/matrix-spec/issues/2132))
|
||||
- Declare the event schemas to follow JSON Schema spec 2020-12. ([#2132](https://github.com/matrix-org/matrix-spec/issues/2132))
|
||||
- Upgrade the docsy theme to version 0.12.0. ([#2160](https://github.com/matrix-org/matrix-spec/issues/2160))
|
||||
- GitHub actions are now building the OpenAPI `spec/identity-service-api/api.json` file. ([#2172](https://github.com/matrix-org/matrix-spec/issues/2172))
|
||||
- Minor fixes to JSON schemas. ([#2182](https://github.com/matrix-org/matrix-spec/issues/2182))
|
||||
- Specify a correct spelling for "display name". ([#2189](https://github.com/matrix-org/matrix-spec/issues/2189))
|
||||
- Fix a grammatical typo on the Matrix Spec Process documentation page. ([#2205](https://github.com/matrix-org/matrix-spec/issues/2205))
|
||||
|
|
@ -132,6 +132,10 @@ The server did not understand the request. This is expected to be returned with
|
|||
a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
|
||||
code if the endpoint is implemented, but the incorrect HTTP method is used.
|
||||
|
||||
`M_UNKNOWN_DEVICE`
|
||||
{{% added-in v="1.17" %}} The device ID supplied by the application service does
|
||||
not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
|
||||
|
||||
`M_UNKNOWN`
|
||||
An unknown error has occurred.
|
||||
|
||||
|
|
@ -3386,10 +3390,10 @@ Unspecified room types are permitted through the use of
|
|||
### Creation
|
||||
|
||||
The homeserver will create an `m.room.create` event when a room is
|
||||
created, which serves as the root of the event graph for this room. This
|
||||
event also has a `creator` key which contains the user ID of the room
|
||||
creator. It will also generate several other events in order to manage
|
||||
permissions in this room. This includes:
|
||||
created, which serves as the root of the event graph for this room. The
|
||||
event `sender` is the user ID of the room creator. The server will also
|
||||
generate several other events in order to manage permissions in this room.
|
||||
This includes:
|
||||
|
||||
- `m.room.power_levels` : Sets the power levels of users and required power
|
||||
levels for various actions within the room such as sending events.
|
||||
|
|
|
|||
|
|
@ -134,9 +134,14 @@ entity isn't in the room.
|
|||
`mxc://` URIs are vulnerable to directory traversal attacks such as
|
||||
`mxc://127.0.0.1/../../../some_service/etc/passwd`. This would cause the
|
||||
target homeserver to try to access and return this file. As such,
|
||||
homeservers MUST sanitise `mxc://` URIs by allowing only alphanumeric
|
||||
(`A-Za-z0-9`), `_` and `-` characters in the `server-name` and
|
||||
`media-id` values. This set of whitelisted characters allows URL-safe
|
||||
homeservers MUST sanitise `mxc://` URIs by:
|
||||
|
||||
- restricting the `server-name` segment to valid
|
||||
[server names](/appendices/#server-name)
|
||||
- allowing only alphanumeric (`A-Za-z0-9`), `_` and `-` characters in
|
||||
the `media-id` segment
|
||||
|
||||
The resulting set of whitelisted characters allows URL-safe
|
||||
base64 encodings specified in RFC 4648. Applying this character
|
||||
whitelist is preferable to blacklisting `.` and `/` as there are
|
||||
techniques around blacklisted characters (percent-encoded characters,
|
||||
|
|
|
|||
|
|
@ -3,6 +3,9 @@
|
|||
|
||||
{{% changed-in v="1.7" %}}
|
||||
|
||||
{{% changed-in v="1.17" %}}: the legacy push rules that looked for mentions in
|
||||
the `body` of the event were removed.
|
||||
|
||||
This module allows users to "mention" other users and rooms within a room event.
|
||||
This is primarily used as an indicator that the recipient should receive a notification
|
||||
about the event.
|
||||
|
|
@ -38,19 +41,18 @@ encrypted as normal. To properly process mentions in encrypted rooms, events
|
|||
must be decrypted first. See [receiving notifications](#receiving-notifications).
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
|
||||
[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
|
||||
[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to match if the `body` of
|
||||
the event contains the user's display name or ID. To avoid unintentional notifications,
|
||||
**it is recommended that clients include a `m.mentions` property on each event**.
|
||||
(If there are no mentions to include it can be an empty object.)
|
||||
|
||||
{{% boxes/rationale %}}
|
||||
{{% boxes/note %}}
|
||||
In previous versions of the specification, mentioning users was done by
|
||||
including the user's display name or the localpart of their Matrix ID and room
|
||||
mentions were done by including the string "@room" in the plaintext `body` of
|
||||
the event. This was prone to confusing and buggy behaviour.
|
||||
{{% /boxes/rationale %}}
|
||||
the event. When the `m.mentions` field was introduced, those push rules were
|
||||
disabled if the `m.mentions` field was present.
|
||||
|
||||
To avoid unintentional notifications with clients and servers that still use
|
||||
those push rules, **it is recommended that clients still include a `m.mentions`
|
||||
property on each event**. (If there are no mentions to include it can be an
|
||||
empty object.)
|
||||
{{% /boxes/note %}}
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
|
|
|
|||
|
|
@ -83,7 +83,7 @@ Push Ruleset
|
|||
: A push ruleset *scopes a set of rules according to some criteria*. For
|
||||
example, some rules may only be applied for messages from a particular
|
||||
sender, a particular room, or by default. The push ruleset contains the
|
||||
entire set of scopes and rules.
|
||||
entire set of rules.
|
||||
|
||||
#### Push Rules
|
||||
|
||||
|
|
@ -91,10 +91,8 @@ A push rule is a single rule that states under what *conditions* an
|
|||
event should be passed onto a push gateway and *how* the notification
|
||||
should be presented. There are different "kinds" of push rules and each
|
||||
rule has an associated priority. Every push rule MUST have a `kind` and
|
||||
`rule_id`. The `rule_id` is a unique string within the kind of rule and
|
||||
its' scope: `rule_ids` do not need to be unique between rules of the
|
||||
same kind on different devices. Rules may have extra keys depending on
|
||||
the value of `kind`.
|
||||
`rule_id`. The `rule_id` is a unique string within the kind of rule.
|
||||
Rules may have extra keys depending on the value of `kind`.
|
||||
|
||||
The different `kind`s of rule, in the order that they are checked, are:
|
||||
|
||||
|
|
@ -382,6 +380,9 @@ The following `alt_aliases` values will NOT match:
|
|||
|
||||
**`contains_display_name`**
|
||||
|
||||
{{% changed-in v="1.17" %}}: this condition is deprecated and **should not be
|
||||
used in new push rules**.
|
||||
|
||||
This matches messages where `content.body` contains the owner's display name in
|
||||
that room. This is a separate condition because display names may change and as such
|
||||
it would be hard to maintain a rule that matched the user's display name. This
|
||||
|
|
@ -413,6 +414,9 @@ Parameters:
|
|||
|
||||
#### Predefined Rules
|
||||
|
||||
{{% changed-in v="1.17" %}}: the legacy default push rules that looked for
|
||||
mentions in the `body` of the event were removed.
|
||||
|
||||
Homeservers can specify "server-default rules". They operate at a lower
|
||||
priority than "user-defined rules", except for the `.m.rule.master` rule
|
||||
which has always a higher priority than any other rule. The `rule_id`
|
||||
|
|
@ -557,41 +561,6 @@ Definition:
|
|||
}
|
||||
```
|
||||
|
||||
<a id="_m_rule_contains_display_name"></a> **`.m.rule.contains_display_name`**
|
||||
|
||||
{{% changed-in v="1.7" %}}
|
||||
|
||||
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
|
||||
does not have an [`m.mentions` property](#definition-mmentions)**.
|
||||
|
||||
Matches any message whose content contains the user's current display name
|
||||
in the room in which it was sent.
|
||||
|
||||
Definition:
|
||||
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.contains_display_name",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "contains_display_name"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "sound",
|
||||
"value": "default"
|
||||
},
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**
|
||||
|
||||
{{% added-in v="1.7" %}}
|
||||
|
|
@ -626,44 +595,6 @@ Definition:
|
|||
}
|
||||
```
|
||||
|
||||
<a id="_m_rule_roomnotif"></a> **`.m.rule.roomnotif`**
|
||||
|
||||
{{% changed-in v="1.7" %}}
|
||||
|
||||
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
|
||||
does not have an [`m.mentions` property](#definition-mmentions)**.
|
||||
|
||||
Matches any message from a sender with the proper power level whose content
|
||||
contains the text `@room`, signifying the whole room should be notified of
|
||||
the event.
|
||||
|
||||
Definition:
|
||||
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.roomnotif",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "event_match",
|
||||
"key": "content.body",
|
||||
"pattern": "@room"
|
||||
},
|
||||
{
|
||||
"kind": "sender_notification_permission",
|
||||
"key": "room"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**<a id="mruletombstone"></a>`.m.rule.tombstone`**
|
||||
|
||||
Matches any state event whose type is `m.room.tombstone`. This is
|
||||
|
|
@ -776,39 +707,6 @@ Definition:
|
|||
}
|
||||
```
|
||||
|
||||
##### Default Content Rules
|
||||
|
||||
<a id="_m_rule_contains_user_name"></a> **`.m.rule.contains_user_name`**
|
||||
|
||||
{{% changed-in v="1.7" %}}
|
||||
|
||||
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
|
||||
does not have an [`m.mentions` property](#definition-mmentions)**.
|
||||
|
||||
Matches any message whose content contains the local part of the user's
|
||||
Matrix ID, separated by word boundaries.
|
||||
|
||||
Definition (as a `content` rule):
|
||||
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.contains_user_name",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"pattern": "[the local part of the user's Matrix ID]",
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "sound",
|
||||
"value": "default"
|
||||
},
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### Default Underride Rules
|
||||
|
||||
**`.m.rule.call`**
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ The rules are as follows:
|
|||
1. If membership state is `join` or `invite`, allow.
|
||||
2. If the `join_authorised_via_users_server` key in `content`
|
||||
is not a user with sufficient permission to invite other
|
||||
users, reject.
|
||||
users or is not a joined member of the room, reject.
|
||||
3. Otherwise, allow.
|
||||
6. If the `join_rule` is `public`, allow.
|
||||
7. Otherwise, reject.
|
||||
|
|
|
|||
|
|
@ -150,7 +150,7 @@ The rules are as follows:
|
|||
1. If membership state is `join` or `invite`, allow.
|
||||
2. If the `join_authorised_via_users_server` key in `content`
|
||||
is not a user with sufficient permission to invite other
|
||||
users, reject.
|
||||
users or is not a joined member of the room, reject.
|
||||
3. Otherwise, allow.
|
||||
6. If the `join_rule` is `public`, allow.
|
||||
7. Otherwise, reject.
|
||||
|
|
|
|||
|
|
@ -157,7 +157,7 @@ The rules are as follows:
|
|||
1. If membership state is `join` or `invite`, allow.
|
||||
2. If the `join_authorised_via_users_server` key in `content`
|
||||
is not a user with sufficient permission to invite other
|
||||
users, reject.
|
||||
users or is not a joined member of the room, reject.
|
||||
3. Otherwise, allow.
|
||||
6. If the `join_rule` is `public`, allow.
|
||||
7. Otherwise, reject.
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@ The rules are as follows:
|
|||
1. If membership state is `join` or `invite`, allow.
|
||||
2. If the `join_authorised_via_users_server` key in `content`
|
||||
is not a user with sufficient permission to invite other
|
||||
users, reject.
|
||||
users or is not a joined member of the room, reject.
|
||||
3. Otherwise, allow.
|
||||
6. If the `join_rule` is `public`, allow.
|
||||
7. Otherwise, reject.
|
||||
|
|
|
|||
|
|
@ -99,6 +99,10 @@ paths:
|
|||
has been removed, making this endpoint behave as though it was `false`.
|
||||
This results in this endpoint being an equivalent to `/3pid/bind` rather
|
||||
than dual-purpose.
|
||||
|
||||
This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
|
||||
Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
|
||||
to determine if this endpoint is available.
|
||||
operationId: post3PIDs
|
||||
deprecated: true
|
||||
security:
|
||||
|
|
@ -214,6 +218,10 @@ paths:
|
|||
Homeservers should prevent the caller from adding a 3PID to their account if it has
|
||||
already been added to another user's account on the homeserver.
|
||||
|
||||
This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
|
||||
Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
|
||||
to determine if this endpoint is available.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
|
|
@ -355,6 +363,10 @@ paths:
|
|||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
parameter because the homeserver is expected to sign the request to the
|
||||
identity server instead.
|
||||
|
||||
This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
|
||||
Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
|
||||
to determine if this endpoint is available.
|
||||
operationId: delete3pidFromAccount
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
|
|||
|
|
@ -379,7 +379,8 @@ paths:
|
|||
description: |-
|
||||
The OpenGraph data for the URL, which may be empty. Some values are
|
||||
replaced with matrix equivalents if they are provided in the response.
|
||||
The differences from the OpenGraph protocol are described here.
|
||||
The differences from the [OpenGraph protocol](https://ogp.me/) are
|
||||
described here.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -394,6 +395,9 @@ paths:
|
|||
format: uri
|
||||
description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
|
||||
the image. Omitted if there is no image.
|
||||
additionalProperties:
|
||||
description: |-
|
||||
Additional properties as per the [OpenGraph](https://ogp.me/) protocol.
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
|
|
|
|||
|
|
@ -605,7 +605,8 @@ paths:
|
|||
description: |-
|
||||
The OpenGraph data for the URL, which may be empty. Some values are
|
||||
replaced with matrix equivalents if they are provided in the response.
|
||||
The differences from the OpenGraph protocol are described here.
|
||||
The differences from the [OpenGraph](https://ogp.me/) protocol are
|
||||
described here.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -620,6 +621,9 @@ paths:
|
|||
format: uri
|
||||
description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
|
||||
the image. Omitted if there is no image.
|
||||
additionalProperties:
|
||||
description: |-
|
||||
Additional properties as per the [OpenGraph](https://ogp.me/) protocol.
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
|
|
|
|||
|
|
@ -34,24 +34,6 @@ properties:
|
|||
type: array
|
||||
type: object
|
||||
example: {
|
||||
"content": [
|
||||
{
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "sound",
|
||||
"value": "default"
|
||||
},
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
],
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"pattern": "alice",
|
||||
"rule_id": ".m.rule.contains_user_name"
|
||||
}
|
||||
],
|
||||
"override": [
|
||||
{
|
||||
"actions": [],
|
||||
|
|
@ -113,12 +95,14 @@ example: {
|
|||
],
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "contains_display_name"
|
||||
"kind": "event_property_contains",
|
||||
"key": "content.m\\.mentions.user_ids",
|
||||
"value": "@alice:example.com"
|
||||
}
|
||||
],
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"rule_id": ".m.rule.contains_display_name"
|
||||
"rule_id": ".m.rule.is_user_mention"
|
||||
},
|
||||
{
|
||||
"actions": [
|
||||
|
|
|
|||
|
|
@ -324,7 +324,7 @@ paths:
|
|||
This endpoint was deprecated in r0 of this specification. Clients
|
||||
should instead call the
|
||||
[/rooms/{roomId}/event/{eventId}](/client-server-api/#get_matrixclientv3roomsroomideventeventid) API
|
||||
or the [/rooms/{roomId}/context/{eventId](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API.
|
||||
or the [/rooms/{roomId}/context/{eventId}](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API.
|
||||
operationId: getOneEvent
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
|
|||
|
|
@ -34,6 +34,10 @@ paths:
|
|||
valid access token is provided. The homeserver SHOULD NOT revoke the
|
||||
access token provided in the request. Whether other access tokens for
|
||||
the user are revoked depends on the request parameters.
|
||||
|
||||
This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
|
||||
Clients SHOULD check the value of the [`m.change_password` capability](/client-server-api/#mchange_password-capability)
|
||||
to determine if this endpoint is available.
|
||||
security:
|
||||
- {}
|
||||
- accessTokenQuery: []
|
||||
|
|
|
|||
|
|
@ -59,6 +59,7 @@ paths:
|
|||
example: "!somewhere:over.the.rainbow"
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: The events received, which may be none.
|
||||
|
|
|
|||
|
|
@ -29,6 +29,11 @@ paths:
|
|||
Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
|
||||
them rather than treating `null` as a deletion request. Clients that want to delete a
|
||||
field, including its key and value, SHOULD use the `DELETE` endpoint instead.
|
||||
|
||||
This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation)
|
||||
depending on the `keyName`. Clients SHOULD check the value of the
|
||||
[`m.profile_fields` capability](/client-server-api/#mprofile_fields-capability) to detect
|
||||
which `keyName`s they are allowed to modify.
|
||||
operationId: setProfileField
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
|
|||
|
|
@ -3,24 +3,6 @@
|
|||
"type": "m.push_rules",
|
||||
"content": {
|
||||
"global": {
|
||||
"content": [
|
||||
{
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "sound",
|
||||
"value": "default"
|
||||
},
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
],
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"pattern": "alice",
|
||||
"rule_id": ".m.rule.contains_user_name"
|
||||
}
|
||||
],
|
||||
"override": [
|
||||
{
|
||||
"actions": [],
|
||||
|
|
@ -82,12 +64,14 @@
|
|||
],
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "contains_display_name"
|
||||
"kind": "event_property_contains",
|
||||
"key": "content.m\\.mentions.user_ids",
|
||||
"value": "@alice:example.com"
|
||||
}
|
||||
],
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"rule_id": ".m.rule.contains_display_name"
|
||||
"rule_id": ".m.rule.is_user_mention"
|
||||
},
|
||||
{
|
||||
"actions": [
|
||||
|
|
|
|||
Loading…
Reference in a new issue