# 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](#quick-start) | [Full example](#full-example) | [Endpoint reference](#endpoint-reference) | [Error codes](#error-codes)

## Documentation sections

- [Links and guests](/docs/chats/sharing) — chat links for employees, joining by code, guest links and invitations by email and SMS
- [Chat discovery](/docs/chats/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](/docs/chats/messages) — reading, loading, context, sending, editing, deleting, marking as read, "read later", bulk loading
- [Chat management](/docs/chats/management) — group chats, ownership, notifications, the unread mark, joining, parent chats, deletion, pinning, marking all chats or a list section as read, leaving
- [Members](/docs/chats/members) — members, mentionable users, membership checks and managers, adding and removing
- [Files](/docs/chats/files) — uploading files to a chat, uploading without posting, publishing uploaded files, saving them to Drive, transcribing audio, file metadata, the chat folder on Drive
- [CoPilot](/docs/chats/copilot) — the CoPilot draft chat, the assistant's model and role, regenerating and rating answers
- [Stickers](/docs/chats/stickers) — sticker packs, adding other users' packs, deletion, recent stickers
- [Messenger settings](/docs/chats/settings) — the user's general settings, status
- [Service methods](/docs/chats/service) — task and flow forms, context for bots, Zoom, the state of updates, plan restrictions, promo hints, the user's department, desktop app logout
- [Events](/docs/chats/events) — subscribing, polling messenger events, unsubscribing

## Message formatting

References for formatting text when sending and editing messages:

- [Text formatting (BB codes)](/docs/chats/messages/formatting)
- [Keyboard](/docs/chats/messages/keyboard)
- [Attachments](/docs/chats/messages/attach)

## 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:

