matrix-spec/content/client-server-api/modules/invite_permission.md

Invite permission

{{% added-in v="1.18" %}}

Users may want to control who is allowed to invite them to new rooms. This module defines how clients and servers can implement invite permission.

Events

{{% event event="m.invite_permission_config" %}}

Client behaviour

To reject invites from all users automatically, clients MUST add an m.invite_permission_config event in the user's account data with the default_action property set to block. To stop rejecting all invites, the same event without the default_action property MUST be added to the account data.

When the default_action field is unset, other parts of the specification might still have effects on invites seen by clients, like ignoring users.

When sending an invite to a user that blocks invites, clients SHOULD receive an error response with the M_INVITE_BLOCKED error code.

Server behaviour

When invites to a given user are blocked, the user's homeserver MUST respond to the following endpoints with an HTTP 403 status code, with the Matrix error code M_INVITE_BLOCKED, if the user is invited:

• PUT /_matrix/federation/v1/invite/{roomId}/{eventId}
• PUT /_matrix/federation/v2/invite/{roomId}/{eventId}
• POST /_matrix/client/v3/rooms/{roomId}/invite
• POST /_matrix/client/v3/createRoom, due to a user in the invite list. It is possible for one of the invited users to be rejected whilst the room creation as a whole succeeds.
• PUT /_matrix/client/v3/rooms/{roomId}/state/m.room.member/{stateKey}, when the membership is set to invite.

In addition, existing events already in the database MUST NOT be served over client synchronisation endpoints such as GET /sync. Invite events received over federation should likewise not be served over GET /sync requests.

Servers MAY return any suppressed invite events over GET /sync if invite blocking is later disabled.

Other endpoints, such as GET /rooms/{roomId}/state, are not affected by invite blocking: invite events are returned as normal.

The Application Services API is also unaffected by invite blocking: invite events are sent over PUT /_matrix/app/v1/transactions/{txnId}.