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).
`/sites`	admin+	Site list.
`/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.
`/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 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.

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 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, then restart the bot.