Add participants

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

Adds users to a group chat by a list of their IDs.

Parameters

Request fields (body)

Examples

curl — personal key

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

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/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 — personal key

const res = await fetch('https://vibecode.bitrix24.com/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 application

const res = await fetch('https://vibecode.bitrix24.com/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()

Response fields

Response example

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

The request included inactive employee 27 — Bitrix24 reported success, the employee did not end up in the chat, and the response carries a 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
  }
}

Error response example

403 — the bot belongs to a different key:

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

Errors

Full list of common API errors — Errors.

Known specifics

Adding participants depends on the bot's rights in the chat. The bot must be a member of the chat and satisfy its manageUsersAdd setting, which takes the values owner, manager and member. The current value arrives in the response of GET /v1/chats/:dialogId. A bot that created the chat through POST /v1/bots/:botId/chats without the ownerId field becomes its owner, and those rights are enough regardless of the setting's value. A bot cannot widen its own rights in someone else's chat — only the chat owner may appoint managers, see Add managers.

The response stays successful even when not everyone is added. Inactive employees and non-existent identifiers never end up in the chat. Users can also be left out because of missing permissions or extranet restrictions. Check the response for warning, not just success.

The active flag does not predict whether the add succeeds. A value of active: true in GET /v1/users only means the employee is not deactivated. Bitrix24 silently skips participants for other reasons as well, so the actual outcome of the add is read from warning.notAdded. External users can be filtered out in advance — their userType field is "extranet".

The roster check is best-effort. The participant list is requested in a separate call after the add call. When that call does not go through, the response arrives as a plain success without warning — so the absence of warning does not prove that everyone ended up in the chat. When the roster matters, request it explicitly: List participants.

See also

• Remove a participant
• List participants
• Add managers
• Bot platform
• Limits and optimization