Chats and messages

Work with the Bitrix24 messenger on behalf of the authorized user: find CRM entity chats, read and send messages, manage members, upload files, and receive events via polling.

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

Quick start | Full example | Endpoint reference | Error codes

Documentation sections

• Links and guests — chat links for employees, joining by code, guest links and invitations by email and SMS
• Chat discovery — recent dialogs, unread counters, folders, access checks and external IDs, channels, collabs and external chats, shared chats, changes since a given time, CRM entity chats, search and dialog details
• Messages — reading, loading, context, sending, editing, deleting, marking as read, "read later", bulk loading
• Chat management — group chats, ownership, notifications, the unread mark, joining, parent chats, deletion, pinning, marking all chats or a list section as read, leaving
• Members — members, mentionable users, membership checks and managers, adding and removing
• Files — uploading files to a chat, uploading without posting and publishing uploaded files, saving them to Drive, transcribing audio, file metadata, the chat folder on Drive
• CoPilot — the CoPilot draft chat, the assistant's model and role, regenerating and rating answers
• Stickers — sticker packs, adding other users' packs, deletion, recent stickers
• Messenger settings — the user's general settings, status
• Service methods — task and flow forms, context for bots, Zoom, the state of updates, plan restrictions, promo hints, the user's department, desktop app logout
• Events — subscribing, polling messenger events, unsubscribing

Message formatting

References for formatting text when sending and editing messages:

• Text formatting (BB codes)
• Keyboard
• Attachments

Chat identifiers

Two kinds of identifiers appear in requests:

• dialogId — the dialog identifier: a number (user ID) for a private conversation, or a string of the form chatN (for example, chat123) for group chats.
• chatId — the numeric chat ID without the chat prefix. Required for managing the chat, members, and files.

Instead of your own identifier, you can pass the literal me — it is replaced with the ID of the current user who owns the key. This lets you send a message to yourself without requesting your own ID with a separate call. The literal is written in lowercase and works everywhere dialogId is accepted. The exception is marking as read, which accepts me only in v2 mode.

Example — send yourself a notification:

curl -X POST "https://vibecode.bitrix24.com/v1/chats/me/messages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Quarterly report is ready"}'

Direct message to a user

To send a direct message to a specific user, pass their numeric Bitrix24 user ID as the dialogId. No separate lookup or dialog creation is needed — POST /v1/chats/:dialogId/messages with a numeric dialogId delivers the message to a private conversation with that user. The chat lookup GET /v1/chats/find finds CRM entity chats and is not required for a private dialog.

A user's numeric ID comes from the user list GET /v1/users.

curl -X POST "https://vibecode.bitrix24.com/v1/chats/42/messages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Sales digest for today is ready"}'

Quick start

Find the chat of a CRM deal, read the messages, and send a reply.

1. Find the deal chat

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/chats/find?entityType=CRM&entityId=DEAL|123"

Response:

{
  "success": true,
  "data": {
    "id": 2741
  }
}

data.id is the numeric chatId. To build the dialogId when calling the message endpoints, add the chat prefix: chat2741.

2. Read the messages

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/chats/chat2741/messages?limit=5"

Response:

{
  "success": true,
  "data": {
    "chatId": 2741,
    "messages": [
      {
        "id": 9357,
        "chatId": 2741,
        "authorId": 1,
        "date": "2026-04-26T18:10:54+00:00",
        "text": "Team, the proposal is approved. We can issue the invoice.",
        "unread": false
      }
    ],
    "users": [
      {
        "id": 1,
        "name": "John Brown",
        "firstName": "John",
        "lastName": "Brown"
      }
    ],
    "files": []
  }
}

3. Send a reply

curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat2741/messages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Invoice issued. Number: INV-2026-0458"}'

Response:

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

data is the ID of the sent message.

Full example

An end-to-end scenario: create a group chat, send a greeting, mark the conversation as read, rename the chat, and leave it.

const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'

async function api(method, path, body = null) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.json()
}

// 1. Create a group chat
const created = await api('POST', '/chats', {
  title: 'Working group',
  users: [1, 5, 12],
})
const chatId = created.data            // numeric chatId
const dialogId = `chat${chatId}`       // dialogId for the message endpoints
console.log('Chat created, ID:', chatId)

// 2. Send a greeting
const sent = await api('POST', `/chats/${dialogId}/messages`, {
  message: 'Welcome to the working group!',
})
console.log('Message sent, ID:', sent.data)

// 3. Mark the conversation as read
const read = await api('POST', `/chats/${dialogId}/read`, {})
console.log('Unread remaining:', read.data.counter)

// 4. Rename the chat — management calls use the numeric chatId, without the chat prefix
await api('PATCH', `/chats/${chatId}`, {
  title: 'Project: Equipment delivery',
})

// 5. Leave the chat
await api('POST', `/chats/${chatId}/leave`, {})
console.log('Done')

If you are the chat owner, first transfer ownership via POST /v1/chats/:chatId/owner, then leave the chat — otherwise you will leave the chat but remain its owner.

Endpoint reference

All 150 endpoints in this section:

Error codes

Chat errors

Bitrix24 error codes arrive in error.b24Code with 422 BITRIX_ERROR. For chat pinning these are FOLDER_PINS_LIMIT_EXCEEDED — 45 chats are already pinned, and INVALID_PIN_POSITION — position is greater than 45 when changing the pinned chat order.

System errors

General codes for authorization, keys, and limits are on the Errors page.

See also

• Bot platform
• Notifications
• Keys and authorization
• Limits and optimization
• Errors reference