Управление чатами

Создавайте и меняйте групповые чаты, их описание, цвет, аватар, права участников и политику автоудаления сообщений. Передавайте владение, управляйте уведомлениями, вступайте и выходите из чатов, привязывайте родительский чат, удаляйте и закрепляйте чаты, раскладывайте чаты по личным папкам, ставьте метку «непрочитано» и отмечайте прочитанными все чаты или раздел списка.

Скоуп: im | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

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

POST /v1/chats

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

Параметры

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

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

Примеры

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

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-приложение

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 — личный ключ

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-приложение

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

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": true,
  "data": 3663
}

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

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

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

Ошибки

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

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

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

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

Чат коллаба. Чат коллаба принадлежит рабочей группе. Группа получает его сразу при создании через POST /v1/workgroups, отдельного главного чата у неё нет. Свой чат у группы уже есть: его dialogId возвращает ID диалога по внешнему идентификатору с externalId вида sgN, где N — ID группы. type: "COLLAB" с entityId той же группы создаёт ей ещё один чат коллаба, а не возвращает существующий. Владелец не может изменить или удалить чат коллаба методами чатов: изменение в режиме v2, права на сообщения, аватар и удаление отвечают 403 BITRIX_ACCESS_DENIED. Аватар этого чата через API не задаётся: поле imageUrl рабочей группы тоже только для чтения. Дочерний чат к чату коллаба создаётся обычным type: "CHAT" с parentChatId.

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

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

• Управление чатами
• Передать владение чатом
• Добавить участников