TKBK Studio
TKBK Studio
Чат-виджет одной строкой: отвечает по вашей базе знаний, а сложные вопросы передаёт человеку в Telegram
Онлайн-консультант, который работает на любом сайте — Tilda, WordPress, самописном. Вставляете одну строку <script>, и в углу появляется чат в вашем фирменном цвете. Ответы печатаются на глазах у посетителя, как в ChatGPT.
Консультант отвечает только по вашей базе знаний: положите в папку knowledge/ файлы с описанием услуг, цен, доставки и FAQ — поиск BM25 найдёт нужные фрагменты, а нейросеть Claude через TKBK API сформулирует ответ. Если ответа нет, бот не выдумывает, а предлагает позвать человека: заявка с перепиской сразу приходит вам в Telegram.
Встроены лимиты на число сообщений с одного IP и в сутки, ограничение длины сообщения и список разрешённых сайтов — ключ не «сгорит» от спама. Всё работает на одном небольшом сервере Node.js, без баз данных.
Для кого: Интернет-магазины, сервисные компании, школы, клиники, лендинги
Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.
TKBK_API_KEYКлюч TKBK API — Получите ключ на https://tkbk.onlineALLOWED_ORIGINSСайты, где разрешён виджет — Через запятую: https://example.ru,https://www.example.ruTELEGRAM_BOT_TOKENТокен бота для заявок — @BotFather → /newbot; нужен для кнопки «Позвать человека»TELEGRAM_CHAT_IDЧат для заявок — Ваш chat_id или id группы (узнать: @userinfobot)# {{BRAND}} — AI-консультант для сайта
Чат-виджет, который отвечает посетителям по вашей базе знаний с помощью нейросети Claude
(через TKBK API). Вставляется на любой сайт одной строкой, а сложные вопросы передаёт
вам в Telegram.
## Что умеет
- Виджет одной строкой — Tilda, WordPress, Bitrix, самописный сайт. Стили изолированы и не ломают ваш сайт.
- Ответ печатается по мере генерации (потоковая передача, SSE).
- Отвечает по файлам из папки `knowledge/` (поиск BM25). Изменили файл — бот знает это через полминуты.
- Не выдумывает: если ответа в базе нет, предлагает «Позвать человека».
- «Позвать человека» — заявка с контактом и перепиской приходит вам в Telegram.
- Защита ключа от спама: лимит сообщений с одного IP в минуту, общий лимит в сутки, длина сообщения,
список сайтов, где разрешён виджет.
## Как устроено
```
knowledge/ база знаний: .md и .txt (услуги, цены, доставка, FAQ)
public/widget.js сам виджет (без зависимостей), widget.css — его стили
public/index.html демо-страница с виджетом
src/config.js название, цвет, приветствие, инструкции для нейросети — меняйте здесь
src/server.js API: /api/widget-config, /api/chat (поток), /api/handoff
src/chat.js промпт, проверка сообщений, дневной лимит (покрыто тестами)
src/tkbk.js клиент TKBK API с потоковой передачей
src/bm25.js поиск по базе знаний (покрыт тестами)
```
## Запуск за 5 минут (Docker)
1. Получите ключ TKBK API на [tkbk.online](https://tkbk.online).
2. Скопируйте `.env.example` в `.env` и вставьте `TKBK_API_KEY`.
3. Замените примеры в `knowledge/` на информацию о вашей компании.
4. Запустите:
```bash
docker compose up -d --build
```
5. Откройте http://localhost:3000 — там демо-страница с работающим виджетом.
## Запуск без Docker
Нужен Node.js 20.16 или новее (рекомендуем 22 LTS).
```bash
npm install
cp .env.example .env # вставьте TKBK_API_KEY
npm start
```
Тесты: `npm test`.
## Как вставить на сайт
Разместите сервер по HTTPS (например, `https://chat.example.ru` через Caddy:
`chat.example.ru { reverse_proxy localhost:3000 }`) и добавьте перед `</body>`:
```html
<script src="https://chat.example.ru/widget.js" defer></script>
```
Необязательные атрибуты переопределяют настройки: `data-color="#e11d48"`, `data-title="Анна"`,
`data-position="left"`. В Tilda — блок T123 «HTML-код», в WordPress — плагин вставки кода в подвал.
Обязательно укажите сайт в `ALLOWED_ORIGINS` в `.env` (через запятую, с `https://`) —
иначе виджет с вашим ключом сможет поставить кто угодно.
## Где взять токены
- **TKBK_API_KEY** — личный кабинет на [tkbk.online](https://tkbk.online). Модель по умолчанию —
`claude-haiku-4-5` (быстрая и недорогая), можно поменять в `TKBK_MODEL`.
- **TELEGRAM_BOT_TOKEN** (для «Позвать человека») — [@BotFather](https://t.me/BotFather) → `/newbot`.
- **TELEGRAM_CHAT_ID** — напишите своему боту любое сообщение, откройте
`https://api.telegram.org/bot<ТОКЕН>/getUpdates` и возьмите `chat.id`. Для группы добавьте бота
в группу и напишите там сообщение. Если эти две переменные не заданы, кнопка просто скрыта.
## База знаний
Файлы `.md` и `.txt` в `knowledge/` (можно в подпапках). Пишите как для нового сотрудника:
факты, цены, сроки, адреса. Заголовки `#`, `##` помогают поиску. Большие файлы делятся
на фрагменты автоматически; в каждый ответ попадают 4 самых подходящих фрагмента.
## FAQ
**Сколько стоит?** Каждый ответ — один запрос к TKBK API: короткие вопросы на Haiku обходятся в копейки.
Дневной потолок задаёт `DAILY_LIMIT`.
**Виджет не появляется.** Откройте консоль браузера: ошибка CORS значит, что сайта нет в `ALLOWED_ORIGINS`;
ошибка mixed content — сервер чата открыт по http, а сайт по https.
**Бот отвечает не по теме или выдумывает.** Добавьте факты в `knowledge/` и уточните правила
в `INSTRUCTIONS` (`src/config.js`).
**Как сменить цвет и тексты?** В `src/config.js` (объект `SETTINGS`) или атрибутами `data-*` у тега `<script>`.
**Где сервер видит реальный IP посетителя?** Если перед сервером стоит Caddy или nginx, поставьте
`TRUST_PROXY=1`, иначе все посетители будут считаться одним IP и упрутся в общий лимит.
Личный бренд: услуги, кейсы, запись на консультацию
Отвечает клиентам по вашим документам через Claude, а сложные вопросы передаёт операторам в Telegram
Форма → КП или договор по шаблону компании: текст пишет нейросеть, цены считает код, экспорт в DOCX и PDF