Chat management

Create and change group chats, their description, color, avatar, member permissions and message deletion policy; transfer ownership, manage notifications, join and leave chats, attach a parent chat, delete and pin chats, 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 the Bitrix24 account. Returns the numeric ID of the created chat.

Parameters

The v2 mode. format=v2 creates the chat with the v2 messenger method im.v2.Chat.add. 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. The check exists because Bitrix24 silently replaces a wrong role or auto-deletion delay with the default. In the response data is the object { chatId, chat }; Bitrix24 leaves chat 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

The title field is optional. A chat can be created without a name — in that case 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 account users who know its ID. A regular chat (CHAT) is available only to invited members.

The data field is the numeric chat ID. Subsequent calls (PATCH /v1/chats/:chatId, POST /v1/chats/:chatId/users, and others) need exactly the numeric ID, not the chat<N> string. In the v2 mode this ID arrives in data.chatId.

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 ownership
• Add members