<div align="center">

<img src="assets/bitrix24-hero.webp" alt="Задачи ближе: Bitrix24 в переписке с Ивой" width="100%">

# Bitrix24 в переписке с Ивой

**Узнавайте, что происходит с задачами, находите документы и поручайте изменения прямо в Telegram.**

[![Версия](https://img.shields.io/github/v/release/mamysh/iva-bitrix24?label=версия&color=91C9AD)](https://github.com/mamysh/iva-bitrix24/releases)
[![Проверки](https://github.com/mamysh/iva-bitrix24/actions/workflows/ci.yml/badge.svg)](https://github.com/mamysh/iva-bitrix24/actions/workflows/ci.yml)
[![MIT](https://img.shields.io/badge/лицензия-MIT-91C9AD)](LICENSE)

[Что попросить](#что-попросить-у-ивы) · [Изменить задачу](#как-меняются-задачи) · [Настройки](#меню-настроек-битрикс) · [Установить](#установить) · [Обновить](#обновить-плагин) · [Помощь](#если-нужна-помощь)

</div>

Плагин подключает задачи вашего Bitrix24 к [Иве](https://github.com/smixs/iva-agent).
Спросите о просроченных задачах, попросите разобраться в обсуждении или найти приложенный
документ. Чтобы создать задачу или изменить существующую, Ива подготовит превью и предложит
подтвердить действие кнопкой.

**Стабильная версия — [0.9.0](https://github.com/mamysh/iva-bitrix24/releases/tag/v0.9.0).**
Настройки Bitrix24 подключены к общему API Panels: в `/panels` можно выбрать
режим действий и поля сотрудников, увидеть превью и подтвердить или отменить
изменение. Без Panels доступно собственное меню Bitrix24.
[Подключение и ограничения API](docs/PANELS.md).

Создание и закрытие задачи ранее проверены владельцем в боевой работе.
Общий API настроек покрыт автоматическими проверками; новое ручное подтверждение
через Panels на рабочем сервере пока не проверено.
[Подробности проверки и совместимости](docs/COMPATIBILITY.md).

Версия включает правку карточки, наблюдателей и чек-листа, стадии канбана и удаление
выбранного файла или сообщения из чата задачи. Запрос из нескольких пунктов получает
одно полное превью и одно подтверждение. Пачка выполняется по порядку: при сбое уже
выполненные изменения сохраняются, оставшиеся пункты останавливаются.

**Подтверждение оформляется через rich replies Ивы:** пустая строка разделяет логические
блоки, внутри блока строки идут подряд, две кнопки относятся ко всему пакету.
Рядом с ответственным показываются должность, подразделение и рабочая почта,
если данные доступны; срок читается как `06.10.2026, 14:35 (UTC+03:00)`.
Пункты чек-листа показаны своим текстом, а новый список получает название «Чек-лист»
или указанное вами имя. Переход с закреплённого RC описан в [SETUP](docs/SETUP.md#переход-с-rc-на-stable).

Списки и отчёты Ива оформляет таблицами с короткими ссылками на задачи; дополнительные
подробности можно раскрыть в сообщении. Для этого используется встроенный rich replies.
Rich-подтверждение работает в личном Telegram-чате Ивы через Telegram-poll.
Для других каналов, webhook-only и недоступного rich остаётся нативное текстовое подтверждение.
Старые кнопки могут оставаться видимыми, но не разрешают повтор или изменённое действие.
Подтверждение ещё не означает успешную запись: Ива проверяет результат в Битрикс24.

## Что попросить у Ивы

| Напишите в чате | Что сделает Ива |
| --- | --- |
| «Перенеси задачу №101 в колонку “Проверка”» | Покажет выбранную стадию проекта и запросит подтверждение перемещения. |
| «Удали загруженный мной файл из чата задачи №101» | Покажет файл и запросит подтверждение удаления. |
| «Покажи мои просроченные задачи» | Найдёт доступные задачи с истёкшим сроком. |
| «Почему у этой задачи поменялся срок?» | Посмотрит историю и обсуждение, объяснит найденные причины. |
| «Найди презентацию в задачах моего отдела» | Найдёт документы по имени и контексту, предложит выбрать нужный. |
| «Разбери документ из этой задачи» | Скачает выбранный файл для разбора; возможности зависят от формата и программ на сервере. |
| «Создай задачу: проверить макет. Описание: сверить текст и цены. Ответственный — Иван Тестов. Срок — 6 октября 2026, 18:00, Минск» | Найдёт сотрудника и покажет полное превью перед созданием. |
| «В этой задаче измени описание, добавь наблюдателя Ивана Тестова и три пункта чек-листа, напиши в чат “тест” и приложи выбранный файл» | Соберёт все изменения в одно превью и выполнит после одного подтверждения. |
| «Добавь комментарий: макет проверен» | Подготовит сообщение в обсуждение выбранной задачи. |
| «Перенеси срок этой задачи на 8 октября 2026, 18:00, Минск» | Покажет новый срок и предложит подтвердить изменение. |
| «Закрой эту задачу» | Подготовит завершение или принятие результата, если задача ожидает контроля. |

Если задача или сотрудник определены неоднозначно, Ива уточнит, кого вы имеете в виду.
Она видит только то, к чему есть доступ у подключённого пользователя Bitrix24.

## Меню настроек Битрикс

В **0.9.0** доступны собственное меню настроек и подключение к Panels.
На экспериментальной Иве с API плагинных экранов команда `/bitrix` открывает
меню без модели. На штатной Иве используйте запрос ниже либо `/panels` при
установленном iva-panels 0.2.0 с включённым общим API.
[Устройство собственного меню](docs/PLUGIN_SCREENS.md).

> Покажи настройки Битрикс

Ива покажет карточку подключения и кнопки **Подключение**, **Возможности**,
**Действия**, **Персональные данные**. Здесь можно проверить webhook без чтения задач,
посмотреть права и выбрать:

- **Только чтение** или **Запись с подтверждением**. Загрузка файлов в Bitrix и удаление
  выбранных сообщений/файлов разрешаются отдельно; подтверждение каждой задачи сохраняется.
- **Только ID**, **ID и имена** или **Рабочий профиль** сотрудников. Email включается отдельно.

Выбор сначала показывает подтверждение. После сохранения настройки переживают перезапуск
и обновление; прежнее превью задачи нужно подготовить заново. Ограничения действуют в коде
плагина до передачи результата Иве, включая превью. В режиме «Только ID» сотрудника выбирают
по номеру, поиск по имени закрыт.

Свежая настройка через установщик 0.7.1-rc.1 начинает с чтения и ID. Обновление прежней установки
сохраняет прежние разрешения, пока вы не выберете свои. Тексты задач, обсуждений, имена файлов
и документы могут содержать персональные данные: режим полей их не обезличивает и не очищает
старые сообщения или память Ивы.

Это собственное меню плагина в личном Telegram-чате. Нажатия обрабатываются Ивой; новый экран
приходит следующим ответом. Подробнее о сохранении, переходе и ограничениях — в
[настройках плагина](docs/SETUP.md#меню-настроек-плагина).

## Как меняются задачи

<img src="assets/bitrix24-confirmation.webp" alt="Попросите Иву, проверьте превью, затем выберите подтверждение или отмену действия" width="100%">

1. **Опишите действие.** Для новой задачи нужны название, описание, ответственный и срок.
   По желанию добавьте проект, наблюдателей, соисполнителей или чек-лист.
2. **Проверьте превью.** Ива покажет, что собирается сделать. Напишите правку, если нужно
   что-то изменить: она подготовит новое превью.
3. **Выберите кнопку.** **Подтвердить** запускает действие, **Отменить** отменяет черновик.
   После выполнения Ива сообщает результат.

Так работают создание, комментарии, загрузка файла в чат задачи, завершение, возврат на
доработку, смена срока и ответственного, перенос по канбану
и удаление из чата задачи; новый исполнитель должен быть активным, а возможность
передачи определяет Битрикс24 по правам пользователя подключения.

*Картинки иллюстрируют сценарий; это не скриншоты интерфейса.*

<details>
<summary><b>Подробности подтверждения и ограничений</b></summary>

Превью действует 30 минут. Новый черновик заменяет предыдущий. Перед записью плагин повторно
проверяет права и состояние задачи. Если результат запроса неизвестен, он не повторяет запись
автоматически; сначала нужно выяснить, что произошло.

Кнопки обрабатывает Ива, а ответ передаётся плагину через модель. Плагин фиксирует содержание
черновика, но не может самостоятельно удостоверить нажатие кнопки. Это ограничение сохраняется
в стабильной версии. [Точный контракт действий](docs/TASK_WRITES.md) · [Защита данных](SECURITY.md).

</details>

## Документы из задач — под рукой

Ива ищет файлы среди вложений задачи, её обсуждения и чек-листа. Показывает список с номерами
и контекстом: выберите один, несколько или все. При обычном разборе задач она сначала
отвечает по задаче, затем предлагает посмотреть файлы. Если вы сразу попросили документ,
лишний вопрос пропускается.

Чтобы получить файл настоящим вложением в Telegram, установите
[плагин доставки файлов](https://github.com/mamysh/iva-file-delivery).
Для просмотра страниц PDF нужен `pdftoppm`, для страниц Word, Excel и презентаций —
LibreOffice. Мастер установки объяснит, чего не хватает. Поиск внутри содержимого документов
Ива запускает по прямой просьбе.

## Установить

Нужны работающая Ива **0.4.0 или новее**, её Linux-сервер и доступ к настройкам входящего
webhook Bitrix24. Webhook — секретный адрес, через который плагин получает разрешённый
доступ к вашему порталу. [Как подготовить подключение](docs/SETUP.md#1-подготовьте-bitrix24).

На сервере под пользователем Ивы выполните:

```bash
curl -fsSL https://raw.githubusercontent.com/mamysh/iva-bitrix24/main/install.sh | bash
```

Русскоязычный мастер установит стабильный плагин, поможет выбрать права, примет webhook
скрытым вводом и проверит подключение. Секретный адрес вводите только в мастере на сервере.

Для чтения нужны права **Задачи**. Для действий с задачами также нужны минимальные права
**Пользователи**, для обсуждения и загрузки файлов — **Чат и уведомления**. Проекты,
подразделения и документы могут требовать дополнительные права:
[таблица и настройка](docs/SETUP.md#1-подготовьте-bitrix24).
Права webhook не расширяют доступ самого сотрудника к задачам.

[Ручная установка и Marketplace](docs/SETUP.md) ·
[Переход с RC на stable](docs/SETUP.md#переход-с-rc-на-stable).

## Первые сообщения после подключения

Начните с проверки:

> Проверь подключение и покажи возможности Bitrix24.

Затем попросите список задач:

> Покажи мои открытые задачи.

Для первой записи используйте вымышленную тестовую задачу и доступного сотрудника:

> Создай тестовую задачу «Проверить подключение». Описание: убедиться, что создание работает.
> Ответственный — я. Срок — 6 октября 2026, 18:00, Минск.

Проверьте превью и нажмите **Подтвердить**. Затем попросите закрыть эту тестовую задачу
и подтвердите действие. Так вы проверите запись именно с правами своего подключения.

## Обновить плагин

Напишите в личном чате с Ивой:

> Проверь обновление плагина Bitrix24.

В 0.7.1-rc.2 карточка в личном Telegram-poll чате разделена на блоки с жирными заголовками.
Команда для VPS, если она нужна, показана отдельным блоком кода для копирования.
Оформление карточки задаёт уже установленная версия: первое обновление со старой
версии может ещё выглядеть как обычный текст.

Ива покажет версии и предложит кнопку **Обновить**. После подтверждения обновление выполнится
в фоне; Ива может ненадолго перезапуститься. При неуспешной диагностике плагин попытается
вернуть предыдущую версию. Затем спросите:

> Как прошло обновление плагина Bitrix24?

Обычная установка и Marketplace следуют каналу `stable`. Если плагин закреплён за тегом RC,
сначала [переведите его на stable](docs/SETUP.md#переход-с-rc-на-stable).

## Что важно знать

- Подключение работает от имени пользователя, создавшего webhook, в пределах его прав.
- Плагин предоставляет перечисленные действия с задачами. CRM, удаление задач и произвольные
  команды Bitrix24 в текущую версию не входят.
- Отправка файла в обсуждение задачи требует современного чата задачи. Один файл — до 50 МиБ.
- При частичной ошибке чек-листа задача уже может быть создана: Ива сообщит результат,
  повторно создавать её не нужно.
- Не отправляйте webhook в Telegram, публичные обращения или журналы.
  [Хранение секрета и доступ к данным](SECURITY.md).

## Если нужна помощь

[Установка и подсказки по ошибкам](docs/SETUP.md) ·
[Сообщить о проблеме](https://github.com/mamysh/iva-bitrix24/issues).

Укажите версии Ивы и плагина, код ошибки и шаги на вымышленном примере.
Webhook, реальные документы и полные ответы вашего портала прикладывать не нужно.

| Подробнее | Где прочитать |
| --- | --- |
| Установка, права, обновление и удаление | [Руководство](docs/SETUP.md) |
| Что проверено и с какими версиями | [Совместимость](docs/COMPATIBILITY.md) |
| Изменения в выпусках | [История версий](CHANGELOG.md) |
| Разрешённые действия и их ограничения | [Контракт действий](docs/TASK_WRITES.md) |

<details>
<summary><b>Для тех, кто хочет улучшить плагин</b></summary>

Плагин работает через изолированный MCP-процесс.
[Инструменты](docs/TOOLS.md) · [Устройство](docs/DESIGN.md) ·
[Правила участия](CONTRIBUTING.md) · [Выпуск версии](docs/RELEASING.md) ·
[Картинки и промпты](docs/VISUALS.md).

```bash
npm ci
npm run check
```

</details>

Независимый плагин для Ивы. Не является официальным продуктом Bitrix24 и не аффилирован с ним.
Лицензия — [MIT](LICENSE).