MAmatrix
Room membership

Knock on a room, requesting permission to join.

Note that this API takes either a room ID or alias, unlike other membership APIs.

This API "knocks" on the room to ask for permission to join, if the user is allowed to knock on the room. Acceptance of the knock happens out of band from this API, meaning that the client will have to watch for updates regarding the acceptance/rejection of the knock.

If the room history settings allow, the user will still be able to see history of the room while being in the "knock" state. The user will have to accept the invitation to join the room (acceptance of knock) to see messages reliably. See the /join endpoints for more information about history visibility to the user.

The knock will appear as an entry in the response of the /sync API.

post/_matrix/client/v3/knock/{roomIdOrAlias}

Request

Path parameters

string mx-room-id required
OR
string mx-room-alias required

The room identifier or alias to knock upon.

Query parameters

viastring[]

The servers to attempt to knock on the room through. One of the servers must be participating in the room.

Request body

reasonstring

Optional reason to be included as the reason on the subsequent membership event.

Example request

{
  "reason": "Looking for support"
}

Response

The room has been knocked upon.

The knocked room ID must be returned in the room_id field.

room_idstring mx-room-id required

The knocked room ID.

Changes

No recorded changes to this operation across all 1 revision of this API.