## Create a group chat

`POST /v1/chats`

Creates a new group chat in your Bitrix24 account.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `format` (query) | string | no | `v2` turns on the v2 mode — see "The v2 mode" below. Any other value is ignored and the response is unchanged |

**The v2 mode.** `format=v2` creates the chat. The body stays flat, as in the regular mode, but accepts more fields — the owner, managers, permissions, message auto-deletion, the avatar, members by department. Every field is checked before any call to Bitrix24: an unknown field, a wrong type or a value outside the list is rejected with `400 INVALID_PARAMS` naming the field. Without this check, a wrong role or auto-deletion delay would be silently replaced with the default. In the response, `data` is the object `{ chatId, chat }`. The `chat` field arrives empty, so read the new chat's card with [dialog details in the v2 mode](/docs/chats/discovery/get). An open chat in the v2 mode is `type: "CHAT"` with `searchable: "Y"`. The old spelling `type: "OPEN"` is rejected with `400 INVALID_PARAMS`.

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `title` | string | no | Chat name |
| `description` | string | no | Chat description |
| `users` | array | no | Array of numeric member IDs. List: [`GET /v1/users`](/docs/entities/users/list). In the v2 mode — positive integers only |
| `type` | string | no | Chat type: `CHAT` (regular) or `OPEN` (open). Defaults to `CHAT`. In the v2 mode: `CHAT`, `CHANNEL`, `COPILOT` or `COLLAB`. `OPEN` is rejected. `COLLAB` requires `entityType` and `entityId` — see "A collab chat" below |
| `entityType` | string | no | Type of the related entity (for example, `CRM`). For `type: "COLLAB"` — `SONET_GROUP` |
| `entityId` | string | no | Identifier of the related entity (for example, `DEAL\|123`). Required for `type: "COLLAB"` — a workgroup ID as a string from the [workgroup list](/docs/entities/workgroups/list), for example `"167"` |
| `color` | string | no | Chat color: `RED`, `GREEN`, `MINT`, `LIGHT_BLUE`, `DARK_BLUE`, `PURPLE`, `AQUA`, `PINK`, `LIME`, `BROWN`, `AZURE`, `KHAKI`, `SAND`, `MARENGO`, `GRAY`, `GRAPHITE` |
| `searchable` | string | no | The v2 mode only. `Y` — an open chat: any employee can find it and join |
| `ownerId` | number | no | The v2 mode only. The chat owner — a user ID from the [user list](/docs/entities/users/list). The caller by default |
| `managers` | array | no | The v2 mode only. IDs of the chat managers — positive integers from the [user list](/docs/entities/users/list) |
| `memberEntities` | array | no | The v2 mode only. Members by entity — `[type, id]` pairs: `["user", 5]`, `["department", "12:F"]` (a department with its sub-departments), `["project", 3]` |
| `parentChatId` | number | no | The v2 mode only. Create the chat as a child of this chat — see [parent chat](/docs/chats/management/parent) |
| `avatar` | string \| number | no | The v2 mode only. An image as a base64 string, or the ID of a Drive file the caller can read |
| `manageUsersAdd` | string | no | The v2 mode only. Who can add members: `MEMBER`, `MANAGER`, `OWNER` |
| `manageUsersDelete` | string | no | The v2 mode only. Who can remove members: `MEMBER`, `MANAGER`, `OWNER` |
| `manageUi` | string | no | The v2 mode only. Who can change the name, description and avatar: `MEMBER`, `MANAGER`, `OWNER` |
| `manageSettings` | string | no | The v2 mode only. Who can change the chat settings: `MANAGER`, `OWNER` |
| `manageMessages` | string | no | The v2 mode only. Who can post: `NONE` (nobody but the owner), `MEMBER`, `MANAGER`, `OWNER` |
| `manageMessagesAutoDelete` | string | no | The v2 mode only. Who can turn on message auto-deletion: `NONE`, `MEMBER`, `MANAGER`, `OWNER` |
| `manageGuestInvites` | string | no | The v2 mode only. Who can invite guests: `NONE`, `MEMBER`, `MANAGER`, `OWNER` |
| `messagesAutoDeleteDelay` | number | no | The v2 mode only. Delete messages after this many hours: `0` (never), `1`, `24`, `168`, `720` |
| `conferencePassword` | string | no | The v2 mode only. Password of a video conference chat |
| `copilotMainRole` | string | no | The v2 mode only. The CoPilot role code of a `COPILOT` chat |
| `entityData1`, `entityData2`, `entityData3` | string | no | The v2 mode only. Arbitrary entity data, stored as is |

