For AI agents: markdown of this page — /docs-content-en/chats/management/create.md documentation index — /llms.txt

Create a group chat

POST /v1/chats

Creates a new group chat in the Bitrix24 account. Returns the numeric ID of the created chat.

Request fields (body)

Field Type Required Description
title string no Chat name
description string no Chat description
users array no Array of numeric participant IDs. List: GET /v1/users
type string no Chat type: CHAT (regular) or OPEN (open). Defaults to CHAT
entityType string no Type of the related entity (for example, CRM)
entityId string no Identifier of the related entity (for example, DEAL|123)
color string no Chat color: RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE

Examples

curl — personal key

Terminal 
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

Terminal 
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()

Response fields

Field Type Description
success boolean Always true on success
data number Numeric ID of the created chat

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
422 BITRIX_ERROR Bitrix24 returned an error (text in message)
403 SCOPE_DENIED The API key lacks the im scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The title field is optional. A chat is created without a name too — in that case the name is generated automatically from the participants' names. The field is recommended for groups with more than two participants.

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

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.

See also