---
title: "Invite a user to participate in a particular room."
method: POST
path: "/_matrix/client/v3/rooms/{roomId}/invite "
tags: ["Room membership"]
---

# Invite a user to participate in a particular room.

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

## Request

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

*Note that there are two forms of this API, which are documented separately.
This version of the API requires that the inviter knows the Matrix
identifier of the invitee. The other is documented in the
[third-party invites](https://spec.matrix.org/v1.19/client-server-api/#third-party-invites) section.*

This API invites a user to participate in a particular room.
They do not start participating in the room until they actually join the
room.

Only users currently in a particular room can invite other users to
join that room.

If the user was invited to the room, the homeserver will append a
`m.room.member` event to the room.

## 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.
  - `user_id` string, mx-user-id, required: The fully qualified user ID of the invitee.

## Response `200`

The user has been invited to join the room, or was already invited to the room.

- object

## Other responses

- `400`: The request is invalid. A meaningful `errcode` and description error text will be returned. Example reasons for rejection include: - The request body is malformed (`errcode` set to `M_BAD_JSON` or `M_NOT_JSON`). - One or more users being invited to the room are residents of a homeserver which does not support the requested room version. The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases.
- `403`: You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: - The invitee has been banned from the room. - The invitee is already a member of the room. - The inviter is not currently in the room. - The inviter's power level is insufficient to invite users to the room. **[Added in `v1.18`]** The `M_INVITE_BLOCKED` error code is used to indicate that the homeserver rejected the invite due to [invite blocking](https://spec.matrix.org/v1.19/client-server-api/#invite-permission).
- `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)