---
title: "Join the requesting user to a particular room."
method: POST
path: "/_matrix/client/v3/rooms/{roomId}/join"
tags: ["Room membership"]
---

# Join the requesting user to a particular room.

`POST /_matrix/client/v3/rooms/{roomId}/join`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/rooms/{roomId}/join`
- 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/rooms/:roomId/join/post.ts> (a function with typed inputs; its response is checked against the schema)

*Note that this API requires a room ID, not alias.*
`/join/{roomIdOrAlias}` *exists if you have a room alias.*

This API starts a user's participation in a particular room, if that user
is allowed to participate in that room. After this call, the client is
allowed to see all current state events in the room, and all subsequent
events associated with the room until the user leaves the room.

After a user has joined a room, the room will appear as an entry in the
response of the [`/initialSync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3initialsync)
and [`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync) APIs.

## Path parameters

- `roomId` string, mx-room-id, required

## Request body

- object
  - `reason` string: Optional reason to be included as the `reason` on the subsequent membership event.
  - `third_party_signed` object: A signature of an `m.third_party_invite` token to prove that this user owns a third-party identity which has been invited to the room.
    - `mxid` string, mx-user-id, required: The Matrix ID of the invitee.
    - `sender` string, mx-user-id, required: The Matrix ID of the user who issued the invite.
    - `signatures` object, required: A signatures object containing a signature of the entire signed object.
    - `token` string, required: The state key of the m.third_party_invite event.

## Response `200`

The room has been joined.

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

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

## Other responses

- `403`: You do not have permission to join the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The room is invite-only and the user was not invited. - The user has been banned from the room. - The room is restricted and the user failed to satisfy any of the conditions.
- `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)