Документация Webchatix

Telegram-first live chat: посетитель пишет в виджет на сайте, команда отвечает из Telegram и веб-панели. Слева — разделы, справа — подробности.

За 5 минут

Откройте бота → /start — создаётся аккаунт на тарифе Free и первый сайт.
Скопируйте HTML-сниппет и вставьте на сайт перед </body>.
/panel — одноразовая ссылка в веб-кабинет (или меню «Веб-панель»).
Пригласите оператора: /invite или меню → «Команда» → ➕.
Подключите Telegram-группу: добавьте бота в группу (или напишите в ней /addgroup) и назначьте её на сайт в «Маршрутах».
Запасной вариант — весь сайт в одну группу: /bindsite site_key в группе.

Тарифы и оплата

Регистрация открытая: /start в боте создаёт аккаунт на тарифе Free. Платные тарифы оплачиваются картой в кабинете, раздел Счета — оплата идёт через Stripe.

Тариф	Сайты	Клиенты / мес.	Операторы	За месяц
`free`	1	30	1	$0
`basic`	20	1000	5	$10 ($8 при оплате за год)
`unlimited`	∞	∞	∞	$20 ($16 при оплате за год)

Цены указаны за месяц. Оплата за год — на 20% дешевле и списывается одним платежом ($96 и $192 в год); в кабинете годовая выбрана по умолчанию.

Premium (с Basic): шаблоны, active invite, visibility rules, заметки, рейтинги.

Клиент — уникальный посетитель, начавший диалог в текущем календарном месяце; счётчик обнуляется 1-го числа.

Как устроена оплата

Кабинет → Счета: текущий тариф, расход лимитов, смена тарифа, список оплат со ссылками на PDF.
Данные карты на наши серверы не попадают — страница оплаты и портал управления принадлежат Stripe.
Смена тарифа в середине периода пересчитывается Stripe пропорционально; отмена оставляет платный тариф до конца оплаченного периода, потом аккаунт возвращается на Free.
На почту из этого же раздела приходят чек, сообщение о неудачном списании и напоминание о продлении за несколько дней.
Platform по-прежнему может поставить любой тариф вручную: /setplan <id|tg> <plan>.

Меню бота

Главное меню после /start / /menu. Кнопки обычно по две в ряд.

Пункт	Что делает
🌐 Сайты	Список сайтов аккаунта: настройки, Online/Offline, сниппет, удаление.
👥 Команда	Операторы / участники аккаунта.
➕ Пригласить	Код и deep-link для нового оператора.
💬 Группы	Telegram-группы, принимающие обращения: подключить, назначить на сайт, отключить.
🔗 Веб-панель	Magic-link входа (одноразовый, ~10 мин).
🗺 Маршруты	Кто принимает диалоги с какого сайта/страницы.
⚙️ Панель	Быстрый доступ: ops / sites / routes.
📝 Шаблоны	Быстрые ответы (Basic+).
💳 Тарифы и оплата	Цены, оплата картой, счета (owner).
👑 Владелец	Передать ownership другому участнику.
🗑 Удалить аккаунт	Каскадное удаление после подтверждения именем.
🛠 Platform	Только ADMIN_IDS: список аккаунтов / setplan.

Карточка сайта

Online / Offline — пауза виджета (чат офлайн).
Настройки — поля брендинга, invite, GDPR и т.д. (по 2 кнопки в ряд).
Оператор — назначить маршрутизацию на человека/группу.
Удалить — с подтверждением названием сайта.

Команды бота

Команда	Кто	Смысл
`/start` [CODE]	все	Онбординг / redeem инвайта.
`/menu`	member	Главное меню аккаунта.
`/help`	все	Справка по командам (по вашей роли).
`/panel`	member	Magic-link веб-панели.
`/newsite` [имя \| origin]	admin+	Создать сайт (+ CORS origins).
`/sites`	admin+	Список сайтов.
`/addgroup`	admin+ в группе	Подключить группу как оператора-группу (chat_id не нужен).
`/bindsite` KEY	admin+ в группе	Привязать группу как fallback-чат.
`/invite`	admin+	Инвайт оператора.
`/op_me` CODE	любой	Принять инвайт.
`/tpl`	member	Список / add / del / отправка reply+/tpl id.
`/note`	member	Заметка к диалогу (Basic+).
`/release`	member	Освободить диалог (+ запрос рейтинга).
`/lang`	все	Язык интерфейса бота: en / pl / de / ru.
`/setrole` id role	owner	owner\|admin\|operator.
`/crm` on\|off	owner	Вкл/выкл CRM-мост аккаунта.
`/deleteaccount`	owner	Удалить аккаунт.
`/setplan`	platform	Сменить тариф аккаунта.
`/platform`	platform	Обзор аккаунтов + ссылка /admin/platform/.
`/id`	в чате	Показать chat_id.

