Create a new private channel, optionally including specified users. Refer to the Channels documents for information on the available room options.
The following permissions are required:
create-p: This permission is required to create a private channel.create-team-group: This permission is required if you want to create a private channel from an existing team.create-abac-managed-room: This permission is required if you sendabacAttributes.
While Enforce ABAC across all workspace rooms is on, new private channels must be ABAC-managed and carry every attribute listed in Attributes required in all ABAC rooms.
Changelog
| Version | Description |
|---|---|
| 9.0.0 | Added the extraData.xmppFederated parameter. |
| 9.0.0 | Added the abacAttributes parameter and the skippedMembers response field. |
| 8.8.0 | Added support for enforcing end-to-end encryption when creating private rooms. |
| 6.4.1 | Added excludeSelf param |
| 0.35.0 | Added |
The authToken of the authenticated user.
The userId of the authenticated user.
{
"name": "groupname",
"members": [
"rocket.cat"
],
"readOnly": true,
"excludeSelf": true,
"customFields": {
"type": "default"
},
"extraData": {
"broadcast": true,
"encrypted": true,
"teamId": "658441562dd9f928ad9951aa"
}
}{
"name": "secret-projects",
"members": [
"jane.doe",
"john.roe"
],
"abacAttributes": {
"clearance": [
"secret"
]
}
}{
"name": "xmpp-private",
"extraData": {
"xmppFederated": true
}
}The name of the new private group.
Set if the private channel is read-only or not. The default value is false.
The users to add to the private channel when it is created.
If set to true, the user calling the endpoint is not added as a member of the private channel. The default value is false.
You add custom fields for private rooms using this parameter. Enter the key and value that you want to associate with this room. For example, { "company": "sell-and-more" }. The custom fields are not displayed in the workspace UI.
Optional. Creates the private channel as an ABAC-managed room with these attributes. Map of attribute keys to the values to assign, for example { "clearance": ["secret"] }. Keys and values can contain letters, digits, _ and -. Use 1 to 10 keys, each with 1 to 10 unique values.
Requires ABAC to be enabled and the create-abac-managed-room permission. You can only assign values returned by GET /api/v1/abac/attributes.listAssignable. You must meet the attributes yourself; otherwise the request fails with error-abac-creator-not-admitted and no room is created. A value outside the values you are offered returns error-abac-invalid-attributes. Members who do not meet the attributes are not added and are listed in skippedMembers.
Enter the following details for the object:
Note: For more information, see Channels.
Whether the group should be a broadcast group. False by default.
Whether the private room should use end-to-end encryption. When Force end-to-end encryption on private rooms is enabled, omit this field or set it to true. Setting it to false returns the error-encrypted-private-rooms-enforced error. Federated private rooms are exempt from this policy.
Enter the team ID for which you want to create a group. You will get an error if the team does not exist.
Set to true to create the private channel as an XMPP federated room that users on remote XMPP servers can join. Its XMPP address is built from the private channel name, the MUC subdomain, and the domain set for the native XMPP server.
The native XMPP server must be enabled with a valid domain. Otherwise, the request fails with error-xmpp-federation-disabled. You can't combine it with federated, encrypted, broadcast, or readOnly; the request fails with error-xmpp-room-options-not-allowed. With abacAttributes, the request fails with error-abac-federated-room-attributes.
The created private channel is returned with an xmppFederation object that holds its XMPP address in muc.
OK
{
"group": {
"_id": "NtR6RQ7NvzA9ejecX",
"name": "testing",
"t": "p",
"msgs": 0,
"u": {
"_id": "aobEdbYhXfu5hkeqG",
"username": "tester"
},
"ts": "2016-12-09T16:53:06.761Z",
"ro": false,
"sysMes": true,
"_updatedAt": "2016-12-09T16:53:06.761Z"
},
"success": true
}{
"group": {
"_id": "6720f1a3c4d5e6f7a8b9c0d1",
"name": "secret-projects",
"t": "p",
"msgs": 0,
"usersCount": 1,
"u": {
"_id": "aB3dE5fG7hJ9kL1mN",
"username": "jane.doe"
},
"ts": "2026-10-28T15:20:11.402Z",
"ro": false,
"sysMes": true,
"_updatedAt": "2026-10-28T15:20:11.402Z",
"abacAttributes": [
{
"key": "department",
"values": [
"engineering"
]
}
]
},
"skippedMembers": [
"john.roe",
"max.poe"
],
"success": true
}{
"group": {
"_id": "Hn4WcV8sQe2YtJ6aR",
"name": "xmpp-private",
"t": "p",
"msgs": 0,
"usersCount": 1,
"u": {
"_id": "aobEdbYhXfu5hkeqG",
"username": "tester"
},
"ts": "2026-10-29T13:06:40.118Z",
"ro": false,
"sysMes": true,
"_updatedAt": "2026-10-29T13:06:40.190Z",
"xmppFederation": {
"version": 1,
"role": "host-muc",
"muc": "xmpp-private@conference.chat.example.com",
"origin": "chat.example.com"
}
},
"success": true
}The room's ABAC attributes. Returned when the private channel was created with abacAttributes.
XMPP federation details of a room created with extraData.xmppFederated set to true. Returned only for XMPP federated rooms.
The version of the XMPP federation data.
The workspace's role for the room. Rooms created on this workspace have the host-muc role.
The room's XMPP address, built as <room name>@<MUC subdomain>.<XMPP domain>.
The XMPP domain of the server that hosts the room.
Usernames of the requested members who were not added because they do not meet the room's ABAC attributes. Returned only when abacAttributes was sent and at least one member was skipped.
Bad Request
{
"success": false,
"error": "Body param \"name\" is required"
}{
"success": false,
"error": "Workspace policy requires all private rooms to be encrypted. [error-encrypted-private-rooms-enforced]",
"errorType": "error-encrypted-private-rooms-enforced"
}{
"success": false,
"error": "error-abac-not-enabled",
"errorType": "error-abac-not-enabled"
}{
"success": false,
"error": "error-abac-attributes-not-allowed",
"errorType": "error-abac-attributes-not-allowed"
}{
"success": false,
"error": "error-abac-attribute-not-assignable",
"errorType": "error-abac-attribute-not-assignable",
"details": {
"cause": "error-invalid-attribute-values",
"attributes": [
{
"key": "clearance",
"values": [
"topsecret"
]
}
]
}
}{
"success": false,
"error": "error-abac-creator-not-admitted",
"errorType": "error-abac-creator-not-admitted",
"details": {
"cause": "error-only-compliant-users-can-be-added-to-abac-rooms"
}
}{
"success": false,
"error": "error-abac-invalid-attributes",
"errorType": "error-abac-invalid-attributes",
"details": {
"cause": "error-invalid-attribute-values"
}
}{
"success": false,
"error": "error-abac-attributes-required",
"errorType": "error-abac-attributes-required"
}{
"success": false,
"error": "XMPP federation is not enabled [error-xmpp-federation-disabled]",
"errorType": "error-xmpp-federation-disabled"
}Present only when a specific attribute or cause is at fault.
Unauthorized
{
"success": false,
"error": "You must be logged in to do this."
}