# Чаты и сообщения

Работайте с мессенджером Битрикс24 от имени авторизованного пользователя: находите чаты CRM-сущностей, читайте и отправляйте сообщения, управляйте участниками, загружайте файлы и получайте события через опрос.

**Скоуп:** `im` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

[Быстрый старт](#быстрый-старт) | [Полный пример](#полный-пример) | [Справочник эндпоинтов](#справочник-эндпоинтов) | [Коды ошибок](#коды-ошибок)

## Разделы документации

- [Поиск чатов](/docs/chats/discovery) — список последних диалогов, поиск чата CRM-сущности, текстовый поиск, информация о диалоге
- [Сообщения](/docs/chats/messages) — чтение, отправка, редактирование, удаление, отметка прочитанными, массовая загрузка
- [Управление чатами](/docs/chats/management) — создание групповых чатов, переименование, передача владения, выход
- [Участники](/docs/chats/members) — список участников, добавление, удаление
- [Файлы](/docs/chats/files) — загрузка файлов в чат, метаданные файла, папка чата на Диске
- [События](/docs/chats/events) — подписка, опрос событий мессенджера, отписка

## Оформление сообщений

Справочники по оформлению текста при отправке и редактировании сообщений:

- [Форматирование текста (BB-коды)](/docs/chats/messages/formatting)
- [Клавиатура](/docs/chats/messages/keyboard)
- [Вложения](/docs/chats/messages/attach)

## Идентификаторы чатов

В запросах встречаются два вида идентификаторов:

- `dialogId` — идентификатор диалога: число (ID пользователя) для личной переписки, строка вида `chatN` (например `chat123`) для групповых чатов.
- `chatId` — числовой ID чата без префикса `chat`. Нужен для управления чатом, участниками и файлами.

Вместо своего идентификатора можно передать литерал `me` — он заменяется на ID текущего пользователя, которому принадлежит ключ. Так можно отправить сообщение самому себе, не запрашивая свой ID отдельным вызовом. Литерал пишется строчными буквами и работает везде, где принимается `dialogId`: информация о диалоге, чтение и отправка сообщений, список участников.

Пример — отправить себе уведомление:

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/me/messages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Квартальный отчёт готов"}'
```

## Личное сообщение сотруднику

Чтобы отправить сотруднику личное сообщение, подставьте его числовой ID пользователя Битрикс24 в качестве `dialogId`. Отдельный поиск или создание диалога не нужны — `POST /v1/chats/:dialogId/messages` с числовым `dialogId` доставляет сообщение в личную переписку с этим сотрудником. Поиск чата [`GET /v1/chats/find`](/docs/chats/discovery/find) находит чаты CRM-сущностей, для личного диалога он не требуется.

Числовой ID сотрудника — из списка пользователей [`GET /v1/users`](/docs/entities/users).

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/42/messages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Дайджест продаж за сегодня готов"}'
```

## Быстрый старт

Найдите чат CRM-сделки, прочитайте сообщения и отправьте ответ.

### 1. Найдите чат сделки

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

Ответ:

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

`data.id` — числовой `chatId`. Для построения `dialogId` при обращении к эндпоинтам сообщений добавьте префикс `chat`: `chat2741`.

### 2. Прочитайте сообщения

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

Ответ:

```json
{
  "success": true,
  "data": {
    "chatId": 253,
    "messages": [
      {
        "id": 9357,
        "chatId": 253,
        "authorId": 1,
        "date": "2026-04-26T18:10:54+03:00",
        "text": "Коллеги, КП утверждено. Можно выставлять счёт.",
        "unread": false
      }
    ],
    "users": [
      {
        "id": 1,
        "name": "Иван Петров",
        "firstName": "Иван",
        "lastName": "Петров"
      }
    ],
    "files": []
  }
}
```

### 3. Отправьте ответ

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/chat2741/messages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Счёт выставлен. Номер: СЧ-2026-0458"}'
```

Ответ:

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

`data` — ID отправленного сообщения.

## Полный пример

Непрерывный сценарий: создать групповой чат, отправить приветствие, отметить переписку прочитанной, переименовать чат и выйти из него.

```javascript
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.tech/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. Создаём групповой чат
const created = await api('POST', '/chats', {
  title: 'Рабочая группа',
  users: [1, 5, 12],
})
const chatId = created.data            // числовой chatId
const dialogId = `chat${chatId}`       // dialogId для эндпоинтов сообщений
console.log('Чат создан, ID:', chatId)

// 2. Отправляем приветствие
const sent = await api('POST', `/chats/${dialogId}/messages`, {
  message: 'Добро пожаловать в рабочую группу!',
})
console.log('Сообщение отправлено, ID:', sent.data)

// 3. Отмечаем переписку прочитанной
const read = await api('POST', `/chats/${dialogId}/read`, {})
console.log('Непрочитанных осталось:', read.data.counter)

// 4. Переименовываем чат — управление идёт по числовому chatId, без префикса chat
await api('PATCH', `/chats/${chatId}`, {
  title: 'Проект: Поставка оборудования',
})

// 5. Выходим из чата
await api('POST', `/chats/${chatId}/leave`, {})
console.log('Готово')
```

> Если вы владелец чата, сначала передайте владение через `POST /v1/chats/:chatId/owner`, затем покидайте чат — иначе выход зафиксируется, но владельцем останетесь вы.

## Справочник эндпоинтов

Все 23 эндпоинта раздела:

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|---------|
| GET | [/v1/chats/recent](/docs/chats/discovery/recent) | im.recent.list | Последние диалоги |
| GET | [/v1/chats/find](/docs/chats/discovery/find) | im.chat.get | Найти чат CRM-сущности |
| GET | [/v1/chats/search](/docs/chats/discovery/search) | im.search.chat.list | Поиск чатов по тексту |
| GET | [/v1/chats/:dialogId](/docs/chats/discovery/get) | im.dialog.get | Информация о диалоге |
| GET | [/v1/chats/:dialogId/messages](/docs/chats/messages/list) | im.dialog.messages.get | Чтение сообщений |
| POST | [/v1/chats/:dialogId/messages](/docs/chats/messages/send) | im.message.add | Отправка сообщения |
| PATCH | [/v1/chats/:dialogId/messages/:messageId](/docs/chats/messages/update) | im.message.update | Редактирование сообщения |
| DELETE | [/v1/chats/:dialogId/messages/:messageId](/docs/chats/messages/delete) | im.message.delete | Удаление сообщения |
| POST | [/v1/chats/:dialogId/read](/docs/chats/messages/read) | im.dialog.read | Отметить прочитанным |
| POST | [/v1/chats/messages/bulk](/docs/chats/messages/bulk) | batch (im.dialog.messages.get) | Массовая загрузка из нескольких диалогов |
| POST | [/v1/chats](/docs/chats/management/create) | im.chat.add | Создать групповой чат |
| PATCH | [/v1/chats/:chatId](/docs/chats/management/rename) | im.chat.updateTitle | Переименовать чат |
| POST | [/v1/chats/:chatId/owner](/docs/chats/management/owner) | im.chat.setOwner | Передать владение |
| POST | [/v1/chats/:chatId/leave](/docs/chats/management/leave) | im.chat.leave | Покинуть чат |
| GET | [/v1/chats/:dialogId/users](/docs/chats/members/list) | im.dialog.users.list | Список участников |
| POST | [/v1/chats/:chatId/users](/docs/chats/members/add) | im.chat.user.add | Добавить участников |
| DELETE | [/v1/chats/:chatId/users](/docs/chats/members/remove) | im.chat.user.delete | Удалить участника |
| POST | [/v1/chats/:chatId/files](/docs/chats/files/upload) | im.disk.folder.get + disk.folder.uploadfile + im.disk.file.commit | Загрузить файл в чат |
| GET | [/v1/chats/files/:fileId](/docs/chats/files/file-get) | disk.file.get | Метаданные файла |
| GET | [/v1/chats/:chatId/folder](/docs/chats/files/folder) | im.disk.folder.get | Папка чата на Диске |
| POST | [/v1/chats/events/subscribe](/docs/chats/events/subscribe) | im.v2.Event.subscribe | Подписаться на события |
| POST | [/v1/chats/events/unsubscribe](/docs/chats/events/unsubscribe) | im.v2.Event.unsubscribe | Отписаться от событий |
| GET | [/v1/chats/events](/docs/chats/events/poll) | im.v2.Event.get | Получить события |

## Коды ошибок

Коды, специфичные для работы с чатами:

| Код | HTTP | Описание |
|-----|------|---------|
| `SCOPE_DENIED` | 403 | API-ключ не имеет скоупа `im` |
| `TOKEN_MISSING` | 401 | У API-ключа не настроены токены Битрикс24 |
| `MISSING_PARAMS` | 400 | Не переданы обязательные параметры (`entityType`/`entityId` при поиске, `filename`/`content` при загрузке файла) |
| `INVALID_REQUEST` | 400 | Некорректное тело запроса (например, пустой массив `dialogs` в массовой загрузке) |
| `BATCH_LIMIT_EXCEEDED` | 400 | Превышен лимит 50 диалогов в массовой загрузке |
| `INVALID_CHAT_ID` | 400 | `chatId` не является положительным целым числом |
| `TITLE_EMPTY` | 400 | Пустое название при переименовании чата |
| `INVALID_OFFSET` | 400 | Некорректный `offset` при опросе событий |
| `INVALID_LIMIT` | 400 | `limit` вне допустимого диапазона |
| `CHAT_NOT_FOUND_OR_NO_ACCESS` | 404 | Чат не существует или нет прав на операцию |
| `DIALOG_NOT_FOUND_OR_NO_ACCESS` | 404 | Диалог не существует или нет доступа |
| `ENTITY_NOT_FOUND` | 404 | Запрошенный объект не найден |
| `FILE_NOT_FOUND` | 404 | Файл с указанным `fileId` не найден |
| `FOLDER_NOT_FOUND` | 404 | Папка чата на Диске не найдена |
| `UPLOAD_FAILED` | 500 | Не удалось загрузить файл на Диск |
| `ME_ALIAS_RESOLUTION_FAILED` | 502 | Не удалось определить текущего пользователя для алиаса `me` |
| `BITRIX_ERROR` | 422 | Битрикс24 вернул ошибку (текст в поле `message`) |
| `BITRIX_UNAVAILABLE` | 502 | Портал Битрикс24 недоступен или вернул ошибку сервера |

Общие коды авторизации, ключей и лимитов — на странице [Ошибки](/docs/errors).

## Смотрите также

- [Бот-платформа](/docs/bots)
- [Уведомления](/docs/notifications)
- [Ключи и авторизация](/docs/keys-auth)
- [Лимиты и оптимизация](/docs/optimization)
- [Справочник ошибок](/docs/errors)