## Examples

### curl — personal key

```bash
curl -X POST https://vibecode.bitrix24.com/v1/chats \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Alpha",
    "users": [27, 29],
    "type": "CHAT",
    "color": "AZURE"
  }'
```

### curl — OAuth application

```bash
curl -X POST https://vibecode.bitrix24.com/v1/chats \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Alpha",
    "users": [27, 29],
    "type": "CHAT",
    "color": "AZURE"
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Project Alpha',
    users: [27, 29],
    type: 'CHAT',
    color: 'AZURE',
  }),
})

const { success, data } = await res.json()
console.log('Chat ID:', data) // numeric chat ID
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Project Alpha',
    users: [27, 29],
    type: 'CHAT',
    color: 'AZURE',
  }),
})

const { success, data } = await res.json()
```

### curl — the v2 mode

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/chats?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Alpha",
    "searchable": "Y",
    "memberEntities": [["user", 27], ["department", "12:F"]],
    "manageUi": "MANAGER"
  }'
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | number | Numeric ID of the created chat |
| `data.chatId` | number | The v2 mode: numeric ID of the created chat |
| `data.chat` | object | The v2 mode: always an empty object |

## Response example

```json
{
  "success": true,
  "data": 3663
}
```

## Error response example

422 — Bitrix24 returned an error while creating the chat:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Access denied."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | The v2 mode only: the body is not a JSON object, an unknown field or a query parameter other than `format`, a wrong type or a value outside the list — the message names the field — or `type: "OPEN"`. Checked before any call to Bitrix24 |
| 422 | `BITRIX_ERROR` | Bitrix24 returned an error (text in `message`). In the v2 mode the Bitrix24 code arrives in `error.b24Code`. `type: "COLLAB"` without `entityId` gives the code `ENTITY_ID_EMPTY` |
| 403 | `SCOPE_DENIED` | The API key lacks the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only — the call creates a chat |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**A chat without a name.** Without `title`, the name is generated automatically from the members' names. The field is recommended for groups with more than two members.

**The `OPEN` type.** An open chat is visible to all users of the Bitrix24 account who know its ID. A regular chat (`CHAT`) is available only to invited members.

**A collab chat.** A collab chat belongs to a workgroup. The group gets it when it is created through [`POST /v1/workgroups`](/docs/entities/workgroups/create), and it has no separate main chat. The group already has its own chat: [dialog ID by external ID](/docs/chats/discovery/dialog-id) returns its `dialogId` for an `externalId` of the form `sgN`, where `N` is the group ID. `type: "COLLAB"` with the `entityId` of the same group creates one more collab chat for it instead of returning the existing one. The owner cannot change or delete a collab chat with the chat methods: [the v2-mode update](/docs/chats/management/rename), [message permissions](/docs/chats/management/permissions-messages), [the avatar](/docs/chats/management/avatar) and [deletion](/docs/chats/management/delete) return `403 BITRIX_ACCESS_DENIED`. The avatar of this chat cannot be set through the API: the workgroup `imageUrl` field is read-only too. A child chat of a collab chat is created as a regular `type: "CHAT"` with `parentChatId`.

**An avatar in the request body.** The request body is limited to 1 MiB, and base64 inflates an image by a third: the `avatar` field fits an image of up to about 750 KiB. Upload a larger image to Drive and pass the file ID.

## See also

- [Chat management](/docs/chats/management)
- [Transfer chat ownership](/docs/chats/management/owner)
- [Add members](/docs/chats/members/add)