For AI agents: markdown of this page — /docs-content-en/bots/chats/user-add.md documentation index — /llms.txt

Add participants

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

Adds users to a chat. After the add call, Vibecode makes a best-effort check of the chat roster against the requested list and reports anyone missing in the warning field of the successful response. The check is not guaranteed: when it does not run, the response arrives without warning.

Request fields (body)

Parameter Type Req. Description
userIds number[] yes Array of user IDs to add

Examples

curl — personal key

Terminal 
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

Terminal 
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

javascript 
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

javascript 
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

Field Type Description
data.result boolean Bitrix24's acknowledgement that the request was accepted. It is true even when no one ended up in the chat — the actual outcome is shown by warning
warning object Present when the check ran and found that at least one of the requested users did not end up in the chat — including the case where none of them did. The absence of the field does not prove that everyone was added
warning.code string Always USERS_NOT_ADDED
warning.message string Explains why the addition may not have gone through
warning.notAdded number[] Identifiers from userIds that are not in the chat roster
warning.addedAtLeast number How many of the requested users were added

Response example

JSON 
{
  "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:

JSON 
{
  "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:

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

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
404 BOT_NOT_FOUND No bot found with this ID
403 BOT_ACCESS_DENIED The bot belongs to another API key
502 BITRIX_ERROR Bitrix24 error (error text in message)
403 SCOPE_DENIED The API key does not have the imbot scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The response stays successful even when not everyone is added. Inactive employees and non-existent identifiers never end up in the chat. Missing permissions and extranet restrictions can also be the cause. The HTTP status stays successful in that case and data.result is true — the ones left out are listed in warning.notAdded. Check the response for warning, not just success.

The roster check is best-effort. The participant list is requested with 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