Веб-панель

Вход тенанта: ссылка из /panel или токен на /admin/login/. Владелец платформы: отдельно /admin/platform/ (пароль admin_password).

Раздел	Зачем
Обзор	Счётчики и последние диалоги; название компании; CRM-мост для owner — переключатель и ссылка вебхука (пусто — общая из config).
Сайты	Создание, сниппет, полные настройки виджета.
Операторы	Участники, инвайты, роли, группы.
Маршруты	Assignments: сайт → оператор/группа.
Диалоги	История, release, заметки, рейтинг.
Шаблоны	CRUD шаблонов + сводка рейтингов (Basic+).
Аккаунты	Только platform: тариф, suspend, impersonate, delete.

Настройки сайта

Доступны в боте («Настройки») и в веб Сайты → шестерёнка.

Поле	Значение
Название / заголовок / подзаголовок	Шапка чата.
Приветствие / лого	Первое сообщение и бренд.
Онлайн с–до, TZ, пауза	Статус Online/Offline.
Эскалация (мин)	Алерт, если нет ответа.
Цвет / позиция / отступы	Кнопка виджета.
Язык / звук	en\|pl\|de\|ru и URL mp3.
Allowed origins	CORS: домены через запятую или `*`.
Invite *	Bubble-приглашение (Basic+).
Visibility JSON	Где показывать кнопку/invite (Basic+).
GDPR	Чекбокс согласия до первого send.

Пример visibility

{"include":["/pricing","/contacts"],"exclude":["/admin"],"desktop":true,"mobile":true}

Виджет на сайте

<script async src="https://ВАШ_ДОМЕН/widget/webchatix.js"
  data-site-key="ВАШ_KEY"></script>

Управление со страницы:

webchatix("show");   // показать кнопку
webchatix("hide");   // спрятать
webchatix("open");   // открыть чат
webchatix("close");  // закрыть панель

Язык виджета берётся из data-lang, затем из <html lang> страницы, затем из браузера; поддерживаются en / pl / de / ru, запасной — английский. После смены настроек обновите страницу клиента (версия виджета в query ?v=).

Если на сайте настроена Content-Security-Policy, разрешите домен виджета в трёх директивах: script-src, style-src и connect-src. Оформление виджет подключает отдельным файлом webchatix.css, так что держать ради него 'unsafe-inline' в style-src не нужно.

Операторы и роли

owner — полный контроль, тарифные запросы, удаление аккаунта, CRM, передача ownership.
admin — сайты, инвайты, маршруты, настройки.
operator — ответы в диалогах, заметки/шаблоны по плану.

Один Telegram-пользователь = один owned-аккаунт. В чужих аккаунтах можно быть оператором по инвайту.

Группы

Кроме людей оператором может быть Telegram-группа: обращения падают карточкой в чат, отвечает любой участник — Reply на карточку. Подключение: добавьте бота в группу (кнопка «Группы» → «Подключить группу») или напишите в группе /addgroup; chat_id вводить не нужно, бот берёт его сам. Группы не занимают лимит операторов по тарифу.

Диалоги

Сообщение клиента уходит в Telegram (группа/оператор по маршруту).
Принять — claim; system message в истории.
Передать — только active member того же аккаунта.
Освободить / release — можно запросить рейтинг у посетителя.
Заметки — видны команде, не клиенту (Basic+).
Шаблоны — Reply на диалог + /tpl id или кнопка шаблона → Reply.

Платформа (владелец приложения)

TG IDs из ADMIN_IDS / platform_tg_ids + пароль admin_password.

Веб: /admin/platform/ → аккаунты, setplan, suspend, impersonate, delete.
Бот: /platform, /setplan id|tg plan.

Impersonate логируется в platform_audit (кто/IP/аккаунт).

Безопасность и GDPR

Аккаунты изолированы по account_id.
Magic-link одноразовый; лимит выдачи ссылок.
Suspend гасит виджет, бот и кабинет тенанта.
CORS: задайте allowed_origins (не оставляйте * на проде без нужды).
GDPR-чекбокс — до первого сообщения клиента.
Квота upload по тарифу (max_upload_mb).
Не больше 10 новых сайтов в час на аккаунт.

Бэкап и деплой

Скрипт бэкапа SQLite с ротацией:

chmod +x scripts/backup-sqlite.sh
# cron ежедневно:
15 3 * * * /path/to/chat-widget/scripts/backup-sqlite.sh

Копии: data/backups/chat_*.sqlite.gz (по умолчанию 14 штук).

После обновления rewrite в aaPanel добавьте docs рядом с faq|contact|blog и языковые префиксы pl|de|ru, затем перезапустите бота.