Chat management

Create and change group chats, their description, color, avatar, member permissions and message auto-delete policy. Transfer ownership, manage notifications, join and leave chats, attach a parent chat, delete and pin chats, sort chats into personal folders, set an unread mark, and mark all chats or a list section as read.

Scope: im | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Create a group chat

POST /v1/chats

Creates a new group chat in your Bitrix24 account.

Parameters

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. 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)

Examples

curl — personal key

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

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

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

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

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

Response example

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

Error response example

422 — Bitrix24 returned an error while creating the chat:

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

Errors

Full list of common API errors — 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, and it has no separate main chat. The group already has its own chat: dialog ID by external 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, message permissions, the avatar and deletion 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
• Transfer chat ownership
• Add members