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

POST /v1/bots/:botId/chats/:dialogId/users

Добавляет пользователей в чат. После добавления Вайбкод по возможности сверяет состав чата с запрошенным списком и перечисляет недобавленных в поле warning успешного ответа. Сверка не гарантирована: когда она не отрабатывает, ответ приходит без warning.

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

Примеры

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

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

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

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

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

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

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

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

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

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

Поля ответа

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

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

Запрошен неактивный сотрудник 27 — Битрикс24 отчитался об успехе, в чат сотрудник не попал, в ответе появился warning:

{
  "success": true,
  "data": {
    "result": true
  },
  "warning": {
    "code": "USERS_NOT_ADDED",
    "message": "Bitrix24 returned success but 1 of 1 requested user(s) were not added to the chat — likely missing permissions, extranet restriction, or user not on portal.",
    "notAdded": [27],
    "addedAtLeast": 0
  }
}

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

403 — бот принадлежит другому ключу:

{
  "success": false,
  "error": {
    "code": "BOT_ACCESS_DENIED",
    "message": "This bot belongs to a different API key"
  }
}

Ошибки

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

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

Добавление участников зависит от прав бота в чате. Бот должен состоять в чате и подходить под его настройку manageUsersAdd, которая принимает значения owner, manager и member. Текущее значение приходит в ответе GET /v1/chats/:dialogId. Бот, создавший чат через POST /v1/bots/:botId/chats без поля ownerId, становится владельцем — этих прав достаточно при любом значении настройки. Расширить свои права в чужом чате бот не может: назначать менеджеров вправе только владелец чата — Добавить менеджеров.

Ответ остаётся успешным, когда добавлены не все. В чат не попадают: неактивный сотрудник и несуществующий идентификатор. Причиной бывают также нехватка прав и ограничение экстранета. HTTP-статус в этом случае остаётся успешным, а data.result равен true — недобавленные перечислены в warning.notAdded. Проверяйте наличие warning в ответе, а не только success.

Признак active не предсказывает результат добавления. Значение active: true в GET /v1/users говорит только о том, что сотрудник не деактивирован. Битрикс24 пропускает участника молча и по другим причинам, поэтому фактический результат добавления читают из warning.notAdded. Заранее отсеять можно внешних пользователей — у них поле userType равно "extranet".

Сверка состава выполняется по возможности. Список участников запрашивается отдельным вызовом уже после добавления. Когда этот вызов не отрабатывает, ответ приходит обычным успехом без warning — то есть отсутствие warning не доказывает, что в чат попали все. Когда состав важен, запросите его явно: Список участников.

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

• Удалить участника
• Список участников
• Добавить менеджеров
• Бот-платформа
• Лимиты и оптимизация