Pour les agents IA : markdown de cette page — /docs-content-en/bots/chats.md index de la documentation — /llms.txt

Les articles de documentation sont actuellement disponibles en anglais.

Chats

Create group chats on behalf of the bot, configure them, add and remove participants, assign managers and an owner.

Scope: imbot | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Create a chat

POST /v1/bots/:botId/chats

Creates a new group chat on behalf of the bot.

Request fields (body)

Parameter Type Required Description
Parameterfields.title Typestring Requiredno DescriptionChat name
Parameterfields.description Typestring Requiredno DescriptionChat description
Parameterfields.color Typestring Requiredno DescriptionChat color (16 named colors). If the value is invalid, a color is assigned automatically
Parameterfields.avatar Typestring Requiredno DescriptionChat avatar URL
Parameterfields.userIds Typenumber[] Requiredno DescriptionArray of user IDs to add
Parameterfields.ownerId Typenumber Requiredno DescriptionOwner ID. If not specified, the bot becomes the owner
Parameterfields.message Typestring Requiredno DescriptionFirst message in the chat

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/chats \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "title": "Support chat",
      "description": "Technical support channel",
      "userIds": [1, 5, 12],
      "color": "AZURE"
    }
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/chats \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "title": "Support chat",
      "description": "Technical support channel",
      "userIds": [1, 5, 12],
      "color": "AZURE"
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/chats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      title: 'Support chat',
      description: 'Technical support channel',
      userIds: [1, 5, 12],
      color: 'AZURE',
    },
  }),
})

const { success, data } = await res.json()
// Later chat requests need dialogId, not the numeric chat.id
console.log('Dialog ID:', data.chat.dialogId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/chats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      title: 'Support chat',
      description: 'Technical support channel',
      userIds: [1, 5, 12],
      color: 'AZURE',
    },
  }),
})

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

Response fields

Field Type Description
Fieldchat.id Typenumber DescriptionNumeric chat ID in Bitrix24. Later chat requests do not accept it
Fieldchat.dialogId Typestring DescriptionDialog ID (chatXXX). Pass this one as :dialogId to GET /v1/bots/:botId/chats/:dialogId and the other chat actions: a bare number there means the personal dialog with the user of that ID
Fieldchat.name Typestring DescriptionChat name
Fieldchat.owner Typenumber DescriptionOwner ID
Fieldchat.type Typestring DescriptionChat type
Fieldchat.color Typestring DescriptionChat color
Fieldchat.dateCreate Typestring DescriptionCreation date (ISO 8601)
Fieldchat.permissions Typeobject DescriptionChat permissions
Fieldusers Typearray DescriptionArray of chat participants

Response example

JSON 
{
  "success": true,
  "data": {
    "chat": {
      "id": 3555,
      "dialogId": "chat3555",
      "name": "Support chat",
      "type": "chat",
      "owner": 42,
      "color": "#4ba984",
      "description": "",
      "dateCreate": "2026-04-13T17:12:03+00:00",
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageSettings": "owner",
        "canPost": "member"
      }
    },
    "users": [
      {
        "id": 42,
        "name": "Support",
        "active": true,
        "bot": true
      }
    ]
  }
}

Error response example

404 — bot not found:

JSON 
{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 999 not found. Register it first via POST /v1/bots."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP404 CodeBOT_NOT_FOUND DescriptionNo bot found with this ID
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot belongs to another API key
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 error while creating the chat
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled and does not process API calls. How to restore it — Bot disabled
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Default owner: if ownerId is not specified, the bot becomes the chat owner.

Invalid colors: if you pass a non-existent color, Bitrix24 assigns a color automatically.

See also