#Chats and messages

Work with the Bitrix24 messenger on behalf of the authorized user: find chats of CRM entities, 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

• Chat discovery — list of recent dialogs, finding a CRM entity chat, text search, dialog details
• Messages — read, send, edit, delete, mark as read, bulk loading
• Chat management — creating group chats, renaming, transferring ownership, leaving
• Members — list of members, adding, removing
• Files — uploading files to a chat, file metadata, the chat folder on Drive
• Events — subscribe, poll messenger events, unsubscribe

#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, 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: dialog details, reading and sending messages, list of members.

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 personal 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 chats of CRM entities 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": 253,
    "messages": [
      {
        "id": 9357,
        "chatId": 253,
        "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

A continuous 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 is done by 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 23 endpoints of the section:

#Error codes

Codes specific to working with chats:

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