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

Добавить участников

POST /v1/chats/:chatId/users

Добавляет одного или нескольких пользователей в групповой чат.

Параметры

Параметр Тип Обяз. Описание
chatId (path) number да Числовой ID чата (без префикса chat)
format (query) string нет v2 включает режим v2 — см. «Режим v2» ниже. Любое другое значение игнорируется, ответ прежний. Повтор format не отклоняется: из format=v1&format=v2 берётся последнее значение, то есть режим v2, а format=v2&format=v1 даёт прежний ответ. Форма format[]=v2 включает режим v2, если все её значения — v2

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

Поле Тип Обяз. Описание
users number[] да Непустой массив ID пользователей для добавления. Каждый элемент — положительное целое: число или строка из десятичных цифр без ведущих нулей и пробелов, не больше 2^53−1; любая другая форма отклоняется до обращения к порталу
hideHistory boolean нет true — новые участники не видят историю до вступления, по умолчанию true. false — история открыта с момента создания чата

Режим v2. format=v2 добавляет участников через мессенджер v2 с тем же телом. Принимаются только users — не больше 50 ID за запрос — и hideHistory: написание Битрикс24 USERS и HIDE_HISTORY, другие поля тела и query-параметры отклоняются с 400 INVALID_PARAMS, а hideHistory должен быть логическим значением. Умолчание hideHistory то же — true. В data приходит { "result": true } вместо true.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/123/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "users": [42, 53] }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/123/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "users": [42, 53] }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/123/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ users: [42, 53] }),
})

const { success, data } = await res.json()
console.log('Добавлено:', data)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/123/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ users: [42, 53] }),
})

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

curl — режим v2

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/123/users?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "users": [42, 53], "hideHistory": false }'

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data boolean true при успешном добавлении
data.result boolean Режим v2: true — запрос выполнен

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

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

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

403 — API-ключ не имеет скоупа im:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'im' scope"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_CHAT_ID chatId не является положительным целым числом — проверяется до обращения в Битрикс24
400 MISSING_PARAMS Поле users отсутствует или массив пуст (в том числе запрос вовсе без тела)
400 INVALID_PARAMS users — не массив, либо один из элементов не является положительным целым в каноничной записи (в message названы индекс и тип; "047", " 47" и значения больше 2^53−1 отклоняются). В режиме v2 также users длиннее 50, query-параметр кроме format, поле тела кроме users и hideHistory, hideHistory не логическое, тело не JSON-объект. В Битрикс24 ничего не отправлено
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения — см. права доступа
403 SCOPE_DENIED API-ключ не имеет скоупа im
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24
422 BITRIX_ERROR Битрикс24 вернул ошибку — текст в поле message (например, чат не найден или нет прав)
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ошибку сервера

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

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

Только числовые ID. Битрикс24 приводит каждый элемент users к числу по правилам PHP: слово превращается в 0 и молча пропускается с ответом «добавлено», а вложенный массив роняет портал. Чтобы опечатка не выглядела успехом, элементы проверяются на стороне API: принимаются число и строка из десятичных цифр без ведущих нулей и пробелов, остальное — 400 INVALID_PARAMS.

Несуществующие пользователи пропускаются. Если в массиве users есть ID несуществующих или неактивных пользователей, они игнорируются без ошибки. Операция для остальных участников выполняется.

По умолчанию история скрыта. При добавлении без явного hideHistory новые участники не видят сообщения, отправленные до их вступления. Чтобы открыть доступ к истории с момента создания чата, передайте hideHistory: false.

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