```bash
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`](/docs/chats/messages/send) with a numeric `dialogId` delivers the message to a private conversation with that user. The chat lookup [`GET /v1/chats/find`](/docs/chats/discovery/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`](/docs/entities/users).

```bash
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

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

Response:

```json
{
  "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

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

Response:

```json
{
  "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

```bash
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:

```json
{
  "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.

```javascript
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`](/docs/chats/management/owner), then leave the chat — otherwise you will leave the chat but remain its owner.

## Endpoint reference

All 154 endpoints in this section:

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|---------|
| GET | [/v1/chats/recent](/docs/chats/discovery/recent) | im.recent.list; with `format=v2` — im.v2.Recent.load, im.v2.Recent.tail | Recent dialogs |
| GET | [/v1/chats/counters](/docs/chats/discovery/counters) | im.v2.Counter.get | Unread counters |
| GET | [/v1/chats/recent/channels](/docs/chats/discovery/recent-channels) | im.v2.Recent.Channel.tail | Channel list |
| GET | [/v1/chats/recent/collabs](/docs/chats/discovery/recent-collabs) | im.v2.Recent.Collab.tail | Collab list |
| GET | [/v1/chats/projects/:projectId/recent](/docs/chats/discovery/project-recent) | im.v2.Recent.load, im.v2.Recent.tail | Project chats |
| GET | [/v1/chats/recent/external](/docs/chats/discovery/recent-external) | im.v2.Recent.ExternalChat.tail | External chats of a section |
| GET | [/v1/chats/shared](/docs/chats/discovery/shared) | im.v2.Chat.listShared | Shared chats with a user |
| GET | [/v1/chats/sync](/docs/chats/discovery/sync) | im.v2.Sync.list | Chat changes since a given time |
| GET | [/v1/chats/find](/docs/chats/discovery/find) | im.chat.get | Find a CRM entity chat |
| GET | [/v1/chats/search](/docs/chats/discovery/search) | im.search.chat.list | Search chats by text |
| GET | [/v1/chats/folders](/docs/chats/discovery/folders) | im.v2.Folder.list | Chat folders |
| GET | [/v1/chats/folders/:folderId/recent](/docs/chats/discovery/folder-recent) | im.v2.Folder.Recent.tail | Folder chats |
| GET | [/v1/chats/:dialogId](/docs/chats/discovery/get) | im.dialog.get; with `format=v2` — im.v2.Chat.get | Dialog details |
| GET | [/v1/chats/:dialogId/messages](/docs/chats/messages/list) | im.dialog.messages.get; with `format=v2` — im.v2.Chat.Message.tail | Read messages |
| GET | [/v1/chats/:dialogId/load](/docs/chats/messages/load) | im.v2.Chat.load; with `shallow=true` — im.v2.Chat.shallowLoad | Load a chat |
| GET | [/v1/chats/messages/:messageId/context](/docs/chats/messages/context) | im.v2.Chat.Message.getContext | Messages around a message |
| GET | [/v1/chats/:dialogId/messages/initial](/docs/chats/messages/initial) | im.v2.Chat.Message.list | First page of a chat |
| GET | [/v1/chats/messages/:messageId/viewers](/docs/chats/messages/viewers) | im.v2.Chat.Message.tailViewers | Who viewed a message |
| POST | [/v1/chats/:dialogId/messages](/docs/chats/messages/send) | im.message.add; with `format=v2` — im.v2.Chat.Message.send | Send a message |
| PATCH | [/v1/chats/:dialogId/messages/:messageId](/docs/chats/messages/update) | im.message.update; with `format=v2` — im.v2.Chat.Message.update | Edit a message |
| DELETE | [/v1/chats/:dialogId/messages/:messageId](/docs/chats/messages/delete) | im.message.delete; with `format=v2` — im.v2.Chat.Message.delete | Delete a message |
| POST | [/v1/chats/messages/:messageId/disappear](/docs/chats/messages/disappear) | im.v2.Chat.Message.disappear | Disappearing message |
| POST | [/v1/chats/messages/:messageId/inform](/docs/chats/messages/inform) | im.v2.Chat.Message.inform | Notify a recipient in Do Not Disturb mode |
| DELETE | [/v1/chats/messages/:messageId/url-preview](/docs/chats/messages/url-preview) | im.v2.Chat.Message.deleteRichUrl | Remove a link preview |
| POST | [/v1/chats/:dialogId/read](/docs/chats/messages/read) | im.dialog.read; with `format=v2` — im.v2.Chat.read | Mark as read |
| POST | [/v1/chats/messages/read](/docs/chats/messages/read-messages) | im.v2.Chat.Message.read | Mark messages as read |
| POST | [/v1/chats/messages/:messageId/mark](/docs/chats/messages/mark) | im.v2.Chat.Message.mark | Read later |
| POST | [/v1/chats/messages/bulk](/docs/chats/messages/bulk) | batch (im.dialog.messages.get) | Bulk loading from several dialogs |
| GET | [/v1/chats/:dialogId/messages/search](/docs/chats/messages/search) | im.v2.Chat.Message.search | Search messages in a chat |
| POST | [/v1/chats/:dialogId/forward](/docs/chats/messages/forward) | im.v2.Chat.Message.send | Forward messages |
| GET | [/v1/chats/messages/:messageId/reactions](/docs/chats/messages/reactions-list) | im.v2.Chat.Message.Reaction.tail | List reactions |
| POST | [/v1/chats/messages/:messageId/reactions](/docs/chats/messages/reactions-create) | im.v2.Chat.Message.Reaction.add | Add a reaction |
| DELETE | [/v1/chats/messages/:messageId/reactions/:reaction](/docs/chats/messages/reactions-delete) | im.v2.Chat.Message.Reaction.delete | Remove a reaction |
| GET | [/v1/chats/:dialogId/pins](/docs/chats/messages/pins) | im.v2.Chat.Pin.tail | List pins |
| POST | [/v1/chats/messages/:messageId/pin](/docs/chats/messages/pins-create) | im.v2.Chat.Message.pin | Pin a message |
| DELETE | [/v1/chats/messages/:messageId/pin](/docs/chats/messages/pins-delete) | im.v2.Chat.Message.unpin | Unpin a message |
| GET | [/v1/chats/:dialogId/pins/count](/docs/chats/messages/pins-count) | im.v2.Chat.Pin.count | Number of pinned messages |
| POST | [/v1/chats/:dialogId/typing](/docs/chats/messages/typing) | im.v2.Chat.InputAction.notify | Typing indicator |
| GET | [/v1/chats/anchors](/docs/chats/messages/anchors-list) | im.v2.Anchor.list | List unread mention and reaction marks (not available on every Bitrix24 account) |
| POST | [/v1/chats/:dialogId/anchors/read](/docs/chats/messages/anchors) | im.v2.Chat.Anchor.read | Remove chat anchors |
| POST | [/v1/chats/anchors/read](/docs/chats/messages/anchors-messages) | im.v2.Anchor.read | Remove message anchors |
| GET | [/v1/chats/messages/comments](/docs/chats/messages/comments) | im.v2.Chat.Message.CommentInfo.list | Comment summary for posts |
| POST | [/v1/chats/:dialogId/comments/read-all](/docs/chats/messages/comments-read-all) | im.v2.Chat.Comment.readAll | Mark all channel comments as read |
| POST | [/v1/chats/messages/:messageId/comments/subscription](/docs/chats/messages/comments-subscription-create) | im.v2.Chat.Comment.subscribe | Follow the comments of a post |
| DELETE | [/v1/chats/messages/:messageId/comments/subscription](/docs/chats/messages/comments-subscription-delete) | im.v2.Chat.Comment.unsubscribe | Stop following the comments of a post |
| POST | [/v1/chats/messages/:messageId/comments/chat](/docs/chats/messages/comments-chat) | im.v2.Chat.load | Open the discussion of a post |
| POST | [/v1/chats/messages/:messageId/blocks](/docs/chats/messages/blocks-create) | im.v2.Chat.Message.Block.Element.append | Add a block to a message |
| PATCH | [/v1/chats/messages/:messageId/blocks/:blockId](/docs/chats/messages/blocks-update) | im.v2.Chat.Message.Block.Element.update | Replace a block of a message |
| DELETE | [/v1/chats/messages/:messageId/blocks/:blockId](/docs/chats/messages/blocks-delete) | im.v2.Chat.Message.Block.Element.delete | Remove a block from a message |
| GET | [/v1/chats/:dialogId/commands](/docs/chats/commands) | im.v2.Chat.Command.list | Bot commands in a chat |
| POST | [/v1/chats/messages/:messageId/command](/docs/chats/messages/command) | im.message.command | Execute a bot command |
| POST | [/v1/chats/messages/:messageId/unread](/docs/chats/messages/unread) | im.dialog.unread | Mark as unread from a message |
| POST | [/v1/chats](/docs/chats/management/create) | im.chat.add; with `format=v2` — im.v2.Chat.add | Create a group chat |
| PATCH | [/v1/chats/:chatId](/docs/chats/management/rename) | im.chat.updateTitle; with `format=v2` — im.v2.Chat.update | Rename a chat |
| POST | [/v1/chats/:chatId/owner](/docs/chats/management/owner) | im.chat.setOwner; with `format=v2` — im.v2.Chat.setOwner | Transfer ownership |
| POST | [/v1/chats/:chatId/leave](/docs/chats/management/leave) | im.chat.leave | Leave a chat |
| POST | [/v1/chats/:chatId/mute](/docs/chats/management/mute) | im.chat.mute | Mute or unmute chat notifications |
| PUT | [/v1/chats/:dialogId/description](/docs/chats/management/description) | im.v2.Chat.setDescription | Change a chat description |
| PUT | [/v1/chats/:dialogId/color](/docs/chats/management/color) | im.v2.Chat.setColor | Change a chat color |
| PUT | [/v1/chats/:dialogId/avatar](/docs/chats/management/avatar) | im.v2.Chat.setAvatar; with the `avatarId` field — im.v2.Chat.setAvatarId | Change a chat avatar |
| PUT | [/v1/chats/:dialogId/permissions/messages](/docs/chats/management/permissions-messages) | im.v2.Chat.setManageMessages | Who posts messages |
| PUT | [/v1/chats/:dialogId/permissions/guest-invites](/docs/chats/management/permissions-guest-invites) | im.v2.Chat.setManageGuestInvites | Who invites guests |
| PUT | [/v1/chats/:dialogId/permissions/settings](/docs/chats/management/permissions-settings) | im.v2.Chat.setManageSettings | Who changes chat permissions |
| PUT | [/v1/chats/:dialogId/permissions/ui](/docs/chats/management/permissions-ui) | im.v2.Chat.setManageUI | Who changes the chat's appearance |
| PUT | [/v1/chats/:dialogId/permissions/users-add](/docs/chats/management/permissions-users-add) | im.v2.Chat.setManageUsersAdd | Who adds members |
| PUT | [/v1/chats/:dialogId/permissions/users-delete](/docs/chats/management/permissions-users-delete) | im.v2.Chat.setManageUsersDelete | Who removes members |
| PUT | [/v1/chats/:dialogId/auto-delete](/docs/chats/management/auto-delete) | im.v2.Chat.setMessagesAutoDeleteDelay | Configure message auto-delete |
| GET | [/v1/chats/:dialogId/users](/docs/chats/members/list) | im.dialog.users.list; with `format=v2` — im.v2.Chat.Member.tail | List of members |
| POST | [/v1/chats/:chatId/users](/docs/chats/members/add) | im.chat.user.add; with `format=v2` — im.v2.Chat.addUsers | Add members |
| DELETE | [/v1/chats/:chatId/users](/docs/chats/members/remove) | im.chat.user.delete; with `format=v2` — im.v2.Chat.deleteUser | Remove a member |
| POST | [/v1/chats/:dialogId/managers](/docs/chats/members/managers-add) | im.v2.Chat.addManagers | Add managers |
| PUT | [/v1/chats/:dialogId/managers](/docs/chats/members/managers-set) | im.v2.Chat.setManagers | Replace managers |
| DELETE | [/v1/chats/:dialogId/managers](/docs/chats/members/managers-remove) | im.v2.Chat.deleteManagers | Remove managers |
| GET | [/v1/chats/:dialogId/member-entities](/docs/chats/members/member-entities) | im.v2.Chat.MemberEntities.list | Chat members as entities |
| GET | [/v1/chats/:dialogId/users/active](/docs/chats/members/active) | im.v2.Chat.User.list | Active members |
| GET | [/v1/chats/:dialogId/users/relations](/docs/chats/members/relations) | im.v2.Chat.Member.filterUsersByParticipation | Membership records |
| GET | [/v1/chats/access](/docs/chats/discovery/access) | im.v2.Access.check | Check access to a chat or message |
| POST | [/v1/chats/dialog-id](/docs/chats/discovery/dialog-id) | im.v2.Chat.getDialogId | Dialog ID by external identifier |
| GET | [/v1/chats/messages/:messageId/load](/docs/chats/messages/load-in-context) | im.v2.Chat.loadInContext | Load around a message |
| POST | [/v1/chats/:dialogId/join](/docs/chats/management/join) | im.v2.Chat.join | Join a chat |
| PUT | [/v1/chats/:dialogId/parent](/docs/chats/management/parent) | im.v2.Chat.attachToParent | Attach to a parent chat |
| DELETE | [/v1/chats/:dialogId/parent](/docs/chats/management/parent-delete) | im.v2.Chat.detachFromParent | Detach from the parent chat |
| DELETE | [/v1/chats/:dialogId](/docs/chats/management/delete) | im.v2.Chat.delete | Delete a chat — irreversible |
| POST | [/v1/chats/:dialogId/history/clear](/docs/chats/management/history-clear) | im.v2.Chat.clearHistory / im.v2.Chat.clearHistoryForAll | Clear history for the caller or everyone |
| POST | [/v1/chats/:dialogId/unread](/docs/chats/management/unread-create) | im.v2.Chat.unread | Set the "unread" mark |
| DELETE | [/v1/chats/:dialogId/unread](/docs/chats/management/unread-delete) | im.v2.Chat.read | Clear the "unread" mark |
| POST | [/v1/chats/folders](/docs/chats/management/folders-create) | im.v2.Folder.add | Create a chat folder |
| GET | [/v1/chats/folders/:folderId](/docs/chats/management/folders-get) | im.v2.Folder.get | A folder with its chats |
| PATCH | [/v1/chats/folders/:folderId](/docs/chats/management/folders-update) | im.v2.Folder.update | Rename a folder, replace its contents |
| DELETE | [/v1/chats/folders/:folderId](/docs/chats/management/folders-delete) | im.v2.Folder.delete | Delete a folder |
| PUT | [/v1/chats/folders/order](/docs/chats/management/folders-order) | im.v2.Folder.sort | Folder order |
| POST | [/v1/chats/folders/:folderId/chats](/docs/chats/management/folder-chats) | im.v2.Folder.addChats | Add chats to a folder |
| DELETE | [/v1/chats/folders/:folderId/chats](/docs/chats/management/folder-chats-delete) | im.v2.Folder.deleteChats | Remove chats from a folder |
| PUT | [/v1/chats/:dialogId/folders](/docs/chats/management/folder-chats-set) | im.v2.Folder.setChatFolders | Set the folders of a chat |
| GET | [/v1/chats/folders/:folderId/sources](/docs/chats/management/folder-sources) | im.v2.Folder.getSources | Sources of the "All" folder (not available on every Bitrix24 account) |
| PUT | [/v1/chats/folders/:folderId/sources](/docs/chats/management/folder-sources-update) | im.v2.Folder.updateSources | Set the sources of the "All" folder (not available on every Bitrix24 account) |
| POST | [/v1/chats/:dialogId/pin](/docs/chats/management/pin) | im.v2.Chat.pin | Pin a chat |
| PUT | [/v1/chats/:dialogId/pin](/docs/chats/management/pin-sort) | im.v2.Chat.sortPin | Pinned chat order |
| DELETE | [/v1/chats/:dialogId/pin](/docs/chats/management/unpin) | im.v2.Chat.unpin | Unpin a chat |
| POST | [/v1/chats/read-all](/docs/chats/management/read-all) | im.v2.Chat.readAll | Mark all chats as read |
| POST | [/v1/chats/recent/read](/docs/chats/management/read-section) | im.v2.Chat.readByRecentSection | Mark a list section as read |
| GET | [/v1/chats/:dialogId/users/mentionable](/docs/chats/members/mentionable) | im.v2.Chat.Mention.list | Users to mention |
| GET | [/v1/chats/:dialogId/users/membership](/docs/chats/members/membership) | im.v2.Chat.Member.checkMembership | Membership check |
| POST | [/v1/chats/:chatId/files](/docs/chats/files/upload) | im.disk.folder.get + disk.folder.uploadfile + im.disk.file.commit; with `format=v2` — im.v2.File.upload | Upload a file to a chat |
| POST | [/v1/chats/:chatId/files/uploads](/docs/chats/files/upload-to-folder) | im.v2.File.uploadToFolder | Upload a file to a chat folder without posting |
| POST | [/v1/chats/files/uploads/status](/docs/chats/files/upload-status) | im.v2.File.download | Check whether an uploaded file exists |
| POST | [/v1/chats/:chatId/files/uploads/discard](/docs/chats/files/upload-discard) | im.disk.file.delete | Discard an uploaded file |
| POST | [/v1/chats/:chatId/files/uploads/publish](/docs/chats/files/upload-publish) | im.disk.file.commit | Publish uploaded files |
| GET | [/v1/chats/files/:fileId](/docs/chats/files/file-get) | disk.file.get | File metadata |
| GET | [/v1/chats/:chatId/folder](/docs/chats/files/folder) | im.disk.folder.get | Chat folder on Drive |
| POST | [/v1/chats/:dialogId/sharing-links/primary](/docs/chats/sharing/primary-link) | im.v2.Chat.SharingLink.getPrimary | Get the primary chat link |
| POST | [/v1/chats/:dialogId/sharing-links/individual](/docs/chats/sharing/individual-link) | im.v2.Chat.SharingLink.getIndividual | Get an individual chat link |
| POST | [/v1/chats/:dialogId/sharing-links/individual/regenerate](/docs/chats/sharing/individual-link-regenerate) | im.v2.Chat.SharingLink.regenerateIndividual | Regenerate an individual link |
| GET | [/v1/chats/sharing-links/:code](/docs/chats/sharing/link-get) | im.v2.SharingLink.get | Get a link by code |
| DELETE | [/v1/chats/sharing-links/:code](/docs/chats/sharing/link-revoke) | im.v2.Chat.SharingLink.revoke | Revoke a link by code |
| POST | [/v1/chats/join-by-code](/docs/chats/sharing/join) | im.v2.Chat.joinByCode | Join a chat by code |
| POST | [/v1/chats/:dialogId/guest-links](/docs/chats/sharing/guest-link) | im.v2.Guest.Link.generate | Get a guest link |
| POST | [/v1/chats/:dialogId/guest-links/regenerate](/docs/chats/sharing/guest-link-regenerate) | im.v2.Guest.Link.regenerate | Regenerate a guest link |
| DELETE | [/v1/chats/:dialogId/guest-links](/docs/chats/sharing/guest-link-revoke) | im.v2.Guest.Link.revoke | Revoke a guest link |
| POST | [/v1/chats/:dialogId/guest-invites/email](/docs/chats/sharing/invite-email) | im.v2.Guest.Link.inviteByEmail | Invite guests by email |
| POST | [/v1/chats/:dialogId/guest-invites/phone](/docs/chats/sharing/invite-phone) | im.v2.Guest.Link.inviteByPhoneNumber | Invite guests by SMS |
| GET | [/v1/chats/stickers/packs](/docs/chats/stickers/packs) | im.v2.Sticker.Pack.load; with a cursor — im.v2.Sticker.Pack.tail | List sticker packs |
| GET | [/v1/chats/stickers/packs/:packId](/docs/chats/stickers/pack-get) | im.v2.Sticker.Pack.get | Sticker pack |
| PATCH | [/v1/chats/stickers/packs/:packId](/docs/chats/stickers/pack-update) | im.v2.Sticker.Pack.rename | Rename a pack |
| DELETE | [/v1/chats/stickers/packs/:packId](/docs/chats/stickers/pack-delete) | im.v2.Sticker.Pack.delete | Delete a pack |
| POST | [/v1/chats/stickers/packs/:packId/link](/docs/chats/stickers/link-create) | im.v2.Sticker.Pack.link | Add a pack |
| DELETE | [/v1/chats/stickers/packs/:packId/link](/docs/chats/stickers/link-delete) | im.v2.Sticker.Pack.unlink | Remove a pack |
| DELETE | [/v1/chats/stickers/packs/:packId/stickers](/docs/chats/stickers/pack-stickers) | im.v2.Sticker.delete | Delete stickers from a pack |
| DELETE | [/v1/chats/stickers/recent](/docs/chats/stickers/recent) | im.v2.Sticker.Recent.deleteAll | Clear recent stickers |
| DELETE | [/v1/chats/stickers/recent/:stickerId](/docs/chats/stickers/recent-delete) | im.v2.Sticker.Recent.delete | Remove a recent sticker |
| POST | [/v1/chats/files/save](/docs/chats/files/save) | im.v2.Disk.File.save | Save files to Drive |
| POST | [/v1/chats/files/:fileId/transcribe](/docs/chats/files/transcribe) | im.v2.Disk.File.transcribe | Transcribe an audio file |
| GET | [/v1/chats/transcription/config](/docs/chats/files/transcribe-transcription-config) | im.v2.Application.config | Get transcription settings |
| POST | [/v1/chats/copilot/draft](/docs/chats/copilot/draft) | im.v2.Copilot.DraftChat.get | CoPilot draft chat |
| PUT | [/v1/chats/:dialogId/copilot/engine](/docs/chats/copilot/engine) | im.v2.Chat.Copilot.updateEngine | Change the CoPilot model |
| PUT | [/v1/chats/:dialogId/copilot/role](/docs/chats/copilot/role) | im.v2.Chat.Copilot.updateRole | Change the CoPilot role |
| POST | [/v1/chats/messages/:messageId/regenerate](/docs/chats/copilot/regenerate) | im.v2.Copilot.Message.regenerate | Regenerate a CoPilot answer |
| POST | [/v1/chats/messages/:messageId/vote](/docs/chats/copilot/vote) | im.v2.Chat.Message.Vote.send | Rate an answer |
| GET | [/v1/chats/settings](/docs/chats/settings/list) | im.v2.Settings.General.list | General messenger settings |
| PATCH | [/v1/chats/settings](/docs/chats/settings/update) | im.v2.Settings.General.update | Change a setting |
| PUT | [/v1/chats/settings/status](/docs/chats/settings/status) | im.v2.Settings.Status.update | Set the status |
| GET | [/v1/chats/:dialogId/task-form](/docs/chats/service/task-form) | im.v2.Chat.Task.prepare | Task form for a chat |
| POST | [/v1/chats/messages/:messageId/task-form](/docs/chats/service/task-form-message) | im.v2.Chat.Task.prepare | Task form for a message |
| GET | [/v1/chats/:dialogId/flow-form](/docs/chats/service/flow-form) | im.v2.Chat.Flow.prepare | Collab flow form |
| POST | [/v1/chats/:dialogId/bot-context](/docs/chats/service/bot-context) | im.v2.Chat.Bot.sendContext | Context for chat bots |
| POST | [/v1/chats/:dialogId/zoom](/docs/chats/service/zoom) | im.v2.Call.Zoom.create | Zoom meeting |
| GET | [/v1/chats/state](/docs/chats/service/state) | im.v2.UpdateState.getStateData | State of updates |
| GET | [/v1/chats/tariff-restrictions](/docs/chats/service/tariff-restrictions) | im.v2.Tariff.Restriction.get | Plan restrictions |
| GET | [/v1/chats/promotions](/docs/chats/service/promotions) | im.v2.Promotion.listActive | Promo hints |
| GET | [/v1/chats/users/:userId/department](/docs/chats/service/department) | im.v2.User.getDepartment | User department |
| POST | [/v1/chats/desktop/logout](/docs/chats/service/desktop-logout) | im.v2.Desktop.logout | Desktop app logout |
| POST | [/v1/chats/events/subscribe](/docs/chats/events/subscribe) | im.v2.Event.subscribe | Subscribe to events |
| POST | [/v1/chats/events/unsubscribe](/docs/chats/events/unsubscribe) | im.v2.Event.unsubscribe | Unsubscribe from events |
| GET | [/v1/chats/events](/docs/chats/events/poll) | im.v2.Event.get | Get events |

## Error codes

### Chat errors

| Code | HTTP | Description |
|-----|------|---------|
| `MISSING_PARAMS` | 400 | Required parameters were not passed, for example `entityType`/`entityId` when finding a CRM entity chat, `filename`/`content` when uploading a file, `users` or `userId` when adding and removing members |
| `INVALID_REQUEST` | 400 | Malformed request body (for example, an empty `dialogs` array in bulk loading) |
| `BATCH_LIMIT_EXCEEDED` | 400 | Bulk loading exceeds the limit of 50 dialogs |
| `INVALID_CHAT_ID` | 400 | `chatId` is not a positive integer |
| `INVALID_PARAMS` | 400 | Invalid `messageId` or `fileId`. For `format=v2`, `load`, `counters`, `context`, links and guests, folders, unread and read-later marks, mentions, membership checks, list sections, shared chats, sync, chat pinning, settings and service methods — an unknown, repeated or invalid query parameter or body field. CoPilot, file saving and transcription also reject missing or invalid body fields. Checked before calling Bitrix24. |
| `MESSAGE_REQUIRED` | 400 | Empty text when sending or editing a message |
| `TITLE_EMPTY` | 400 | Empty title when renaming a chat |
| `INVALID_OFFSET` | 400 | Invalid `offset` when polling events |
| `INVALID_LIMIT` | 400 | `limit` when polling events is not an integer from 1 to 1000 |
| `WRONG_PATH` | 400 | `GET /v1/chats` was called — there is no such endpoint. `message` lists the endpoints for recent dialogs, text search, and finding a CRM entity chat |
| `PAYLOAD_TOO_LARGE` | 413 | The request body exceeds the limit: 40 MiB when uploading a file, 1 MiB when setting an avatar from an image |
| `BITRIX_ACCESS_DENIED` | 403 | Bitrix24 refused to change the chat settings: the user is not a chat member, or a chat permission does not allow it |
| `CHAT_NOT_FOUND_OR_NO_ACCESS` | 404 | The chat does not exist or you do not have permission for the operation |
| `DIALOG_NOT_FOUND_OR_NO_ACCESS` | 404 | The dialog does not exist or you do not have access to it |
| `FILE_NOT_FOUND` | 404 | A file with the given `fileId` was not found |
| `FOLDER_NOT_FOUND` | 404 | The chat folder on Drive was not found |
| `UPLOAD_FAILED` | 500 | Failed to upload the file to Drive |
| `ME_ALIAS_RESOLUTION_FAILED` | 502 | Failed to resolve the current user for the `me` alias |

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

| Code | HTTP | Description |
|-----|------|---------|
| `SCOPE_DENIED` | 403 | The API key does not have the `im` scope |
| `TOKEN_MISSING` | 401 | The API key has no Bitrix24 tokens configured |
| `WRITE_BLOCKED_READONLY_KEY` | 403 | A read-only key called an operation that changes data |
| `INVALID_JSON_BODY` | 400 | The request body is not valid JSON |
| `ENTITY_NOT_FOUND` | 404 | The requested object was not found |
| `BITRIX_ERROR` | 422 | Bitrix24 returned an error (text in the `message` field) |
| `METHOD_NOT_YET_AVAILABLE` | 422 | The method is rolling out and is not available on the portal yet — the page of such a method opens with a notice about it |
| `BITRIX_UNAVAILABLE` | 502 | Bitrix24 is unavailable or returned a server error |
| `BITRIX_TIMEOUT` | 503 | Bitrix24 did not respond in time. The outcome of the call is unknown — the method page says how to proceed |

General codes for authorization, keys, and limits are on the [Errors](/docs/errors) page.

## See also

- [Bot platform](/docs/bots)
- [Notifications](/docs/notifications)
- [Keys and authorization](/docs/keys-auth)
- [Limits and optimization](/docs/optimization)
- [Errors reference](/docs/errors)