Дакументацыя Webchatix

Live chat, які працуе перш за ўсё праз Telegram: наведвальнік піша ў віджэт на сайце, а каманда адказвае з 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): шаблоны, актыўнае запрашэнне, правілы бачнасці, нататкі, ацэнкі.

Кліент — унікальны наведвальнік, які пачаў дыялог у бягучым каляндарным месяцы; лічыльнік абнуляецца 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).
👑 Уладальнік	Перадаць правы ўладальніка іншаму ўдзельніку.
🗑 Выдаліць акаўнт	Каскаднае выдаленне пасля пацвярджэння назвай.
🛠 Platform	Толькі ADMIN_IDS: спіс акаўнтаў / setplan.

Картка сайта

Online / Offline — прыпыніць віджэт (чат афлайн).
Налады — палі брэндынгу, запрашэнне, GDPR і г.д. (па дзве кнопкі ў радзе).
Аператар — накіраваць гэты сайт на чалавека або групу.
Выдаліць — з пацвярджэннем назвай сайта.

Каманды бота

Каманда	Хто	Прызначэнне
`/start` [CODE]	усе	Пачатак працы / актывацыя запрашэння.
`/menu`	member	Галоўнае меню акаўнта.
`/help`	усе	Даведка па камандах для вашай ролі.
`/panel`	member	Magic link у вэб-панэль.
`/newsite` [назва \| origin]	admin+	Стварыць сайт (+ CORS origins).
`/addgroup`	admin+ у групе	Падключыць групу як аператара-групу (chat_id не патрэбны).
`/bindsite` KEY	admin+ у групе	Прывязаць групу як рэзервовы чат.
`/invite`	admin+	Запрашэнне для аператара.
`/op_me` CODE	любы	Прыняць запрашэнне.
`/tpl`	member	Спіс / add / del / адпраўка адказам + /tpl id.
`/note`	member	Нататка да дыялогу (ад Basic).
`/release`	member	Вызваліць дыялог (+ запыт ацэнкі).
`/lang`	усе	Мова інтэрфейсу бота: en / pl / de / ru / uk / be / ar.
`/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).
Сайты	Стварэнне, сніпет, поўныя налады віджэта.
Аператары	Удзельнікі, запрашэнні, ролі, групы.
Маршруты	Прызначэнні: сайт → аператар/група.
Дыялогі	Гісторыя, вызваленне, нататкі, ацэнка.
Шаблоны	Стварэнне і рэдагаванне шаблонаў + зводка ацэнак (ад Basic).
Акаўнты	Толькі platform: тарыф, suspend, impersonate, delete.

Налады сайта

Даступныя ў боце («Налады») і ў вэб-панэлі: Сайты → шасцярня.

Поле	Значэнне
Назва / загаловак / падзагаловак	Шапка чата.
Прывітанне / лагатып	Першае паведамленне і брэнд.
Анлайн з–да, TZ, паўза	Статус Online/Offline.
Эскалацыя (хв)	Апавяшчэнне, калі няма адказу.
Колер / пазіцыя / адступы	Кнопка віджэта.
Мова / гук	en\|pl\|de\|ru\|uk\|be\|ar і URL mp3.
Allowed origins	CORS: дамены праз коску або `*`.
Invite *	Запрашэнне-бурбалка (ад Basic).
Visibility JSON	Дзе паказваць кнопку/запрашэнне (ад Basic).
GDPR	Сцяжок згоды перад першай адпраўкай.
ШІ-адказчык	Адказвае наведвальніку, калі ніхто не адказаў N хвілін (па змаўчанні 3).

ШІ-адказчык (Gemini)

Наведвальнік напісаў, а аператар маўчыць — праз зададзеную колькасць хвілін у дыялогу адказвае Google Gemini. Наведвальнік бачыць адказ у віджэце, а аператары атрымліваюць у Telegram картку «Адказаў ШІ» з тым жа тэкстам, каб ніхто не паўтараў сказанае.

Уключаецца для кожнага сайта асобна: Сайты → шасцярня → ШІ-адказчык. Там жа — затрымка і поле «Што ШІ павінен ведаць пра кампанію»: гадзіны працы, дастаўка, чаго нельга абяцаць.
Адказ чалавека скідае адлік; дыялог, які аператар узяў на сябе, ШІ не чапае.
Адказ ШІ не адмяняе эскалацыю: адміністратар усё роўна атрымае апавяшчэнне, што жывы чалавек не адказаў.
Мадэль адказвае коратка, не выдумляе цэн і тэрмінаў, а на прамое пытанне прызнаецца, што яна аўтаматычны асістэнт.
Ключ API задаецца адзін раз для ўсёй усталёўкі: gemini_api_key у config/config.php (яго можна атрымаць у Google AI Studio, там ёсць бясплатны ліміт). Без ключа сцяжок нічога не робіць.

Прыклад 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 / uk / be / ar, запасная — англійская. Пасля змены налад абнавіце старонку кліента (версія віджэта перадаецца ў query ?v=).

Калі на сайце настроена Content-Security-Policy, дазвольце дамен віджэта ў трох дырэктывах: script-src, style-src і connect-src. Стылі віджэт падгружае асобным файлам webchatix.css, таму трымаць дзеля яго 'unsafe-inline' у style-src не трэба.

Аператары і ролі

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

Адзін карыстальнік Telegram = адзін уласны акаўнт. У чужых акаўнтах можна быць аператарам па запрашэнні.

Групы

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

Дыялогі

Паведамленне кліента трапляе ў Telegram (групе/аператару паводле маршруту).
Прыняць — бярэ дыялог на сябе; у гісторыі з’яўляецца сістэмнае паведамленне.
Перадаць — толькі актыўнаму ўдзельніку таго ж акаўнта.
Вызваліць — можна папрасіць наведвальніка ацаніць размову.
Нататкі — бачыць каманда, але не кліент (ад Basic).
Шаблоны — Reply на дыялог + /tpl id або кнопка шаблона → Reply.

Платформа (уладальнік праграмы)

Telegram ID з 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 паказваецца да першага паведамлення кліента.
Квота на загрузку файлаў залежыць ад тарыфу (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|uk|be|ar, а потым перазапусціце бота.