Self-Hosted Setup Guide

1. Pull the Docker image

docker pull ghcr.io/buzz-line/live-chat-widget

Or use Docker Compose — create a docker-compose.yml:

services:
  buzz-line:
    image: ghcr.io/buzz-line/live-chat-widget
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    env_file:
      - .env

2. Create a Telegram bot

1. Message @BotFather on Telegram and create a new bot
2. Save the bot token
3. Create a Telegram group, add your bot as admin, and enable Topics
4. Get the group ID (add @raw_data_bot to the group temporarily to see it)

3. Configure environment variables

Create a .env file:

TELEGRAM_BOT_TOKEN=<from-botfather>
TELEGRAM_GROUP_ID=<your-group-id>
TELEGRAM_WEBHOOK_URL=https://<your-server-domain>/api/telegram/webhook
TELEGRAM_WEBHOOK_SECRET=<random-string>
ALLOWED_ORIGINS=https://<your-website-domain>
JWT_SECRET=<random-string>

What each variable does:

• TELEGRAM_BOT_TOKEN — from BotFather
• TELEGRAM_GROUP_ID — your support group ID (starts with -100)
• TELEGRAM_WEBHOOK_URL — the public HTTPS URL of your buzz-line server, followed by /api/telegram/webhook. Telegram sends updates here, so it must be reachable from the internet
• TELEGRAM_WEBHOOK_SECRET — a random string used to verify incoming webhook requests are from Telegram
• ALLOWED_ORIGINS — the domain where your chat widget is embedded (e.g. https://myapp.com), not the chat server domain
• JWT_SECRET — a random string. If using authenticated mode, this must match the secret your app uses to sign widget tokens

4. Start the server

docker compose up -d

Verify it's running:

curl https://<your-chat-domain>/health

5. Create host token endpoint (optional)

For authenticated chat (linking messages to your users), your app must expose an endpoint that returns a short-lived JWT for the logged-in user (e.g. /api/widget-token).

The token must be signed with the same secret as JWT_SECRET, and include sub, jti, exp, origin, and site.

Skip this step if you're using anonymous mode — the widget works without authentication out of the box.

6. Embed the widget

<script>
  window.LiveChatConfig = {
    server: 'https://<your-chat-domain>',
    title: 'Support chat',
    subtitle: 'Replies usually within minutes'
  };
</script>
<script
  src="https://<your-chat-domain>/widget/widget.js"
  data-site="<your-app-domain-without-protocol>"
  data-auth-endpoint="/api/widget-token"
></script>

For anonymous mode, omit data-auth-endpoint.

7. Send your first message

1. Open your site and click the chat widget
2. Send a message
3. Confirm it appears in your Telegram group as a new topic
4. Reply in Telegram and confirm the reply syncs back to the widget