Webchatix documentation

Telegram-first live chat: the visitor writes into the website widget, your team answers from Telegram and the web dashboard. Sections on the left, details on the right.

In 5 minutes

Open the bot → /start — an account on the Free plan and the first site are created.
Copy the HTML snippet and paste it into your site before </body>.
/panel — a one-time link into the web dashboard (or the “Web dashboard” menu item).
Invite an operator: /invite or menu → “Team” → ➕.
Connect a Telegram group: add the bot to the group (or run /addgroup there) and assign it to a site under Routes.
Fallback for a whole site in one group: /bindsite site_key inside the group.

Plans and billing

Registration is open: /start in the bot creates an account on the Free plan. Paid plans are bought by card in the dashboard, section Billing — payment goes through Stripe.

Plan	Websites	Clients / month	Operators	Per month
`free`	1	30	1	$0
`basic`	20	1000	5	$10 ($8 paid yearly)
`unlimited`	∞	∞	∞	$20 ($16 paid yearly)

Prices are shown per month. Paying for a year is 20% cheaper and is charged as a single payment ($96 and $192 a year); yearly is preselected in the dashboard.

Premium (Basic and above): templates, active invite, visibility rules, notes, ratings.

A client is a unique visitor who started a chat in the current calendar month — the counter resets on the 1st.

How payment works

Dashboard → Billing: current plan, usage, plan switch, list of invoices with PDF links.
Card details never reach our servers — the payment page and the customer portal belong to Stripe.
Changing the plan mid-period is prorated by Stripe; cancelling keeps the paid plan until the end of the paid period, then the account returns to Free.
The email address in the same section receives the receipt, the failed-payment notice and a renewal reminder several days in advance.
Platform can still set any plan manually: /setplan <id|tg> <plan>.

Bot menu

The main menu after /start / /menu. Buttons usually come two per row.

Item	What it does
🌐 Sites	The account's site list: settings, Online/Offline, snippet, deletion.
👥 Team	Operators / members of the account.
➕ Invite	Code and deep link for a new operator.
💬 Groups	Telegram groups that take requests: connect, assign to a site, disconnect.
🔗 Web dashboard	Magic login link (single use, ~10 min).
🗺 Routes	Who receives dialogs from which site/page.
⚙️ Panel	Quick access: ops / sites / routes.
📝 Templates	Canned replies (Basic and above).
💳 Plans and billing	Prices, card payment, invoices (owner).
👑 Owner	Hand ownership over to another member.
🗑 Delete account	Cascade deletion after confirming by name.
🛠 Platform	ADMIN_IDS only: account list / setplan.

Site card

Online / Offline — pause the widget (chat offline).
Settings — branding fields, invite, GDPR and so on (two buttons per row).
Operator — route this site to a person or a group.
Delete — confirmed by the site name.

Bot commands

Command	Who	Meaning
`/start` [CODE]	everyone	Onboarding / redeem an invite.
`/menu`	member	The account main menu.
`/help`	everyone	Command reference for your role.
`/panel`	member	Magic link to the web dashboard.
`/newsite` [name \| origin]	admin+	Create a site (+ CORS origins).
`/addgroup`	admin+ in a group	Connect the group as a group operator (no chat_id needed).
`/bindsite` KEY	admin+ in a group	Bind the group as the fallback chat.
`/invite`	admin+	Operator invite.
`/op_me` CODE	anyone	Accept an invite.
`/tpl`	member	List / add / del / send with reply + /tpl id.
`/note`	member	Note on a dialog (Basic and above).
`/release`	member	Release a dialog (+ ask for a rating).
`/lang`	everyone	Bot interface language: en / pl / de / ru / uk / be / ar.
`/setrole` id role	owner	owner\|admin\|operator.
`/crm` on\|off	owner	Turn the account CRM bridge on/off.
`/deleteaccount`	owner	Delete the account.
`/setplan`	platform	Change the account plan.
`/platform`	platform	Account overview + link to /admin/platform/.
`/id`	in a chat	Show chat_id.

Web dashboard

Tenant login: the link from /panel or a token on /admin/login/. The platform owner has a separate entrance: /admin/platform/ (password admin_password).

Section	What for
Overview	Counters and recent dialogs; the company name; the CRM bridge for the owner — switch and webhook link (empty falls back to the one in config).
Sites	Creation, snippet, full widget settings.
Operators	Members, invites, roles, groups.
Routes	Assignments: site → operator/group.
Dialogs	History, release, notes, rating.
Templates	Template CRUD + rating summary (Basic and above).
Accounts	Platform only: plan, suspend, impersonate, delete.

