Создать групповой чат

POST /v1/chats

Создаёт новый групповой чат на портале Битрикс24. Возвращает числовой ID созданного чата.

Поля запроса (body)

Поле Тип Обяз. Описание
title string нет Название чата
description string нет Описание чата
users array нет Массив числовых ID участников. Список: GET /v1/users
type string нет Тип чата: CHAT (обычный) или OPEN (открытый). По умолчанию — CHAT
entityType string нет Тип связанной сущности (например, CRM)
entityId string нет Идентификатор связанной сущности (например, DEAL|123)
color string нет Цвет чата: RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/chats \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Проект Альфа",
    "users": [27, 29],
    "type": "CHAT",
    "color": "AZURE"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/chats \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Проект Альфа",
    "users": [27, 29],
    "type": "CHAT",
    "color": "AZURE"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Проект Альфа',
    users: [27, 29],
    type: 'CHAT',
    color: 'AZURE',
  }),
})

const { success, data } = await res.json()
console.log('Chat ID:', data) // числовой ID чата

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Проект Альфа',
    users: [27, 29],
    type: 'CHAT',
    color: 'AZURE',
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data number Числовой ID созданного чата

Пример ответа

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

Пример ответа при ошибке

422 — Битрикс24 вернул ошибку при создании чата:

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

Ошибки

HTTP Код Описание
422 BITRIX_ERROR Битрикс24 вернул ошибку (текст в message)
403 SCOPE_DENIED API-ключ не имеет скоупа im
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Поле title необязательно. Чат создаётся и без названия — в этом случае имя формируется автоматически по именам участников. Поле рекомендуется передавать для групп с более чем двумя участниками.

Тип OPEN. Открытый чат виден всем пользователям портала, которые знают его ID. Обычный чат (CHAT) доступен только приглашённым участникам.

Поле data — числовой ID чата. Для последующих вызовов (PATCH /v1/chats/:chatId, POST /v1/chats/:chatId/users и других) нужен именно числовой ID, не строка chat<N>.

Смотрите также