Add a user or bulk users to a channel.
For a user to invite other users, they must match at least one of the following premises:
- The user is a member of the channel and has the
add-user-to-joined-room(Add user to any joined channel) permission. - The user has the
add-user-to-any-c-room(Add user to any public channel) permission.
You can identify the channel by roomId or roomName, and the users either by ID (userId, userIds) or by username (username, user, usernames). You cannot mix IDs and usernames in the same request.
Users that do not exist are skipped and the valid users are invited. If none of the users you provide exist, the request fails with invalid-user-invite-list. Users who are already members of the channel are ignored, and the request still succeeds.
Changelog
| Version | Description |
|---|---|
| 9.0.0 | Added the userIds and usernames parameters to invite multiple users in one request. |
| 0.48.0 | Added |
The authToken of the authenticated user.
The userId of the authenticated user.
{
"roomId": "nSYqWzZ4GsKTX4dyK",
"userId": "ByehQjC44FwMeiLbX"
}{
"roomId": "nSYqWzZ4GsKTX4dyK",
"userIds": [
"ByehQjC44FwMeiLbX",
"Wq3kLm8TzR2vNpX5d"
]
}{
"roomName": "general",
"usernames": [
"john.doe",
"jane.doe"
]
}The channel's ID. This parameter is required if no roomName is provided.
The channel's name. This parameter is required if no roomId is provided.
The ID of the user to invite. Cannot be combined with username, user, or usernames.
An array of IDs of the users to invite. Cannot be combined with username, user, or usernames.
The username of the user to invite. Cannot be combined with userId or userIds.
The username of the user to invite. Alternative to username. Cannot be combined with userId or userIds.
An array of usernames of the users to invite. Cannot be combined with userId or userIds.
You can enter the user ID of one user or add multiple users. Use any one of the objects above as the body parameters.
OK
{
"channel": {
"_id": "nSYqWzZ4GsKTX4dyK",
"fname": "testing",
"_updatedAt": "2026-11-02T20:32:22.790Z",
"name": "testing",
"t": "c",
"msgs": 2,
"usersCount": 3,
"u": {
"_id": "uXquEbv7EkGHfBLa3",
"username": "admin",
"name": "Admin"
},
"ts": "2026-11-02T20:32:22.614Z",
"ro": false,
"default": false,
"sysMes": true
},
"success": true
}{
"channel": {
"_id": "nSYqWzZ4GsKTX4dyK",
"fname": "testing",
"_updatedAt": "2026-11-02T20:32:22.790Z",
"name": "testing",
"t": "c",
"msgs": 1,
"usersCount": 2,
"u": {
"_id": "uXquEbv7EkGHfBLa3",
"username": "admin",
"name": "Admin"
},
"ts": "2026-11-02T20:32:22.614Z",
"ro": false,
"default": false,
"sysMes": true
},
"success": true
}Bad Request
{
"success": false,
"errorType": "error-invalid-params",
"error": "must NOT be valid"
}{
"success": false,
"error": "Please provide \"userId\" or \"username\" or \"userIds\" or \"usernames\" as param [error-users-params-not-provided]",
"errorType": "error-users-params-not-provided"
}{
"success": false,
"error": "Not allowed [error-not-allowed]",
"errorType": "error-not-allowed",
"details": {
"method": "addUsersToRoom"
}
}{
"success": false,
"error": "invalid-user-invite-list",
"errorType": "Cannot invite if no users are provided"
}Unauthorized
{
"success": false,
"error": "You must be logged in to do this."
}