125 lines
6.5 KiB
Plaintext
125 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. This is added by the homeserver.'
|
|
type: string
|
|
displayname:
|
|
description: 'The display name for this user, if any. This is added by the homeserver.'
|
|
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
|
|
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
|
|
unsigned:
|
|
type: object
|
|
title: UnsignedData
|
|
description: Contains optional extra information about the event.
|
|
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
|
|
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
|
|
title: The current membership state of a user in the room.
|
|
type: object
|