Для AI-агентов: markdown этой страницы — /docs-content/chats/management/create.md индекс документации — /llms.txt

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

POST /v1/chats

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

Параметры

Параметр Тип Обяз. Описание
format (query) string нет v2 включает режим v2 — см. «Режим v2» ниже. Любое другое значение игнорируется, ответ прежний

Режим v2. format=v2 создаёт чат. Тело остаётся плоским, как в обычном режиме, но принимает больше полей — владельца, менеджеров, права, автоудаление сообщений, аватар, участников по подразделениям. Каждое поле проверяется до обращения к Битрикс24: неизвестное поле, неверный тип или значение вне списка отклоняются с 400 INVALID_PARAMS с именем поля. Без этой проверки неверная роль или срок автоудаления молча заменились бы значением по умолчанию. В ответе data — объект { chatId, chat }. Поле chat приходит пустым, карточку нового чата читайте информацией о диалоге в режиме v2. Открытый чат в режиме v2 — type: "CHAT" с searchable: "Y". Прежнее написание type: "OPEN" отклоняется с 400 INVALID_PARAMS.

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

Поле Тип Обяз. Описание
title string нет Название чата
description string нет Описание чата
users array нет Массив числовых ID участников. Список: GET /v1/users. В режиме v2 — только положительные целые
type string нет Тип чата: CHAT (обычный) или OPEN (открытый). По умолчанию — CHAT. В режиме v2: CHAT, CHANNEL, COPILOT или COLLAB. OPEN отклоняется
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
searchable string нет Только режим v2. Y — открытый чат: его может найти и вступить в него любой сотрудник
ownerId number нет Только режим v2. Владелец чата — ID пользователя из списка пользователей. По умолчанию — вызывающий
managers array нет Только режим v2. ID менеджеров чата — положительные целые из списка пользователей
memberEntities array нет Только режим v2. Участники по сущностям — пары [тип, id]: ["user", 5], ["department", "12:F"] (подразделение с дочерними), ["project", 3]
parentChatId number нет Только режим v2. Создать чат дочерним для этого чата — см. родительский чат
avatar string | number нет Только режим v2. Картинка строкой base64 или ID файла на Диске, доступного вызывающему
manageUsersAdd string нет Только режим v2. Кто может добавлять участников: MEMBER, MANAGER, OWNER
manageUsersDelete string нет Только режим v2. Кто может удалять участников: MEMBER, MANAGER, OWNER
manageUi string нет Только режим v2. Кто может менять название, описание и аватар: MEMBER, MANAGER, OWNER
manageSettings string нет Только режим v2. Кто может менять настройки чата: MANAGER, OWNER
manageMessages string нет Только режим v2. Кто может писать: NONE (никто, кроме владельца), MEMBER, MANAGER, OWNER
manageMessagesAutoDelete string нет Только режим v2. Кто может включать автоудаление сообщений: NONE, MEMBER, MANAGER, OWNER
manageGuestInvites string нет Только режим v2. Кто может приглашать гостей: NONE, MEMBER, MANAGER, OWNER
messagesAutoDeleteDelay number нет Только режим v2. Автоудаление сообщений через столько часов: 0 (не удалять), 1, 24, 168, 720
conferencePassword string нет Только режим v2. Пароль чата видеоконференции
copilotMainRole string нет Только режим v2. Код роли CoPilot для чата типа COPILOT
entityData1, entityData2, entityData3 string нет Только режим v2. Произвольные данные сущности, сохраняются как есть

Примеры

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

curl — режим v2

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Проект Альфа",
    "searchable": "Y",
    "memberEntities": [["user", 27], ["department", "12:F"]],
    "manageUi": "MANAGER"
  }'

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data number Числовой ID созданного чата
data.chatId number Режим v2: числовой ID созданного чата
data.chat object Режим v2: всегда пустой объект

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

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

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

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

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

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Только режим v2: тело не JSON-объект, неизвестное поле или параметр строки запроса вне format, неверный тип или значение вне списка — поле названо в сообщении, — либо type: "OPEN". Проверяется до обращения к Битрикс24
422 BITRIX_ERROR Битрикс24 вернул ошибку (текст в message). В режиме v2 код портала приходит в error.b24Code
403 SCOPE_DENIED API-ключ не имеет скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения — вызов создаёт чат
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

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

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

Аватар в теле запроса. Тело запроса ограничено 1 МиБ, а base64 увеличивает размер картинки на треть: в поле avatar помещается изображение примерно до 750 КиБ. Картинку больше загрузите на Диск и передайте ID файла.

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