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

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 Req. Description
fields.title string no Chat name
fields.description string no Chat description
fields.color string no Chat color (16 named colors). If the value is invalid, a color is assigned automatically
fields.avatar string no Chat avatar URL
fields.userIds number[] no Array of user IDs to add
fields.ownerId number no Owner ID. If not specified, the bot becomes the owner
fields.message string no First 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()
console.log('Chat ID:', data.chatId)

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
chat.id number ID of the created chat
chat.dialogId string Dialog ID (chatXXX)
chat.name string Chat name
chat.owner number Owner ID
chat.type string Chat type
chat.color string Chat color
chat.dateCreate string Creation date (ISO 8601)
chat.permissions object Chat permissions
users array Array 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
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 while creating the chat
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

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