TGLiveChat adds a chat widget to your website. Your visitors type a message, you get it in Telegram, you reply from your phone. That's the whole thing.
What is TGLiveChat?
TGLiveChat is a live chat widget that connects your website visitors directly to your Telegram account. You paste one script tag on your site, connect your Telegram, and that's it — visitors chat, you reply from your phone. No extra app, no separate inbox to check. This documentation covers installation, widget configuration, Telegram setup, platform-specific guides, and the WebSocket protocol for custom integrations. It's written for anyone building or managing a website, not just developers. If you've never touched HTML before, the Quick Start section will have you running in under two minutes.
Three steps. Under two minutes if you already have a Telegram account.
Create your account
Sign up at tglivechat.com. You'll get a widget ID instantly.
Connect Telegram
Open the dashboard, click "Connect Telegram", and start the bot. Messages will flow to your personal chat or a group of your choice.
Paste the code
Add one script tag before your closing </body> tag:
<script src="https://cdn.tglivechat.com/w.js" data-id="YOUR_WIDGET_ID"></script>That's it. Open your site, click the chat bubble, send a test message. It should land in Telegram within a second.
The widget loads from our CDN as a single script tag. It creates a shadow DOM container so it won't conflict with your site's styles.
<!-- Add before </body> -->
<script
src="https://cdn.tglivechat.com/w.js"
data-id="YOUR_WIDGET_ID"
></script>The script is async by default and won't block page rendering. No jQuery, no dependencies, no build step.
Configure the widget directly from the script tag. All attributes are optional except data-id.
| Attribute | Type | Description |
|---|---|---|
data-id | string | Your widget ID. Required. |
data-server | string | Custom server URL. Only for self-hosted setups. |
data-color | hex | Accent color. Defaults to #2AABEE (Telegram blue). |
data-privacy | url | Link to your privacy policy. Shown in pre-chat form. |
data-theme | string | Widget theme name. See Themes section. |
data-title | string | Chat header title. Default: "Chat with us" |
data-subtitle | string | Chat header subtitle. Default: "We usually reply within minutes" |
data-autoopen | number | Auto-open after N seconds. 0 = disabled. |
data-container | selector | CSS selector to embed the widget inline instead of floating. |
data-preview | string | Preview message shown on the bubble. |
<script
src="https://cdn.tglivechat.com/w.js"
data-id="abc123"
data-color="#7C3AED"
data-theme="minimal"
data-title="Hey there!"
data-subtitle="We're online"
data-autoopen="5"
data-privacy="https://yoursite.com/privacy"
data-preview="Need help? Chat with us!"
></script>You have two options: receive messages in a personal chat with the bot, or in a Telegram group.
If multiple people need to see and reply to messages, use a Telegram group. Each visitor conversation gets its own forum thread (topic) so nothing gets mixed up.
Why Admin + Manage Topics?
The bot creates a new topic for each visitor so conversations stay organized. It needs Manage Topics to create and close threads. Without it, messages will fail silently.
All config lives in your dashboard. Changes apply instantly, no code updates needed.
Set any hex color. It applies to the chat bubble, send button, and header. You can also set it via the data-color attribute on the script tag.
Ask for a visitor's name and email before they can send a message. Useful if you want to follow up outside of Telegram. You can make fields optional or required.
Set your available hours for each day of the week. Outside those hours, the widget shows an offline message. Visitors can still leave messages, you'll see them next time you open Telegram.
Lock the widget to specific domains. If someone copies your script tag to another site, the widget won't load. Useful to prevent abuse.
Pick a theme from the dashboard or set it with data-theme. All themes support your custom accent color.
default
Clean and neutral. Works with everything.
minimal
Stripped down. Thin borders, no shadows.
modern
Rounded corners, subtle gradients.
glassmorphism
Frosted glass effect with blur backdrop.
gradient
Colorful gradient header based on your accent color.
dark
Full dark mode. Easy on the eyes.
compact
Smaller footprint. Same features, less space.
rounded
Extra round corners and pill-shaped buttons.
corporate
Straight lines, professional feel.
playful
Bouncy animations, friendly vibe.
flat
No shadows, no gradients. Pure flat design.
neo-brutalist
Bold borders, raw aesthetic, high contrast.
The widget works on any site that supports custom HTML. For React and Next.js there's also an official npm package. Each link below is a full step-by-step guide.
HTML / Any Site
Plain HTML, static sites, any custom build
React / Next.js / Vite
npm install @tglivechat/widget — official React component
WordPress
Official plugin or manual script tag
Shopify
Edit theme.liquid in 60 seconds
Webflow
Project Settings > Custom Code
Bubble.io
Settings > SEO / metatags or HTML element
Squarespace
Settings > Advanced > Code Injection
The recommended way is the npm package — it handles StrictMode, cleanup, and remounting automatically:
npm install @tglivechat/widget// components/LiveChat.tsx
'use client'
import { TGLiveChat } from '@tglivechat/widget'
export default function LiveChat() {
return <TGLiveChat widgetId="YOUR_WIDGET_ID" />
}
// app/layout.tsx
import LiveChat from '@/components/LiveChat'
export default function RootLayout({ children }) {
return (
<html><body>
{children}
<LiveChat />
</body></html>
)
}Alternatively, use next/script without the npm package:
import Script from 'next/script'
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Script
src="https://cdn.tglivechat.com/w.js"
data-id="YOUR_WIDGET_ID"
strategy="afterInteractive"
/>
</body>
</html>
)
}See the full React / Next.js install guide for Vite, CRA, props reference, and troubleshooting.
If you're building a custom client or integrating with the chat server directly, here's the protocol reference.
wss://your-server-url/ws| Event | Description |
|---|---|
init | Initialize session with widget ID and optional visitor info |
message:send | Send a chat message |
ping | Keep the connection alive |
| Event | Description |
|---|---|
session:created | Session initialized, returns session ID |
message:received | New message from the operator |
typing:start | Operator started typing |
typing:stop | Operator stopped typing |
session:closed | Chat session ended by operator |
error | Something went wrong (includes error code and message) |
const ws = new WebSocket('wss://your-server/ws')
ws.onopen = () => {
ws.send(JSON.stringify({
event: 'init',
data: { widgetId: 'YOUR_WIDGET_ID' }
}))
}
ws.onmessage = (e) => {
const msg = JSON.parse(e.data)
console.log(msg.event, msg.data)
}
// Send a message
ws.send(JSON.stringify({
event: 'message:send',
data: { text: 'Hello!' }
}))
// Keep alive every 30s
setInterval(() => {
ws.send(JSON.stringify({ event: 'ping' }))
}, 30000)</body> and the data-id is correctcdn.tglivechat.com is allowed in your script-src and connect-src directivesstyle-src, you'll need 'unsafe-inline' or the widget's nonceStill stuck?
Open a chat on tglivechat.com (yes, we use our own product) or email [email protected].
Common questions about TGLiveChat setup, compatibility, and how it works.
TGLiveChat is a live chat widget you embed on your website. When a visitor sends a message, it gets forwarded to your Telegram account in real time via the Telegram Bot API. You reply from Telegram — mobile or desktop — and the visitor sees your reply instantly in the chat window on your site. No separate support app, no inbox to manage.
No coding required. Installation is one script tag you paste into your site's HTML. On WordPress, Shopify, Webflow, and Squarespace there are specific spots to paste it that need zero coding. The whole process takes under two minutes from sign-up to working widget.
Any platform that lets you add custom HTML or JavaScript. That covers plain HTML, WordPress, Shopify, Webflow, Squarespace, Bubble.io, Next.js, React, Vue, Astro, and anything else. If you can paste a script tag somewhere on your page, the widget will load.
The widget opens a WebSocket connection to the TGLiveChat server. When a visitor sends a message, the server pushes it to your Telegram via the Telegram Bot API. You can receive messages in a personal chat with the bot, or in a Telegram group where each visitor gets their own topic thread so nothing gets mixed up.
Yes. Everything lives in the dashboard — accent color, header title and subtitle, pre-chat form fields, working hours, and which of the 20 themes to use. You can also pass most settings directly on the script tag with data attributes. Nothing requires touching source code.
Messages are forwarded to Telegram and stored in your dashboard chat history on Pro and Agency plans. On the Free plan, messages go to Telegram but dashboard history is limited. Messages are stored on secure infrastructure and aren't shared with third parties.
Open your widget settings in the dashboard and find the Working Hours section. Set your available hours for each day of the week. Outside those hours, the widget switches to an offline state — either hiding completely or showing a custom offline message. Visitors can still leave messages if you allow it; you'll see them when you're back.