Create Group

Prev Next
Post
/api/v1/groups.create

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 send abacAttributes.

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
Header parameters
X-Auth-Token
stringRequired

The authToken of the authenticated user.

ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f
X-User-Id
stringRequired

The userId of the authenticated user.

ExamplerbAXPnMktTFbNpwtJ
Body parameters
Example
{
  "name": "groupname",
  "members": [
    "rocket.cat"
  ],
  "readOnly": true,
  "excludeSelf": true,
  "customFields": {
    "type": "default"
  },
  "extraData": {
    "broadcast": true,
    "encrypted": true,
    "teamId": "658441562dd9f928ad9951aa"
  }
}
ABAC-managed private channel
{
  "name": "secret-projects",
  "members": [
    "jane.doe",
    "john.roe"
  ],
  "abacAttributes": {
    "clearance": [
      "secret"
    ]
  }
}
XMPP federated private channel
{
  "name": "xmpp-private",
  "extraData": {
    "xmppFederated": true
  }
}
Expand All
object
name
string Required

The name of the new private group.

Examplegroupname
readOnly
boolean

Set if the private channel is read-only or not. The default value is false.

Examplefalse
members
Array of string

The users to add to the private channel when it is created.

string
Examplerocket.cat
excludeSelf
boolean

If set to true, the user calling the endpoint is not added as a member of the private channel. The default value is false.

Examplefalse
customFields
object

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.

abacAttributes
object

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.

Example{ "clearance": [ "secret" ] }
property*
Array of string additionalProperties
string
extraData
object

Enter the following details for the object:

Note: For more information, see Channels.

broadcast
boolean

Whether the group should be a broadcast group. False by default.

encrypted
boolean

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.

teamId
string

Enter the team ID for which you want to create a group. You will get an error if the team does not exist.

xmppFederated
boolean

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.

Exampletrue
Responses
200

OK

Success
{
  "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
}
ABAC-managed private channel
{
  "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
}
XMPP federated private channel
{
  "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
}
Expand All
object
group
object
_id
string
name
string
t
string
msgs
integer
u
object
_id
string
username
string
ts
string
ro
boolean
sysMes
boolean
_updatedAt
string
usersCount
integer
abacAttributes
Array of object

The room's ABAC attributes. Returned when the private channel was created with abacAttributes.

object
key
string
values
Array of string
string
xmppFederation
object (XmppFederation)

XMPP federation details of a room created with extraData.xmppFederated set to true. Returned only for XMPP federated rooms.

version
integer

The version of the XMPP federation data.

Example1
role
string

The workspace's role for the room. Rooms created on this workspace have the host-muc role.

Examplehost-muc
muc
string

The room's XMPP address, built as <room name>@<MUC subdomain>.<XMPP domain>.

Examplexmpp-public@conference.chat.example.com
origin
string

The XMPP domain of the server that hosts the room.

Examplechat.example.com
skippedMembers
Array of string

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.

string
success
boolean
400

Bad Request

Name is required
{
  "success": false,
  "error": "Body param \"name\" is required"
}
Private room encryption is enforced
{
  "success": false,
  "error": "Workspace policy requires all private rooms to be encrypted. [error-encrypted-private-rooms-enforced]",
  "errorType": "error-encrypted-private-rooms-enforced"
}
ABAC not enabled
{
  "success": false,
  "error": "error-abac-not-enabled",
  "errorType": "error-abac-not-enabled"
}
ABAC attributes not allowed
{
  "success": false,
  "error": "error-abac-attributes-not-allowed",
  "errorType": "error-abac-attributes-not-allowed"
}
ABAC value not assignable
{
  "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"
        ]
      }
    ]
  }
}
Creator does not meet the ABAC attributes
{
  "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"
  }
}
Invalid ABAC attribute values
{
  "success": false,
  "error": "error-abac-invalid-attributes",
  "errorType": "error-abac-invalid-attributes",
  "details": {
    "cause": "error-invalid-attribute-values"
  }
}
Required ABAC attributes missing
{
  "success": false,
  "error": "error-abac-attributes-required",
  "errorType": "error-abac-attributes-required"
}
XMPP federation not enabled
{
  "success": false,
  "error": "XMPP federation is not enabled [error-xmpp-federation-disabled]",
  "errorType": "error-xmpp-federation-disabled"
}
Expand All
object
success
boolean
error
string
errorType
string
details
object

Present only when a specific attribute or cause is at fault.

401

Unauthorized

Authorization Error
{
  "success": false,
  "error": "You must be logged in to do this."
}
object
success
boolean
error
string