TKBK Studio
TKBK Studio
Нейросеть читает сделку, комментарии и звонки, пишет резюме и следующий шаг в таймлайн и в Telegram
Сервис для отдела продаж на Битрикс24: когда сделка меняется (или по расписанию), он собирает её поля, комментарии таймлайна и дела — звонки, письма, встречи — и просит нейросеть через TKBK API кратко пересказать, что происходит, и предложить следующий шаг.
Резюме с рисками появляется комментарием в таймлайне сделки и уходит в Telegram-чат со ссылкой на карточку. Руководитель видит суть сделки за 10 секунд, а менеджер — что делать дальше.
Сервис не спамит: ждёт, пока правки затихнут, пропускает сделки без изменений и закрытые сделки, а телефоны и почты клиентов не отправляет в нейросеть.
Для кого: Отделы продаж и руководители на Битрикс24, интеграторы
Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.
B24_WEBHOOK_URLВходящий вебхук Битрикс24 — Разработчикам → Другое → Входящий вебхук, права CRMB24_APP_TOKENТокен исходящего вебхука — Разработчикам → Другое → Исходящий вебхук → Токен приложенияTKBK_API_KEYКлюч TKBK API — tkbk.online → API-ключиTELEGRAM_BOT_TOKENТокен Telegram-бота — @BotFather → /newbotTELEGRAM_CHAT_IDID чата для резюме — Добавьте бота в чатADMIN_TOKENТокен для ручного запуска — Необязательно# AI-резюме сделок Битрикс24
Сервис читает сделку Битрикс24 вместе с комментариями и делами (звонки, письма, встречи), просит
нейросеть (TKBK API, модель `{{AI_MODEL}}`) сделать короткое резюме и предложить следующий шаг, пишет
результат комментарием в таймлайн сделки и отправляет в Telegram.
## Что умеет
- Режим `{{MODE}}`: `event` — по исходящему вебхуку ONCRMDEALUPDATE/ONCRMDEALADD, `schedule` — раз в
{{SCHEDULE_MINUTES}} мин. по изменённым сделкам, `both` — оба способа.
- Резюме, следующий шаг и риски — в таймлайн сделки (`crm.timeline.comment.add`, с BB-кодами).
- Копия в Telegram со ссылкой на сделку.
- Не спамит: ждёт, пока правки сделки затихнут (`DEBOUNCE_SECONDS`), делает резюме не чаще раза в
{{MIN_INTERVAL_MINUTES}} мин. и только если данные сделки изменились; свои комментарии не учитывает.
- Закрытые сделки (выиграны/проиграны) можно пропускать: `SKIP_CLOSED`, сейчас — `{{SKIP_CLOSED}}`.
- Телефоны и почты контакта в нейросеть не отправляются — только имя.
- Повтор при `QUERY_LIMIT_EXCEEDED` (HTTP 503) и лимитах TKBK API.
## Запуск за 5 минут
### С Docker
```bash
cp .env.example .env # B24_WEBHOOK_URL, B24_APP_TOKEN, TKBK_API_KEY
docker compose up -d --build
curl http://localhost:8000/health
```
### Без Docker (Python 3.12)
```bash
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
python -m app
```
Для режима `event` Битрикс24 должен достучаться до сервиса по HTTPS (сервер с доменом или туннель,
например `cloudflared tunnel --url http://localhost:8000`). Режиму `schedule` внешний адрес не нужен.
## Настройка Битрикс24 пошагово
### 1. Входящий вебхук (чтение сделок и запись комментариев)
1. Битрикс24 → **Разработчикам** (или «Приложения → Разработчикам») → **Другое → Входящий вебхук**.
2. Права доступа: **CRM (crm)**. Сохраните.
3. Скопируйте «Вебхук для вызова rest api» → `B24_WEBHOOK_URL`.
Вебхук работает от имени создавшего его пользователя — у него должен быть доступ к нужным сделкам.
### 2. Исходящий вебхук (события; нужен для режимов event и both)
1. **Разработчикам → Другое → Исходящий вебхук**.
2. URL обработчика: `https://ваш-домен/b24/event`.
3. События: **Обновление сделки (ONCRMDEALUPDATE)**, по желанию **Создание сделки (ONCRMDEALADD)**.
4. Скопируйте «Токен приложения» → `B24_APP_TOKEN`. Сервис отклоняет события с другим токеном.
### 3. Ключ TKBK API
tkbk.online → личный кабинет → **API-ключи** → `TKBK_API_KEY`.
### 4. Telegram (необязательно)
Бот от [@BotFather](https://t.me/BotFather) → `TELEGRAM_BOT_TOKEN`; добавьте бота в чат отдела продаж и
укажите ID чата в `TELEGRAM_CHAT_ID`.
## Ручной запуск
```bash
curl -X POST http://localhost:8000/api/deals/42/summarize -H "Authorization: Bearer <ADMIN_TOKEN>"
```
## Настройки из мастера
`app/config.py` (константы `WIZARD_*`): режим, интервал расписания, минимальный интервал между резюме,
модель, пропуск закрытых сделок. Переопределяются в `.env`: `MODE`, `SCHEDULE_MINUTES`,
`MIN_INTERVAL_MINUTES`, `TKBK_MODEL`, `SKIP_CLOSED`.
## Тесты
```bash
pip install pytest==9.1.1
pytest
```
Тесты не ходят в сеть: Битрикс24, TKBK API и Telegram подменены `httpx.MockTransport`.
## FAQ
**Резюме не появляется после изменения сделки.** Подождите `DEBOUNCE_SECONDS` (по умолчанию 2 минуты) и
проверьте логи: `docker compose logs -f summary`. Если данные сделки не менялись с прошлого резюме, новое не пишется.
**Ошибка `insufficient_scope` или `ACCESS_DENIED`.** У входящего вебхука нет права CRM или у пользователя
нет доступа к сделке.
**Сколько стоит?** Одно резюме — один запрос к модели (≈2–5 тыс. токенов в зависимости от истории сделки).
## Ограничения API
- Битрикс24 REST: около 2 запросов в секунду на портал; при превышении — `QUERY_LIMIT_EXCEEDED`, сервис ждёт
и повторяет.
- Берутся последние 20 комментариев и 20 дел сделки — лимиты в `app/bitrix.py`.
- Исходящие вебхуки Битрикс24 не подписываются — проверяется только `application_token`.
Услуги, мастера, свободные окна на 14 дней, напоминания за сутки и за 2 часа, предоплата и отзывы
Оценка 0–10 после заказа: довольных — на Яндекс Карты, 2ГИС и WB, недовольных — сразу к менеджеру
Оплата звёздами или картой, одноразовые ссылки, напоминания о продлении и автоисключение по окончании