Site settings

Available in the bot (“Settings”) and in the web dashboard under Sites → gear icon.

Field	Meaning
Name / title / subtitle	The chat header.
Greeting / logo	The first message and the brand.
Online from–to, TZ, pause	The Online/Offline status.
Escalation (min)	Alert when there is no answer.
Colour / position / offsets	The widget button.
Language / sound	en\|pl\|de\|ru\|uk\|be\|ar and an mp3 URL.
Allowed origins	CORS: comma-separated domains or `*`.
Invite *	Bubble invitation (Basic and above).
Visibility JSON	Where to show the button/invite (Basic and above).
GDPR	Consent checkbox before the first send.
AI responder	Answers the visitor when nobody replied for N minutes (3 by default).

AI responder (Gemini)

The visitor wrote, the operator is silent — after the configured number of minutes Google Gemini answers in the chat. The visitor sees the reply in the widget, and operators get an “AI replied” card in Telegram with the same text, so nobody repeats it.

Enabled per site: Sites → gear → AI responder. The same block holds the delay and the “what the AI should know” field — opening hours, delivery, what must not be promised.
A human reply resets the timer; a conversation an operator has claimed is left alone.
An AI answer does not cancel escalation: the admin is still alerted that no human replied.
The model keeps answers short, never invents prices or dates, and admits to being an automated assistant when asked directly.
The API key is set once per installation: gemini_api_key in config/config.php (take it in Google AI Studio, it has a free tier). Without the key the checkbox does nothing.

Visibility example

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

Website widget

<script async src="https://YOUR_DOMAIN/widget/webchatix.js"
  data-site-key="YOUR_KEY"></script>

Control from the page:

webchatix("show");   // show the button
webchatix("hide");   // hide it
webchatix("open");   // open the chat
webchatix("close");  // close the panel

The widget language follows data-lang, then the page <html lang>, then the browser; en / pl / de / ru / uk / be / ar are supported, with English as the fallback. After changing the settings, reload the client page (the widget version sits in the ?v= query).

If your site sets a Content-Security-Policy, allow the widget domain in three directives: script-src, style-src and connect-src. The widget loads its styling from a separate webchatix.css file, so you do not need to keep 'unsafe-inline' in style-src for it.

Operators and roles

owner — full control, plan requests, account deletion, CRM, ownership transfer.
admin — sites, invites, routes, settings.
operator — answers in dialogs, notes/templates depending on the plan.

One Telegram user = one owned account. In other people's accounts you can be an operator by invitation.

Groups

Besides people, a Telegram group can be an operator: requests arrive as a card in the chat and anyone in the group answers by replying to it. To connect one, add the bot to the group (menu → 💬 Groups → “Connect a group”) or run /addgroup inside it — no chat_id to type, the bot reads it itself. Groups do not count against the plan's operator limit.

Dialogs

The customer message goes to Telegram (group/operator according to the route).
Claim — takes the dialog; a system message lands in the history.
Transfer — only to an active member of the same account.
Release — you can ask the visitor for a rating.
Notes — visible to the team, not to the customer (Basic and above).
Templates — reply to the dialog plus /tpl id, or the template button → Reply.

Platform (application owner)

Telegram IDs from ADMIN_IDS / platform_tg_ids plus the admin_password.

Web: /admin/platform/ → accounts, setplan, suspend, impersonate, delete.
Bot: /platform, /setplan id|tg plan.

Impersonation is logged into platform_audit (who/IP/account).

Security and GDPR

Accounts are isolated by account_id.
The magic link is single use; link issuing is rate limited.
Suspend switches off the widget, the bot and the tenant dashboard.
CORS: set allowed_origins (do not leave * in production without a reason).
The GDPR checkbox comes before the customer's first message.
Upload quota depends on the plan (max_upload_mb).
No more than 10 new sites per hour per account.

Backup and deploy

SQLite backup script with rotation:

chmod +x scripts/backup-sqlite.sh
# daily cron:
15 3 * * * /path/to/chat-widget/scripts/backup-sqlite.sh

Copies: data/backups/chat_*.sqlite.gz (14 by default).

After updating the rewrite rules in aaPanel, add docs next to faq|contact|blog and the language prefixes pl|de|ru|uk|be|ar, then restart the bot.