🤖 assistant ·
# Битрикс 24
## Правила интерпретации
- Если Денис говорит «лид», это значит «сделка».
- В работе не использовать сущность «лид» как отдельную сущность CRM.
- Все запросы про лиды трактовать как запросы про сделки.
## Воронки
- CATEGORY_ID = 0, первая воронка, воронка для офиса.
- CATEGORY_ID = 1, вторая воронка, воронка по банкротству.
- При подсчете договоров смотреть сделки в воронках: первая, вторая, 3. реализация, 4. реструктуризация. Альтернативное правило проверки: учитывать все сделки, где заполнено поле «Дата передачи юристу».
- Это правило подсчета договоров касается только флагманской услуги: «Банкротство физических лиц».
- По умолчанию в обычных вопросах про лиды и новые сделки имеются в виду только первая и вторая воронки.
- Новые сделки за прошлую неделю в этом контексте считать только по первой и второй воронкам.
- Остальные воронки по умолчанию не учитывать, кроме отдельного правила подсчета договоров.
- Сделки, перешедшие из одной воронки в другую, не считать новыми.
## Правило работы
- При каждом запросе, связанном с Битрикс24, сначала сверяться с этим файлом.
- Если формулировка пользователя конфликтует с техническими сущностями Битрикс24, применять правила из этого файла.
- Периодически сверять рабочий список сотрудников с активными пользователями Битрикс24.
- Если появляется новый активный пользователь Битрикс24 или кто-то из известных сотрудников перестает проявлять активность, запрашивать у Дениса актуальность списка действующих сотрудников.
- Если Денис спрашивает, сколько новых лидов за сегодня в первой воронке и на каких они этапах, отвечать в бизнес-формулировке, а не просто техническим списком стадий.
- В таком ответе разделять сделки на три группы: подтвержденные новые лиды, необработанные новые заявки, и все остальные, которые ушли в недозвон или закрыты как не лид.
- Подтвержденными новыми лидами считать только сделки за сегодня в первой воронке, которые находятся на рабочих этапах вроде «Встреча назначена», «Дожать на договор» и других аналогичных этапах активной обработки, но не находятся в «Новая заявка», «Не удалось дозвониться» или «Не лид».
- Сделки на этапе «Новая заявка» считать необработанными и отдельно указывать, сколько таких заявок и во сколько создана самая поздняя из них, если это важно для ответа.
- Сделки на этапах «Не удалось дозвониться» и «Не лид» не называть подтвержденными новыми лидами; их описывать как недозвон или закрытые / отсеянные.
- Если уместно, формулировать ответ по образцу: «подтвержденных новых лидов X, ...; остальные закрыты как не лид или на недозвоне; не обработана Y заявка, создана в HH:MM».
- Количество заключенных договоров не определять по статусу «Сделка успешна». Для Дениса количество заключенных договоров считается по сделкам, где одновременно заполнено поле «Дата передачи юристу» и в поле «Платеж 1: статус оплаты» стоит значение «да», при этом дата в поле «Платеж 1: дата» должна попадать в запрошенный период.
- Рабочее соответствие полей: `UF_CRM_AMO_629053` = «Платеж 1: дата», `UF_CRM_AMO_629067` = «Платеж 1: статус оплаты», `UF_CRM_AMO_640693` = «Дата передачи юристу».
- Важное бизнес-правило: все сделки во второй воронке считать договорными.
- При поиске договоров ориентироваться не только на вторую воронку, а на первую, вторую, воронку «Реализация», воронку «Реструктуризация» или вообще на все сделки с заполненным полем «Дата передачи юристу».
- Если при такой проверке даты в полях логически не совпадают или вызывают сомнение, отдельно сообщать об этом Денису.
- Если Денис спрашивает по конкретной сделке или спрашивает «что там со сделкой», сначала прочитать комментарии в сделке Bitrix24.
- При изучении конкретной сделки обязательно смотреть: комментарий в карточке, таймлайн-комментарии, **транскрипты звонков (входящих и исходящих)**, речевой анализ, если есть, сообщения из Wazzup/MAX/Telegram, задачи и ближайшие активности, если нужны для статуса, а также чат сделки, где идет обсуждение между сотрудниками компании.
- Если для этой сделки есть речевой анализ или строка в связанной таблице, найти соответствующую строку по сделке и прочитать её целиком.
- Для первой линии продаж, Виктория Боева, использовать таблицу речевого анализа: `https://docs.google.com/spreadsheets/d/1WgkgMtcd5vVPTHqL8APgzakOKxWiYaTRuWRnq_oJzC4/edit?gid=1945766933#gid=1945766933`.
### Транскрипты звонков — обязательный источник (с 2026-05-01)
С мая 2026 у нас работает фоновый транскрибатор B24 (AssemblyAI Universal-3 Pro + диаризация). Каждые 5 минут он подбирает новые звонки (входящие и исходящие) и постит расшифровку как **timeline-комментарий** одновременно в карточку контакта и в активные сделки этого контакта.
**Как опознать транскрипт в `crm.timeline.comment.list`:**
- Маркер в начале комментария: `[b]Транскрипт входящего звонка[/b]` или `[b]Транскрипт исходящего звонка[/b]`.
- Шапка: `Дата: ... | длит.: X сек | номер: +7...` + `Оператор: ...`.
- Далее построчная диаризация: `Спикер 1:` / `Спикер 2:` (кто оператор, кто клиент — определяется по контексту шапки).
**Что от меня требуется:**
1. На любую задачу «что там со сделкой / клиентом», «оцени ситуацию», «подготовь сводку», «брать ли в работу» — **обязательно** прогнать `crm.timeline.comment.list` и явно отфильтровать комментарии-транскрипты. Если их нет — сказать прямо «расшифровок звонков в ленте нет».
2. В управленческом выводе для Дениса включать факты ИЗ транскриптов наравне с перепиской: что обещали по телефону, какие возражения, на каком шаге зависли, был ли результативный контакт.
3. При подготовке пакета фактов для Джейми (банкротство) — выдёргивать из транскриптов то, что повлияет на дело: согласие/несогласие должника, упоминание имущества, кредиторов, представителя по доверенности.
4. Не путать транскрипт с речевым анализом из таблицы Виктории — это разные источники, оба надо учитывать (транскрипт = факт диалога, речевой анализ = оценка качества разговора).
5. Если в шапке транскрипта оператор не определился (`PORTAL_USER_ID=...`) — это нормально, разговор всё равно валидный.
**Чего делать НЕ надо:**
- Не выдумывать содержимое звонка, если транскрипта нет в ленте — звонок-активность без транскрипта = «расшифровки нет», а не «разговор был о Х».
- Не игнорировать длинные транскрипты (звонки бывают по 15-30 минут) — пробегаться целиком, выделять решения и обещания.
- После этого отвечать не сырыми полями CRM, а коротким управленческим выводом: кто клиент, кто ответственный, в чем суть ситуации, какой главный риск или следующий шаг, и какова вероятность заключения договора.
- Такие ответы делать лаконично: 3-6 коротких строк, без длинных пересказов, если Денис не просит подробный разбор.
- Если в доступных данных нет комментариев, задач, истории касаний или речевого анализа, прямо говорить, что по голым полям CRM можно видеть только текущий этап и базовые атрибуты, а вероятность заключения договора тогда оценивать осторожно.
## 🔴 Роли в карточке сделки B24 (важно — не путать)
Когда читаю `crm.deal.get` → достаю связанные сущности. Каждая роль — своё назначение:
- **Контакт-физлицо в сделке** = **должник** (клиент банкротства). Это тот, на чьё имя готовится заявление. Полное ФИО + паспорт берём из его карточки контакта (`crm.contact.get`).
- **Компания в сделке** = **рефер-партнёр** (юр.лицо, привлёкшее клиента к нам). Это **НЕ представитель** должника и **НЕ кредитор**. Для пакета документов в суд эта компания **не нужна**, не упоминаем её.
- **Представитель** должника по доверенности — **только если** в карточке должника явно заполнено поле типа `UF_CRM_*PREDSTAVITEL*` или `UF_CRM_*POVERENNYJ*` с реквизитами доверенности (номер, дата, нотариус). Если поле пустое — представителя нет, заявление подаётся **от имени должника лично**.
- **Кредиторы** — отдельные UF_CRM_* поля сделки или отдельные сущности; **не путать с компанией-рефером** в основной связке.
Когда передаю Джону факты по сделке — **явно различаю**: «должник: Иванов И.И., паспорт ... ; рефер-партнёр (для информации, не в пакет): ООО „Партнёр"; кредиторов: 3 шт. (список); представитель: нет». Без этого разделения Джейми спутает реферера с представителем и попросит несуществующую доверенность (это уже один раз случилось 2026-04-25 по сделке 98843 — Иванова Татьяна Ивановна была реферером, а не представителем).
## 🔴 HARD RULE: Документы клиентов на Я.Диске (skill yandex-disk)
**Любая задача, в которой упомянута сделка банкротства физлица (ID, ссылка на B24, ФИО должника, слова «комплект документов», «в суд», «банкротство», «БФЛ») — ОБЯЗАТЕЛЬНО включает шаг по yandex-disk. Без него ответ Джону = брак.**
Проигнорируешь — Джейми получит пустой набор фактов и выкатит «черновик с дырами», что было 2026-04-25 в первом прогоне по сделке 98843. Не повторяй.
При работе со сделкой банкротства физлица — у клиента **всегда** есть папка на Я.Диске Дениса с **сканами**: паспорт, СНИЛС, ИНН, справки о доходах, выписки по счетам, ЕГРН, доверенность представителя, договоры с кредиторами.
**Где лежат:** в корне диска Дениса папка `/Клиенты/` (на 2026-04-25 в ней 1047 элементов, расшаренная как `https://disk.360.yandex.ru/d/4M2DrALRS3tNdA`). Внутри — папки по «Фамилия И.О.» клиента (например `Ревякин А.А.`) — точно как ФИО должника в карточке B24. Скрипт `find` автоматически paginate через все страницы и матчит по фамилии (нечётко).
**ОБЯЗАТЕЛЬНЫЙ пайплайн при задаче «выгрузи факты по сделке X»:**
1. **Карточка сделки** через `bitrix24-rest` → `crm.deal.get` (ID, название, ID контакта, ID компании, ответственный, кредиторы из UF_CRM_*).
2. **Карточка контакта** через `crm.contact.get` (ID контакта из шага 1) → достаю **паспортные данные**: **серию и номер паспорта**, полное ФИО, дату рождения, адрес. Это **ground truth** — клиента ищем по нему, а не по фамилии. Поля паспорта обычно лежат в `UF_CRM_*PASSPORT*` (точные имена меняются — если стандартных полей `PASSPORT_SERIES/NUMBER` нет, дёрни `crm.contact.userfield.list` и найди по `LABEL` со словом «паспорт»).
3. На Я.Диске запускаю Bash-инструментом (НЕ описываю — делаю exec):
```bash
python3 ~/.openclaw/workspace-b24-ops/skills/yandex-disk/scripts/yadisk.py match "<фамилия>" <серия> <номер>
```
Скрипт:
- найдёт все папки в `/Клиенты/` с этой фамилией (родственники + однофамильцы),
- для каждой быстро прогонит download → ocr → extract,
- вернёт **только ту папку, где паспорт совпал с серией+номером из B24-контакта**,
- удалит кэш несовпавших папок (это однофамильцы, мы их данные не должны держать).
4. **Если совпадений 0** — отчитываюсь Джону: «Папки клиента `<ФИО>` (паспорт `<серия> <номер>`) на Я.Диске нет. Кандидаты по фамилии: <список>. Передавай задачу Денису — попроси загрузить документы или уточнить».
5. **Если совпадение есть** — возвращаю Джону **сводный пакет**:
- факты из B24 (карточка)
- извлечённые поля из документов (паспорт серия/номер, СНИЛС, ИНН, адреса) — из `extract.json`
- список путей к OCR-текстам (`/home/openclaw/clients/<slug>/text/*.txt`) — Джейми может сам прочитать через Read для деталей
- список путей к оригинальным сканам (`/home/openclaw/clients/<slug>/raw/*.pdf|jpg`) — Джейми через `lawclaw` может анализировать PDF-договоры
**Если папки клиента нет на Я.Диске** — честно говорю: «Папки `<ФИО>` на Я.Диске не нашёл. Проверь название (формат `Фамилия И.О.`) или попроси Дениса загрузить».
**Если токен не настроен** — скрипт скажет «нет файла yandex-disk.env, Денис должен прислать OAuth-токен». В этом случае возвращаю Джону только B24-факты + помету «документы клиента недоступны: токен Я.Диска не настроен».
## 🔴 HARD RULE: Чаты с клиентами — Wazzup (не API Битрикса)
Если речь про **wazzup/wazzap/вотсап/телеграм/max/сообщения клиента/переписку клиента/что клиент написал** — я иду в приложение Wazzup через браузер, а не жалуюсь что API не даёт.
**Авторизация в Wazzup:** `admin@bvoru.ru` / `y8WD9SnC`
**Пайплайн:**
1. Открываю `https://app.wazzup24.com/login/` в браузере, ввожу логин/пароль.
2. Перехожу в раздел чатов, ищу клиента по имени или номеру телефона.
3. Читаю переписку и возвращаю Денису суть.
Не пытаться вытащить переписку через `im.dialog.get`, `crm.activity.list` или `imopenlines` — эти методы не дают текст чатов Wazzup.
## Генерация документов БФЛ через documentgenerator
Все шаблоны для БФЛ-пакета (заявление, опись имущества, список кредиторов, согласия) уже загружены в B24 и доступны через `crm.documentgenerator.document.add`. Реестр templateId — в `bfl-templates.md` (читать перед генерацией).
**Главное правило:** **выбор ФУ (Климанова / Астапенко / ЕСБ) — всегда человеческий**. Я НИКОГДА не выбираю ФУ сам. Если Джон при делегации не указал ФУ — возвращаю ему: «Нужна ФУ: Климанова / Астапенко / ЕСБ или другая. Уточни у Дениса». Без ФУ генерацию не запускаю.
**Пол должника** — определяю морфологически по ФИО (отчество `-вич`/`-вна` — самый надёжный сигнал; см. `bfl-templates.md`). Если сомнения — возврат Джону «уточни пол должника».
**Бизнес-процессы B24:** заполняют поля сделки (арбитражный суд, реквизиты кредиторов) из библиотек ДО генерации. Обычно стартуют автоматически при изменении стадии. Я их сам не запускаю. Если документ сгенерировался с пустыми кредиторами/судом — значит BP не отработал, возвращаю Джону: «BP заполнения не отработал, поля кредиторов/суда пустые. Денис, проверь стадию сделки».
**Стандартный пакет БФЛ — 3 файла:**
1. Заявление (templateId по таблице ФУ × пол).
2. Опись имущества — templateId=404.
3. Список кредиторов — templateId=402.
Подробности API + таблицы templateId — в `bfl-templates.md`.
## Дайджест звонков (`/digest` → `run.sh`)
Запуск: `bash /home/openclaw/call-digest/run.sh --period {today|yesterday|N}`. Логика выборки данных и резолва имён — внутри скрипта; формат финального ответа Денису — это правило.
**Структура ответа:**
1. **Шапка — общая.** Всего звонков N (входящих X / исходящих Y), с расшифровкой K, без M. Учитываются **все звонки всех сотрудников во всех воронках**, и входящие, и исходящие. Никаких фильтров «только воронка 1» или «только Виктория».
2. **Шапка — по сотрудникам.** Сразу после общей шапки — то же самое в разрезе каждого сотрудника: ФИО + всего N (вх. X / исх. Y), с расшифровкой K, без M. Сотрудники, у которых ноль звонков в период, не упоминаются.
3. **Звонки с расшифровкой.** По каждому строка вида `<ФИО сотрудника> ↔ <ФИО/название клиента> — суть в 1-2 предложениях`. Имена обязательны: никаких `contact#1936`, `deal#12345`, телефонов вместо имени. Связка `<ФИО сотрудника> ↔ <ФИО/название клиента>` оформляется markdown-гиперссылкой на сделку, в которой ведётся работа с этим клиентом (ссылка вида `https://portal.zashita-bankrotstvo.ru/crm/deal/details/<ID>/`). Если у звонка привязка к контакту/лиду без сделки — ссылка ведёт на эту сущность, а в тексте можно кратко указать «(без сделки)».
4. **Тревожные сигналы.** Отказы, негатив, ушёл к конкуренту, обещали и не сделали.
5. **Положительные сигналы.** Оплаты, согласия, договорённости, подвижки по делу.
6. **Что требует решения от Дениса.** 1-3 пункта или «ничего срочного».
**Тон:** сухой, деловой. Не выдумывать — только то, что в расшифровках. Если расшифровок мало — честно сказать.
**Definition of done:** дайджест считается валидным, только если в нём есть оба разреза шапки (общий + по сотрудникам), все имена раскрыты, и в звонках с расшифровкой проставлены гиперссылки на сделки.
## Правила составления документов от имени клиентов (жалобы, письма в БКИ, обращения в ЦБ)
- **Никогда не упоминать «ЮК Защита»** в тексте жалоб, писем в БКИ, обращений в ЦБ и любых других документов, составляемых от имени клиента.
- **Контакт для связи** (email для уведомлений о результатах) — всегда **workspace7717.17@gmail.com**. Не email клиента, не email сотрудника ЮК.
🤖 assistant ·
---
name: bitrix24-rest
description: >
Work with Bitrix24 (Битрикс24) via REST API and MCP documentation server. Triggers on:
CRM — "сделки", "контакты", "лиды", "воронка", "клиенты", "deals", "contacts", "leads", "pipeline";
Tasks — "задачи", "мои задачи", "просроченные", "создай задачу", "tasks", "overdue", "to-do";
Calendar — "расписание", "встречи", "календарь", "schedule", "meetings", "events";
Chat — "чаты", "сообщения", "уведомления", "написать", "notifications", "messages";
Channels — "каналы", "канал", "объявления", "подписчики", "channels", "announcements", "subscribers";
Open Lines — "открытые линии", "поддержка", "обращения", "клиентские чаты", "операторы",
"омниканал", "виджет чата", "open lines", "support", "customer chat", "helpdesk", "operator";
Projects — "проекты", "рабочие группы", "projects", "workgroups";
Time — "рабочее время", "кто на работе", "учёт времени", "timeman", "work status";
Drive — "файлы", "документы", "диск", "files", "documents", "drive";
Structure — "сотрудники", "отделы", "структура", "подчинённые", "departments", "employees", "org structure";
Feed — "лента", "новости", "объявления", "feed", "announcements";
Scenarios — "утренний брифинг", "morning briefing", "еженедельный отчёт", "weekly report",
"статус команды", "что у меня сегодня", "итоги дня", "план на день", "воронка продаж",
"расскажи про клиента", "подготовь к встрече", "как работает отдел".
metadata:
openclaw:
requires:
bins:
- python3
env:
- BITRIX24_WEBHOOK_URL
mcp:
- url: https://mcp-dev.bitrix24.tech/mcp
transport: streamable_http
tools:
- bitrix-search
- bitrix-app-development-doc-details
- bitrix-method-details
- bitrix-article-details
- bitrix-event-details
primaryEnv: BITRIX24_WEBHOOK_URL
emoji: "B24"
homepage: https://github.com/bitrix24/bitrix24-skill
aliases:
- Bitrix24
- bitrix24
- Bitrix
- bitrix
- b24
- Битрикс24
- битрикс24
- Битрикс
- битрикс
tags:
- bitrix24
- bitrix
- b24
- crm
- tasks
- calendar
- drive
- chat
- messenger
- im
- webhook
- oauth
- mcp
- Битрикс24
- CRM
- задачи
- чат
- проекты
- группы
- лента
- рабочее время
- timeman
- socialnetwork
- feed
- projects
- workgroups
- org structure
- smart process
- смарт-процесс
- products
- товары
- каталог
- quotes
- предложения
- invoices
- счета
- open lines
- openlines
- imopenlines
- открытые линии
- поддержка
- обращения
- операторы
- омниканал
- helpdesk
- landing
- sites
- сайты
- лендинги
---
# Bitrix24
## Security Model
- The webhook URL is read from `BITRIX24_WEBHOOK_URL` environment variable. OpenClaw users configure it as `apiKey` in `openclaw.json` — the platform maps it automatically.
- The skill never stores the webhook on disk and never transmits it to third-party services. All API calls go directly to the user's Bitrix24 portal.
- **Implicit invocation:** The skill activates automatically when the user's message matches Bitrix24 topics (CRM, tasks, calendar, etc.). Read requests execute immediately; write/delete operations always require explicit user confirmation.
- Non-secret cache (user_id, timezone) is stored in `~/.config/bitrix24-skill/cache_user_timezone.json` (permissions 600).
- If the webhook is lost (env var removed or reconfigured), the user or admin simply sets it again.
- Users should create a dedicated webhook with only the scopes they need, and can revoke it at any time from their Bitrix24 admin panel.
## STOP — Read These Rules Before Doing Anything
You are talking to a business person (company director), NOT a developer. They do not know what an API is. They do not want to see technical details. Every violation of these rules makes the user angry.
### Rule 1: Read requests — EXECUTE IMMEDIATELY
When the user asks to see, show, list, or check anything — DO IT RIGHT NOW. Do not ask questions. Do not ask for confirmation. Do not offer choices. Call the Bitrix24 methods using the configured webhook and show the result. The user has already authorized access by configuring their webhook URL.
User says "дай расписание на среду" → you IMMEDIATELY:
1. Call `user.current` to get user ID and timezone
2. Call `calendar.event.get` for that date (read `references/calendar.md` for exact syntax)
3. Call `tasks.task.list` with deadline filter for that date (read `references/tasks.md`)
4. Show combined schedule in a clean list
User says "покажи сделки" → you IMMEDIATELY call `crm.deal.list` and show results.
User says "мои задачи" → you IMMEDIATELY call `tasks.task.list` and show results.
### Rule 2: Keep replies non-technical
The user is a business person. Avoid implementation details in replies. Do not expose these in user-facing output:
method names (calendar.event.get, crm.deal.list), script names (bitrix24_call.py), config paths, raw parameters, HTTP details, JSON structures.
It is OK to say "получаю данные из Битрикс24" or "подключаюсь к вашему порталу" — the user knows they connected their Bitrix24. Just don't show HOW technically.
WRONG replies (NEVER do this):
- "Используем ваш webhook URL bitrix24.team/rest/5/..." — FORBIDDEN
- "Вызовем calendar.get или calendar.event.get..." — FORBIDDEN
- "Пришлите экспорт календаря (ICS/CSV)..." — FORBIDDEN
- "Подтвердите часовой пояс..." — FORBIDDEN
- "Подтвердите источник данных..." — FORBIDDEN
- "Как предпочитаете продолжить?" — FORBIDDEN for read requests
CORRECT replies:
- "Вот ваше расписание на среду, 11 марта:" followed by the data
- "Открытые сделки:" followed by the list
- "Ваши задачи на сегодня:" followed by the list
### Rule 3: Write requests — one short yes/no question
For creating, updating, or deleting: confirm in one sentence.
- CORRECT: "Создать сделку «Поставка» на 500 000 ₽?"
- WRONG: "Вызовем crm.deal.add с параметрами..."
### Rule 4: Errors — fix silently or say one sentence
If a call fails, retry automatically. If still fails: "Не удалось подключиться к Битрикс24, проверьте, что портал доступен." Nothing else.
### Rule 5: Language and format
- Reply in the same language the user writes in
- Present data as clean tables or bullet lists
- Use business words: "сделка", "задача", "контакт", "встреча", "расписание"
- For schedule requests: combine calendar events AND task deadlines into one view
- Get timezone from `user.current`, never ask the user
### Rule 6: Proactive insights
When showing data, automatically highlight important things:
- Tasks: count and flag overdue ones ("⚠️ 3 задачи просрочены")
- Deals: flag stuck ones — no activity for 14+ days ("💤 2 сделки без движения")
- Schedule: warn about conflicts — overlapping events
### Rule 7: Suggest next actions
After showing results, add ONE short hint about what else you can do. Keep it to one line.
- After schedule: "Могу перенести встречу или добавить задачу."
- After tasks: "Могу отметить задачу выполненной или создать новую."
- After deals: "Могу показать детали по сделке или создать новую."
- After contacts: "Могу найти сделки этого контакта или добавить задачу."
### Rule 8: First message in session
If this is the user's first request and it's a greeting or unclear what they want, briefly introduce yourself:
"Я помощник по Битрикс24. Могу показать расписание, задачи, сделки, контакты или отчёт по команде. Что интересно?"
## Ready-Made Scenarios
Use these when the user's request matches. Execute ALL calls, then present combined result.
### Morning briefing ("что у меня сегодня?", "утренний брифинг", "дай обзор")
Use batch call for speed:
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'calendar=calendar.event.get.nearest?type=user&ownerId=<ID>&forCurrentUser=Y&days=1' \
--cmd 'tasks=tasks.task.list?filter[RESPONSIBLE_ID]=<ID>&filter[!STATUS]=5&filter[<=DEADLINE]=<today_end>' \
--cmd 'deals=crm.deal.list?filter[ASSIGNED_BY_ID]=<ID>&filter[STAGE_SEMANTIC_ID]=P&select[]=ID&select[]=TITLE&select[]=OPPORTUNITY&select[]=STAGE_ID' \
--json
```
Present as:
- 📅 Встречи сегодня (from calendar)
- ✅ Задачи на сегодня + просроченные (from tasks, flag overdue)
- 💰 Активные сделки (from deals, flag stuck)
### Weekly report ("итоги недели", "еженедельный отчёт")
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'done=tasks.task.list?filter[RESPONSIBLE_ID]=<ID>&filter[STATUS]=5&filter[>=CLOSED_DATE]=<week_start>' \
--cmd 'deals=crm.deal.list?filter[ASSIGNED_BY_ID]=<ID>&filter[>=DATE_MODIFY]=<week_start>&select[]=ID&select[]=TITLE&select[]=STAGE_ID&select[]=OPPORTUNITY' \
--json
```
Present as:
- ✅ Завершённые задачи за неделю (count + list)
- 💰 Движение по сделкам (stage changes)
### Team status ("статус команды", "как дела в отделе")
1. Get department: `department.get` with user's department
2. Get employees: `im.department.employees.get`
3. Batch tasks + timeman for each employee
Present as table: Name | Active tasks | Overdue | Work status
### Client dossier ("расскажи про клиента X", "всё по компании Y", "досье")
1. Find contact/company by name → `crm.contact.list` filter `%LAST_NAME` or `crm.company.list` filter `%TITLE`
2. Batch:
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'deals=crm.deal.list?filter[CONTACT_ID]=<ID>&filter[STAGE_SEMANTIC_ID]=P&select[]=ID&select[]=TITLE&select[]=OPPORTUNITY&select[]=STAGE_ID' \
--cmd 'activities=crm.activity.list?filter[OWNER_TYPE_ID]=3&filter[OWNER_ID]=<ID>&select[]=ID&select[]=SUBJECT&select[]=DEADLINE&order[DEADLINE]=desc' \
--json
```
Present as:
- 👤 Контакт — имя, компания, телефон, email
- 💰 Сделки — список с суммами и стадиями
- 📋 Последние действия — звонки, письма, встречи
- 💡 Подсказка: "Могу создать задачу по этому клиенту или запланировать звонок."
### Meeting prep ("подготовь к встрече", "что за встреча в 14:00")
1. Get today's events → `calendar.event.get` for today
2. Find the matching event by time or name
3. Get attendee info → `user.get` for each attendee ID
4. Check for related deals (search by attendee company name)
Present as:
- 📅 Встреча — название, время, место
- 👥 Участники — имена, должности, компании
- 💰 Связанные сделки (если есть)
- 💡 "Могу показать досье на участника или историю сделки."
### Day results ("итоги дня", "что я сделал", "мой отчёт за день")
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'tasks=tasks.task.list?filter[RESPONSIBLE_ID]=<ID>&filter[STATUS]=5&filter[>=CLOSED_DATE]=<today_start>&select[]=ID&select[]=TITLE' \
--cmd 'events=calendar.event.get?type=user&ownerId=<ID>&from=<today_start>&to=<today_end>' \
--json
```
Also call `crm.stagehistory.list` with `filter[>=CREATED_TIME]=<today_start>` for deal movements.
Present as:
- ✅ Завершённые задачи (count + list)
- 📅 Проведённые встречи
- 💰 Движение по сделкам (стадия изменилась)
- 💡 "Могу составить план на завтра."
### Sales pipeline ("воронка", "как работает отдел продаж", "продажи")
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'active=crm.deal.list?filter[STAGE_SEMANTIC_ID]=P&select[]=ID&select[]=TITLE&select[]=STAGE_ID&select[]=OPPORTUNITY&select[]=DATE_MODIFY&select[]=ASSIGNED_BY_ID' \
--cmd 'leads=crm.lead.list?filter[>=DATE_CREATE]=<week_start>&select[]=ID&select[]=TITLE&select[]=SOURCE_ID&select[]=DATE_CREATE' \
--json
```
Present as:
- 📊 Воронка — сделки по стадиям с суммами
- 💤 Зависшие — без движения 14+ дней
- 🆕 Новые лиды за неделю
- 💡 "Могу показать детали по сделке или назначить задачу менеджеру."
### Deal-card layout ("показывать всегда", "общий вид", "развернуть блок")
For changes to the deal-card layout, empty-field visibility, common sections,
or applying one layout to all employees, read
`playbooks/bitrix-card-layout.md`. Do not use the browser: Bitrix24 provides
`crm.item.details.configuration.*` REST methods for this operation.
Use the dedicated `scripts/casey_card_layout.py` flow. It preserves the full
layout, creates a hash-pinned preview, requires explicit write confirmation,
checks for live drift, applies the common layout, and verifies the result.
Never call the generic read-only wrapper for this write and never disable its
global READONLY guard.
### Cross-domain search ("найди...", "кто отвечает за...", "все по теме...")
When user searches for something, search across multiple entities in parallel:
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'contacts=crm.contact.list?filter[%LAST_NAME]=<query>&select[]=ID&select[]=NAME&select[]=LAST_NAME&select[]=COMPANY_ID' \
--cmd 'companies=crm.company.list?filter[%TITLE]=<query>&select[]=ID&select[]=TITLE' \
--cmd 'deals=crm.deal.list?filter[%TITLE]=<query>&select[]=ID&select[]=TITLE&select[]=STAGE_ID&select[]=OPPORTUNITY' \
--json
```
Present grouped results: Контакты | Компании | Сделки. If only one match — show full details immediately.
---
## Scheduled Tasks (Recommended Automations)
These are pre-built scenarios for scheduled/cron execution. The user can activate them via OpenClaw scheduled tasks.
### Day plan (daily, workdays 08:30)
Build a structured day plan from calendar events and tasks:
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'events=calendar.event.get?type=user&ownerId=<ID>&from=<today_start>&to=<today_end>' \
--cmd 'tasks=tasks.task.list?filter[RESPONSIBLE_ID]=<ID>&filter[<=DEADLINE]=<today_end>&filter[<REAL_STATUS]=5&select[]=ID&select[]=TITLE&select[]=DEADLINE&select[]=STATUS&order[DEADLINE]=asc' \
--json
```
Output format:
```
📋 План на день — <date>
📅 Встречи:
09:00 – Планёрка
14:00 – Звонок с ООО «Рога и копыта»
16:30 – Обзор проекта
✅ Задачи (дедлайн сегодня):
• Подготовить КП для клиента
• Отправить отчёт
⚠️ Просроченные:
• Согласовать договор (дедлайн был 5 марта)
```
### Morning briefing (daily, workdays 09:00)
Day plan (above) PLUS active deals summary and new leads from yesterday:
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'events=calendar.event.get?type=user&ownerId=<ID>&from=<today_start>&to=<today_end>' \
--cmd 'tasks=tasks.task.list?filter[RESPONSIBLE_ID]=<ID>&filter[<=DEADLINE]=<today_end>&filter[<REAL_STATUS]=5&select[]=ID&select[]=TITLE&select[]=DEADLINE&select[]=STATUS' \
--cmd 'deals=crm.deal.list?filter[ASSIGNED_BY_ID]=<ID>&filter[STAGE_SEMANTIC_ID]=P&select[]=ID&select[]=TITLE&select[]=OPPORTUNITY&select[]=STAGE_ID&select[]=DATE_MODIFY' \
--cmd 'leads=crm.lead.list?filter[>=DATE_CREATE]=<yesterday_start>&select[]=ID&select[]=TITLE&select[]=SOURCE_ID' \
--json
```
### Evening summary (daily, workdays 18:00)
Same as "Day results" scenario. Summarize completed tasks, past meetings, deal movements.
### Weekly report (Friday 17:00)
Same as "Weekly report" scenario. Tasks completed + deal pipeline changes for the week.
### Overdue alert (daily, workdays 10:00)
Check for overdue tasks and stuck deals. Send ONLY if there are problems (no spam when all is clean):
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'overdue=tasks.task.list?filter[RESPONSIBLE_ID]=<ID>&filter[<DEADLINE]=<today_start>&filter[<REAL_STATUS]=5&select[]=ID&select[]=TITLE&select[]=DEADLINE' \
--cmd 'stuck=crm.deal.list?filter[ASSIGNED_BY_ID]=<ID>&filter[STAGE_SEMANTIC_ID]=P&filter[<DATE_MODIFY]=<14_days_ago>&select[]=ID&select[]=TITLE&select[]=DATE_MODIFY&select[]=OPPORTUNITY' \
--json
```
If both are empty — do not send anything. If there are results:
```
🚨 Внимание
⚠️ Просроченные задачи (3):
• Задача A (дедлайн 3 марта)
• Задача B (дедлайн 5 марта)
💤 Зависшие сделки (2):
• Сделка X — 500 000 ₽, без движения 21 день
• Сделка Y — 150 000 ₽, без движения 18 дней
```
### New leads monitor (daily, workdays 12:00)
Check for new leads in the last 24 hours. Send only if there are new leads:
```bash
python3 scripts/bitrix24_call.py crm.lead.list \
--param 'filter[>=DATE_CREATE]=<24h_ago>' \
--param 'select[]=ID' \
--param 'select[]=TITLE' \
--param 'select[]=SOURCE_ID' \
--param 'select[]=NAME' \
--param 'select[]=LAST_NAME' \
--json
```
---
## Setup
The webhook URL must be configured as `BITRIX24_WEBHOOK_URL` environment variable before the skill can work. OpenClaw users set it as `apiKey` in `openclaw.json`:
```json
{
"skills": {
"entries": {
"bitrix24-rest": {
"enabled": true,
"apiKey": "https:…et>/"
}
}
}
}
```
If the env var is not set when a user asks for Bitrix24 data, respond once:
"Webhook не настроен. Попросите администратора указать его в настройках."
Do not ask the user to paste a webhook URL. Do not retry.
On the first successful call, the skill caches user_id and timezone in `~/.config/bitrix24-skill/cache_user_timezone.json` for faster subsequent requests.
If calls fail, read `references/troubleshooting.md` and run `scripts/check_webhook.py --json`.
## Making REST Calls
```bash
python3 scripts/bitrix24_call.py <method> --json
```
Examples:
```bash
python3 scripts/bitrix24_call.py user.current --json
python3 scripts/bitrix24_call.py crm.deal.list \
--param 'select[]=ID' \
--param 'select[]=TITLE' \
--param 'select[]=STAGE_ID' \
--json
```
### Parameters from JSON file
For complex parameters (nested objects, arrays, multi-file uploads), use `--params-file` instead of multiple `--param` flags. This avoids shell escaping issues:
```bash
echo '{"filter": {">=DATE_CREATE": "2025-01-01", "%TITLE": "client"}, "select": ["ID", "TITLE"]}' > /tmp/params.json
python3 scripts/bitrix24_call.py crm.deal.list --params-file /tmp/params.json --json
```
### Auto-pagination
For `.list` methods, use `--iterate` to automatically collect all pages:
```bash
python3 scripts/bitrix24_call.py crm.deal.list \
--param 'filter[STAGE_SEMANTIC_ID]=P' \
--param 'select[]=ID' \
--param 'select[]=TITLE' \
--iterate --json
```
Use `--max-items N` to cap the total number of items collected.
### Dry-run mode
Preview what would be called without executing:
```bash
python3 scripts/bitrix24_call.py crm.deal.add \
--param 'fields[TITLE]=Test' \
--dry-run --json
```
### Operation safety
Methods are automatically classified by suffix:
| Type | Suffixes | Required flag |
|------|----------|---------------|
| Read | `.list`, `.get`, `.current`, `.fields` | — |
| Write | `.add`, `.update`, `.set`, `.start`, `.complete`, `.attach`, `.send` | `--confirm-write` |
| Destructive | `.delete`, `.remove`, `.unbind` | `--confirm-destructive` |
The script refuses to execute write/destructive methods without the matching flag. This prevents accidental data changes. When writing scenarios, always include the flag:
```bash
python3 scripts/bitrix24_call.py crm.deal.add \
--param 'fields[TITLE]=New deal' \
--confirm-write --json
```
If calls fail, read `references/troubleshooting.md` and run `scripts/check_webhook.py --json`.
## Batch Calls (Multiple Methods in One Request)
For scenarios that need 2+ methods (schedule, briefing, reports), use batch to reduce HTTP calls:
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'tasks=tasks.task.list?filter[RESPONSIBLE_ID]=5' \
--cmd 'deals=crm.deal.list?filter[ASSIGNED_BY_ID]=5&select[]=ID&select[]=TITLE' \
--json
```
Results are returned under `body.result.result` keyed by command name. The
script also returns top-level `ok` and `summary` with `total`, `successful`, and
`failed`. Treat a batch as successful only when `ok=true` and
`summary.failed=0`; HTTP 200 alone is not success because Bitrix reports
per-command failures inside `body.result.result_error`.
Never count `len(body.result)` as the number of successful commands: that
object is the service envelope (`result`, `result_error`, `result_total`,
`result_next`, `result_time`). For mass writes, use only top-level `summary`,
then re-read the source and destination objects from Bitrix.
### Cross-command references ($result)
In batch, use `$result[name]` to pass the output of one command into another. This allows chaining — e.g., create a company and immediately create a contact linked to it:
```bash
python3 scripts/bitrix24_batch.py \
--cmd 'company=crm.company.add?fields[TITLE]=Acme Corp' \
--cmd 'contact=crm.contact.add?fields[NAME]=John&fields[COMPANY_ID]=$result[company]' \
--cmd 'deal=crm.deal.add?fields[TITLE]=New deal&fields[CONTACT_ID]=$result[contact]&fields[COMPANY_ID]=$result[company]' \
--halt 1 \
--json
```
Use `--halt 1` to stop on first error when commands depend on each other.
**Encoding note:** Batch commands use query string format — Cyrillic and special characters must be URL-encoded. For complex values, prefer `--params-file` with the regular `bitrix24_call.py` instead of batch.
## User ID and Timezone Cache
After the first `user.current` call, user_id and timezone are saved to config. To use cached values without calling `user.current` again:
```python
from bitrix24_config import get_cached_user
user = get_cached_user() # returns {"user_id": 5, "timezone": "Europe/Kaliningrad"} or None
```
If cache is empty, call `user.current` first — it auto-populates the cache.
## Finding the Right Method
When the exact method name is unknown, use MCP docs in this order:
1. `bitrix-search` to find the method, event, or article title.
2. `bitrix-method-details` for REST methods.
3. `bitrix-event-details` for event docs.
4. `bitrix-article-details` for regular documentation articles.
5. `bitrix-app-development-doc-details` for OAuth, install callbacks, BX24 SDK topics.
Do not guess method names from memory when the task is sensitive or the method family is large. Search first.
Then read the domain reference that matches the task:
- `references/crm.md`
- `references/smartprocess.md`
- `references/products.md`
- `references/quotes.md`
- `references/tasks.md`
- `references/chat.md`
- `references/channels.md`
- `references/openlines.md`
- `references/calendar.md`
- `references/drive.md`
- `references/files.md`
- `references/users.md`
- `references/projects.md`
- `references/feed.md`
- `references/timeman.md`
- `references/sites.md`
## Technical Rules
These rules are for the agent internally, not for user-facing output.
- **Do not use `im.message.add`, `im.chat.add`, `im.disk.file.commit`, or other `im.*`/`imbot.*` methods to reply to the user or deliver files to the user.** These methods manage internal Bitrix24 chats, not the current conversation. Use `im.*` methods only when the user explicitly asks to manage **other** chats (read history, search messages, create a group chat for employees, send a message to someone else on their behalf).
- Start with `user.current` to get the webhook user's ID — many methods need `ownerId` or `RESPONSIBLE_ID`.
- Do not invent method names. There is no `calendar.get`, `tasks.list`, etc. Always use exact names from the reference files or MCP search. When unsure, search MCP first.
- Prefer server-side filtering with `filter[...]` and narrow output with `select[]`.
- Filter operators are prefixes on the key: `>=DEADLINE`, `!STATUS`, `>OPPORTUNITY`. Not on the value.
- Use `*.fields` or user-field discovery methods before writing custom fields.
- Expect pagination on list methods via `start` (page size = 50).
- Use ISO 8601 date-time strings for datetime fields, `YYYY-MM-DD` for date-only fields.
- Treat `ACCESS_DENIED`, `insufficient_scope`, `QUERY_LIMIT_EXCEEDED`, and `expired_token` as normal operational cases.
- A browser login failure is not evidence that the REST webhook failed. Test
REST separately before reporting an authorization problem.
- For `imbot.*`, persist and reuse the same `CLIENT_ID`.
- When a call fails, run `scripts/check_webhook.py --json` before asking the user.
- When the portal-specific configuration matters, verify exact field names with `bitrix-method-details`.
## API Module Restrictions
Not all Bitrix24 REST modules work as expected through a webhook. Some methods exist only for external system integration. Before using methods from these modules, understand their limitations:
- **Telephony (`voximplant.*`, `telephony.*`):** Does NOT make real calls. `telephony.externalcall.register` only creates a call record in CRM — for integrating external PBX systems. Tell the user the REST API cannot initiate voice connections.
- **Mail services (`mailservice.*`):** Configures SMTP/IMAP server settings, cannot send or read emails. No REST API exists for actual email operations.
- **SMS providers (`messageservice.*`):** Registers SMS providers, does not send messages directly. Requires a pre-configured external provider.
- **Connectors (`imconnector.*`):** Infrastructure for connecting external messengers to Open Lines. Requires an external server handler. Useless without a configured integration.
- **Widget embedding (`placement.*`, `userfieldtype.*`):** Registers UI widgets and custom field types. Only works in Marketplace application context, not via webhook.
- **Event handlers (`event.*`):** Registers webhook handlers for events. Requires an external HTTP server to receive notifications.
- **Business processes (`bizproc.*`):** `bizproc.workflow.instances` and
`bizproc.workflow.terminate` require scope `bizproc` and an administrator.
A waiting process is not necessarily stuck. Before termination, explain its
business function and get a separate destructive approval. Never suggest a
server-side Chrome/OpenClaw extension fallback when scope is missing. Before
a mass termination, aggregate instances by deal and template and inspect each
template's `AUTO_EXECUTE`: when it is `0`, the process will not restart by
itself after moving the deal, so preserving future tasks requires a separate
migration or an explicitly approved restart from the beginning.
If the user requests something from these modules — do not refuse. Explain what the method actually does and what it does NOT do. Let the user decide.
## Domain References
- `references/access.md` — webhook setup, OAuth, install callbacks.
- `references/troubleshooting.md` — diagnostics and self-repair.
- `references/mcp-workflow.md` — MCP tool selection and query patterns.
- `references/crm.md` — deals, contacts, leads, companies, activities.
- `references/smartprocess.md` — smart processes, funnels, stages, universal crm.item API.
- `references/products.md` — product catalog, product rows on deals/quotes/invoices.
- `references/quotes.md` — quotes (commercial proposals), smart invoices.
- `references/tasks.md` — tasks, checklists, comments, planner.
- `references/chat.md` — im, imbot, notifications, dialog history.
- `references/channels.md` — channels (каналы), announcements, subscribers, broadcast messaging.
- `references/openlines.md` — open lines (открытые линии), omnichannel customer communication, operators, sessions.
- `references/calendar.md` — sections, events, attendees, availability.
- `references/drive.md` — storage, folders, files, external links.
- `references/files.md` — file uploads: base64 inline for CRM, disk+attach for tasks.
- `references/users.md` — users, departments, org-structure, subordinates.
- `references/projects.md` — workgroups, projects, scrum, membership.
- `references/feed.md` — activity stream, feed posts, comments.
- `references/timeman.md` — time tracking, work day, absence reports, task time.
- `references/sites.md` — landing pages, sites, blocks, publishing.
Read only the reference file that matches the current task.
Note: Bitrix24 has no REST API for reading or sending emails. `mailservice.*` only configures SMTP/IMAP services.