You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/event-schemas/schema/m.room.member

129 lines
6.5 KiB
Plaintext

---
allOf:
- $ref: core-event-schema/state_event.yaml
description: |-
Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.
The following membership states are specified:
- ``invite`` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
- ``join`` - The user has joined the room (possibly after accepting an invite), and may participate in it.
- ``leave`` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
- ``ban`` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than ``ban``).
- ``knock`` - This is a reserved word, which currently has no meaning.
The ``third_party_invite`` property will be set if this invite is an ``invite`` event and is the successor of an ``m.room.third_party_invite`` event, and absent otherwise.
This event may also include an ``invite_room_state`` key inside the event's ``unsigned`` data.
If present, this contains an array of ``StrippedState`` Events. These events provide information
on a subset of state events such as the room name.
The user for which a membership applies is represented by the ``state_key``. Under some conditions,
the ``sender`` and ``state_key`` may not match - this may be interpreted as the ``sender`` affecting
the membership state of the ``state_key`` user.
The ``membership`` for a given user can change over time. The table below represents the various changes
over time and how clients and servers must interpret those changes. Previous membership can be retrieved
from the ``prev_content`` object on an event. If not present, the user's previous membership must be assumed
as ``leave``.
.. TODO: Improve how this table is written? We use a csv-table to get around vertical header restrictions.
.. csv-table::
:header-rows: 1
:stub-columns: 1
"","to ``invite``","to ``join``","to ``leave``","to ``ban``","to ``knock``"
"from ``invite``","No change.","User joined the room.","If the ``state_key`` is the same as the ``sender``, the user rejected the invite. Otherwise, the ``state_key`` user had their invite revoked.","User was banned.","Not implemented."
"from ``join``","Must never happen.","``displayname`` or ``avatar_url`` changed.","If the ``state_key`` is the same as the ``sender``, the user left. Otherwise, the ``state_key`` user was kicked.","User was kicked and banned.","Not implemented."
"from ``leave``","New invitation sent.","User joined.","No change.","User was banned.","Not implemented."
"from ``ban``","Must never happen.","Must never happen.","User was unbanned.","No change.","Not implemented."
"from ``knock``","Not implemented.","Not implemented.","Not implemented.","Not implemented.","Not implemented."
properties:
content:
properties:
avatar_url:
description: 'The avatar URL for this user, if any.'
type: string
displayname:
description: 'The display name for this user, if any.'
type:
- "string"
- "null"
membership:
description: The membership state of the user.
enum:
- invite
- join
- knock
- leave
- ban
type: string
is_direct:
description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See `Direct Messaging`_.
type: boolean
third_party_invite:
properties:
display_name:
description: A name which can be displayed to represent the user instead of their third party identifier
type: string
signed:
description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.'
properties:
mxid:
description: The invited matrix user ID. Must be equal to the user_id property of the event.
type: string
signatures:
description: 'A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.'
title: Signatures
type: object
additionalProperties:
type: object
additionalProperties:
type: string
token:
description: The token property of the containing third_party_invite object.
type: string
required:
- mxid
- signatures
- token
title: signed
type: object
required:
- display_name
- signed
title: Invite
type: object
required:
- membership
title: EventContent
type: object
state_key:
description: |-
The ``user_id`` this membership event relates to. In all cases except for when ``membership`` is
``join``, the user ID sending the event does not need to match the user ID in the ``state_key``,
unlike other events. Regular authorisation rules still apply.
type: string
type:
enum:
- m.room.member
type: string
unsigned:
allOf:
- $ref: "core-event-schema/unsigned_prop.yaml"
- type: object
properties:
invite_room_state:
description: 'A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.'
items:
$ref: "stripped_state.yaml"
type: array
title: The current membership state of a user in the room.
type: object