---
title: "Knock on a room, requesting permission to join."
method: POST
path: "/_matrix/client/v3/knock/{roomIdOrAlias}"
tags: ["Room membership"]
---

# Knock on a room, requesting permission to join.

`POST /_matrix/client/v3/knock/{roomIdOrAlias}`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/knock/{roomIdOrAlias}`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v3/knock/:roomIdOrAlias/post.ts> (a function with typed inputs; its response is checked against the schema)

*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`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync) API.

## Path parameters

- `roomIdOrAlias` union, required
  - string, mx-room-id
  - string, mx-room-alias

## Query parameters

- `via` string[]

## Request body

- object
  - `reason` string: Optional reason to be included as the `reason` on the subsequent membership event.

## Response `200`

The room has been knocked upon.

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

- object
  - `room_id` string, mx-room-id, required: The knocked room ID.

## Other responses

- `403`: You do not have permission to knock on the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The room is not set up for knocking. - The user has been banned from the room.
- `404`: The room could not be found or resolved to a room ID.
- `429`: This request was rate-limited.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)