Getting Started

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.

Quick Start

Three steps. Under two minutes if you already have a Telegram account.

Create your account

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:

html

<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.

Installation

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.

html

<!-- Add before </body> -->
<script
  src="https://cdn.tglivechat.com/w.js"
  data-id="YOUR_WIDGET_ID"
></script>

What happens when the script loads

Downloads the widget bundle (~18KB gzipped)
Creates a shadow DOM container at the bottom right of the page
Connects to the chat server via WebSocket
Shows the chat bubble

The script is async by default and won't block page rendering. No jQuery, no dependencies, no build step.

Data Attributes

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.

Example with all attributes

html

<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>

Connecting Telegram

You have two options: receive messages in a personal chat with the bot, or in a Telegram group.

Personal chat (simplest)

Go to the TGLiveChat dashboard
Click "Connect Telegram"
You'll be redirected to Telegram to start the bot
Press "Start" in Telegram
Done. All visitor messages go to this chat.

Group chat (for teams)

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.

Create a Telegram group (or use an existing one)
Enable Topics: Group Settings > Topics > Turn on
Add the TGLiveChat bot to the group
Make the bot an Admin with Manage Topics permission
In the dashboard, select "Group" and pick your group from the list

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.

Widget Configuration

All config lives in your dashboard. Changes apply instantly, no code updates needed.

Accent color

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.

Pre-chat form

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.

Working hours

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.

Domain restriction

Lock the widget to specific domains. If someone copies your script tag to another site, the widget won't load. Useful to prevent abuse.

Themes

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.

Platform Guides

The widget works on any site that supports custom HTML. Here's where to paste the script tag on popular platforms.

WordPress

Option A: Go to Appearance > Theme File Editor > footer.php and paste the script before </body>.

Option B: Install the "Insert Headers and Footers" plugin (by WPCode). Go to Settings > Insert Headers and Footers, paste the script in the "Footer" box, and save.

Webflow

Go to Project Settings > Custom Code > Before </body> tag. Paste the script and publish.

Shopify

Go to Online Store > Themes > Actions > Edit Code. Open theme.liquid and paste the script right before the closing </body> tag.

Next.js

Use the Script component from next/script in your root layout:

tsx

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>
  )
}

Static HTML / Any other site

Paste the script tag before </body> in your HTML. That's all.

WebSocket Protocol

If you're building a custom client or integrating with the chat server directly, here's the protocol reference.

Connection

text

wss://your-server-url/ws

Client to server

Event	Description
`init`	Initialize session with widget ID and optional visitor info
`message:send`	Send a chat message
`ping`	Keep the connection alive

Server to client

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)

Example

javascript

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)

Troubleshooting

Widget not appearing

Check that the script tag is before </body> and the data-id is correct
Open browser DevTools (F12) and check the Console tab for errors
Make sure your domain is allowed if you've set domain restrictions
Try loading the script URL directly in a new tab. If it 404s, your widget ID might be wrong

Messages not reaching Telegram

Make sure the bot is still connected in your dashboard. Look for the green "Connected" badge
If using a group, check that the bot is still a member and has Admin + Manage Topics permissions
Check if you haven't blocked the bot in Telegram
Try disconnecting and reconnecting from the dashboard

Widget looks wrong

The widget uses Shadow DOM, so your site's CSS shouldn't affect it. If it still looks off, check if your site has a very aggressive CSS reset
If you're using a Content Security Policy (CSP), make sure cdn.tglivechat.com is allowed in your script-src and connect-src directives
For style-src, you'll need 'unsafe-inline' or the widget's nonce

Still stuck?

Open a chat on tglivechat.com (yes, we use our own product) or email support@tglivechat.com.