---
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.
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:
              description: 'A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.'
              properties:
                content:
                  description: The ``content`` for the event.
                  title: EventContent
                  type: object
                state_key:
                  description: The ``state_key`` for the event.
                  type: string
                type:
                  description: The ``type`` for the event.
                  type: string
              required:
                - type
                - state_key
                - content
              title: StrippedState
              type: object
            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