TKBK Studio
TKBK Studio
Заявка с сайта сразу в чат менеджеров: оценка нейросети, черновик ответа, кнопки «Взял» и «Спам»
Сервис принимает заявки с Tilda или любой формы через вебхук, проверяет секрет, отсеивает явный спам и просит нейросеть через TKBK API оценить заявку и написать черновик первого ответа клиенту.
В чат менеджеров приходит карточка: контакты, источник и UTM, оценка «горячая / тёплая / холодная / спам», резюме и черновик ответа. Кнопка «Взял» закрепляет заявку за менеджером — второй нажавший увидит, что её уже взяли. Все заявки дублируются в Google Таблицу со статусом.
В отличие от стандартных уведомлений Tilda, менеджер сразу видит, кому звонить первым и что сказать, а руководитель — кто и когда взял заявку.
Для кого: Малый бизнес, студии и агентства, которые принимают заявки с сайта
Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.
TELEGRAM_BOT_TOKENТокен Telegram-бота — @BotFather → /newbotMANAGERS_CHAT_IDID чата менеджеров — Добавьте бота в чат, ID вида -100…WEBHOOK_SECRETСекрет вебхука — Длинная случайная строка; в Tilda — API-ключ X-Webhook-SecretTKBK_API_KEYКлюч TKBK API — tkbk.online → API-ключиGOOGLE_SERVICE_ACCOUNT_FILEПуть к JSON-ключу сервисного аккаунта Google — Необязательно, например secrets/google.jsonGOOGLE_SHEET_IDID Google Таблицы — Часть адреса между /d/ и /edit# Заявки с Tilda → AI → Telegram — {{COMPANY_NAME}}
Заявка с сайта на Tilda (или любой формы, которая умеет вебхуки) за пару секунд превращается в карточку в
чате менеджеров: контакты, оценка нейросети «горячая / тёплая / холодная / спам», короткое резюме и
черновик первого ответа клиенту. Кнопки «Взял» и «Спам» фиксируют, кто занялся заявкой, а строка
дублируется в Google Таблицу.
## Что умеет
- Приём заявок из Tilda (form-urlencoded) и любых форм (JSON) с проверкой секрета.
- Ответ Tilda на тестовый запрос `test=test` при подключении вебхука.
- Защита от дублей (повтор Tilda с тем же `tranid` не создаёт вторую карточку).
- Отсев явного спама без затрат на нейросеть: поле-ловушка, ссылки без контактов.
- AI-квалификация через TKBK API (модель `{{AI_MODEL}}`) и черновик ответа в тоне «{{REPLY_TONE}}».
Телефон и почта клиента в нейросеть не передаются.
- Карточка в Telegram с кнопками «Взял» / «Спам»: первая нажатая кнопка побеждает, остальным бот
отвечает, кто уже взял заявку.
- Запись в Google Таблицу через сервисный аккаунт (необязательно) с обновлением статуса и менеджера.
## Запуск за 5 минут
### С Docker
```bash
cp .env.example .env # TELEGRAM_BOT_TOKEN, MANAGERS_CHAT_ID, WEBHOOK_SECRET, 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
```
Tilda отправляет заявки только на публичный HTTPS-адрес: разместите сервис на сервере с доменом или для
проверки пробросьте порт туннелем (`cloudflared tunnel --url http://localhost:8000`).
## Настройка пошагово
### 1. Telegram
1. [@BotFather](https://t.me/BotFather) → `/newbot` → токен в `TELEGRAM_BOT_TOKEN`.
2. Добавьте бота в чат менеджеров. ID чата (вида `-100…`) можно узнать, переслав сообщение из чата боту
@getmyid_bot → `MANAGERS_CHAT_ID`.
3. Бот получает нажатия кнопок долгим опросом (`getUpdates`) — не подключайте этого же бота к другим
сервисам с вебхуком.
### 2. Tilda
1. Придумайте длинный секрет → `WEBHOOK_SECRET`.
2. Tilda → **Настройки сайта → Формы → Webhook**.
3. Адрес: `https://ваш-домен/webhook/lead`.
4. Передайте секрет одним из способов:
- в настройках вебхука добавьте **API-ключ**: имя `X-Webhook-Secret`, значение — ваш секрет;
- или просто допишите его в адрес: `https://ваш-домен/webhook/lead?secret=ВАШ_СЕКРЕТ`.
5. Нажмите «Добавить» — Tilda пришлёт тест, сервис ответит `ok`. Подключите вебхук к нужным формам.
Имена полей формы лучше оставить стандартными (`Name`, `Phone`, `Email`, `Comments`) — остальные поля
тоже попадут в карточку.
### 3. Любая другая форма
POST на `/webhook/lead?secret=...` с JSON `{"name": "...", "phone": "...", "email": "...", "comment": "..."}`
или с обычной формой.
### 4. Ключ TKBK API
tkbk.online → личный кабинет → **API-ключи** → `TKBK_API_KEY`.
### 5. Google Таблица (необязательно)
1. [Google Cloud Console](https://console.cloud.google.com) → создайте проект → **APIs & Services → Library** →
включите **Google Sheets API**.
2. **IAM & Admin → Service Accounts** → создайте сервисный аккаунт → вкладка **Keys → Add key → JSON**.
3. Положите файл в папку `secrets/` рядом с проектом, например `secrets/google.json`, и укажите
`GOOGLE_SERVICE_ACCOUNT_FILE=secrets/google.json`.
4. Откройте таблицу → «Настройки доступа» → добавьте e-mail сервисного аккаунта с правом **Редактор**.
5. ID таблицы — часть адреса между `/d/` и `/edit` → `GOOGLE_SHEET_ID`. Лист — `GOOGLE_SHEET_TAB`
(пусто — первый лист). Заголовки колонок сервис создаст сам.
## Настройки из мастера
`app/config.py` (константы `WIZARD_*`): название и описание компании, тон ответа, модель. Переопределяются в
`.env`: `COMPANY_NAME`, `COMPANY_CONTEXT`, `REPLY_TONE`, `TKBK_MODEL`.
## Тесты
```bash
pip install pytest==9.1.1
pytest
```
Тесты не ходят в сеть: TKBK API и Telegram подменены `httpx.MockTransport`.
## FAQ
**Tilda пишет «ошибка подключения».** Адрес должен открываться снаружи по HTTPS, а секрет — совпадать
(при неверном секрете сервис отвечает 403).
**Карточки не приходят.** Проверьте, что бот добавлен в чат и `MANAGERS_CHAT_ID` верный; смотрите логи
`docker compose logs -f leads`.
**Кнопки не реагируют.** У бота включён вебхук другого сервиса — при старте сервис отключает его, но если
другой сервис включает снова, используйте отдельного бота.
**Нейросеть недоступна или закончился баланс.** Карточка всё равно придёт, просто без оценки.
## Ограничения
- Telegram: сообщение до 4096 символов — длинные комментарии сокращаются в карточке (полностью — в базе и таблице).
- Google Sheets API: около 60 запросов записи в минуту на пользователя — для сотен заявок в минуту
нужна очередь.
- Хранение персональных данных: заявки лежат в `data/leads.db` и в Google Таблице — учитывайте 152-ФЗ.
Услуги, мастера, свободные окна на 14 дней, напоминания за сутки и за 2 часа, предоплата и отзывы
Оценка 0–10 после заказа: довольных — на Яндекс Карты, 2ГИС и WB, недовольных — сразу к менеджеру
Оплата звёздами или картой, одноразовые ссылки, напоминания о продлении и автоисключение по окончании