Integration Guide

Widget Integration Docs

Everything you need to add TalkTG live chat to your website. From basic setup to advanced customization.

Quick Start

Get TalkTG running on your website in under 3 minutes. Just paste a single line of code.

Sign up & create a site

Go to talktg.com/register to create your account, then navigate to Sites and click Add Site. Enter your website domain (e.g. example.com).

Bind a Telegram Bot

Open Telegram and talk to @BotFather to create a new bot. Copy the Bot Token.

Back in TalkTG, go to your site's detail page → click Telegram → paste the token → Bind.

Then send /start to your bot in Telegram to activate the chat channel.

Paste the widget code

Copy the embed code from your site's detail page and paste it into your HTML, just before the closing </body> tag:

<script src="https://talktg.com/widget.js"
  data-site-id="YOUR_SITE_ID" async></script>

Replace YOUR_SITE_ID with the actual Site ID shown on your dashboard.

Prerequisites

1A TalkTG account — sign up free
2A website where you can edit the HTML source
3A Telegram Bot Token from @BotFather

Installation

Basic HTML

Add the script tag before the closing </body> tag in your HTML file:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>My Website</title>
</head>
<body>
  <!-- Your website content -->

  <!-- TalkTG Widget -->
  <script src="https://talktg.com/widget.js"
    data-site-id="YOUR_SITE_ID" async></script>
</body>
</html>

Next.js / React

Use the Next.js Script component in your root layout:

import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://talktg.com/widget.js"
          data-site-id="YOUR_SITE_ID"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

Vue.js / Nuxt

Add to your nuxt.config.ts or in the main template:

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://talktg.com/widget.js',
          'data-site-id': 'YOUR_SITE_ID',
          async: true,
        },
      ],
    },
  },
});

WordPress

Go to Appearance → Theme Editor → footer.php, and paste the code right before </body>:

<script src="https://talktg.com/widget.js"
  data-site-id="YOUR_SITE_ID" async></script>

Alternatively, use a plugin like Insert Headers and Footers to add the code without editing theme files.

Shopify

Go to Online Store → Themes → Edit Code → theme.liquid, and add before the closing </body> tag:

<script src="https://talktg.com/widget.js"
  data-site-id="YOUR_SITE_ID" async></script>

Wix

In Wix, go to Settings → Custom Code → Add Custom Code. Paste the script, set placement to Body - end, and apply to All pages.

Widget Configuration

Customize the widget appearance from your TalkTG dashboard. Go to Sites → Your Site → Widget Settings.

Option	Default	Description
Primary Color	`#6366F1`	Theme color for the widget button, header, and visitor messages.
Position	`bottom-right`	Widget button position. Options: bottom-right, bottom-left.
Greeting	`Hi there! How can we help you?`	Auto-popup greeting text shown to first-time visitors.
Agent Name	`Support`	Display name shown in the chat header.
Offline Message	`We are currently offline. Leave a message!`	Banner text when Telegram bot is not bound or inactive.
Show Branding	`true`	Show "Powered by TalkTG" footer. Pro/Team plans can hide this.
Auto Popup	`false`	Automatically show the greeting bubble to new visitors.
Auto Popup Delay	`5 (seconds)`	Delay before showing the auto-popup greeting.
Sound Enabled	`true`	Play a notification sound when a new agent message arrives.

API Reference

The widget communicates with TalkTG through the following public API endpoints. These are used internally by the widget — you typically don't need to call them directly.

GET/api/widget/config/{siteId}

Fetch widget configuration (colors, greeting, agent name, etc.).

GET/api/sites/{siteId}/status

Check if the Telegram bot is online for this site.

POST/api/chat/send

Send a visitor message. Body: { siteId, visitorKey, content, pageUrl }.

GET/api/chat/history

Load conversation history. Params: siteId, visitorKey, conversationId.

GET/api/chat/poll

Poll for new messages. Params: conversationId, after (last message ID).

How It Works

The widget script loads asynchronously and creates a Shadow DOM container on your page. This ensures zero style conflicts with your existing CSS.

When a visitor sends a message, it's delivered to your Telegram bot via the TalkTG server. The bot forwards it to your linked Telegram chat.

When you reply in Telegram, TalkTG sends the reply back to the visitor via real-time polling (every 3 seconds). The visitor sees the reply instantly.

Visitor identity is persisted in localStorage, so returning visitors continue in the same conversation thread.

FAQ & Troubleshooting

The widget doesn't appear on my site

Make sure the script tag is correctly placed before </body>. Check the browser console for errors. Verify that your Site ID is correct and the site is active in your dashboard.

I'm not receiving messages in Telegram

Ensure you've sent /start to your bot in Telegram after binding. Check that the Telegram status shows "Bound" on your site detail page.

Can I use the widget on multiple domains?

Each site in TalkTG is tied to one domain. Create separate sites for each domain. The Free plan supports 1 site, Pro supports 3, and Team supports 10.

Does the widget slow down my website?

No. The widget script loads asynchronously (async attribute) and uses Shadow DOM for complete isolation. It does not block your page rendering.

How do I customize the widget colors?

Go to Sites → Your Site → Widget Settings in your dashboard. You can change the primary color, position, greeting text, agent name, and more.

Can I remove the "Powered by TalkTG" branding?

Yes! Upgrade to the Pro or Team plan to hide the branding footer.

What happens when I'm offline?

Visitors will see an "offline" banner but can still send messages. You'll receive them in Telegram when you're back online, and replies will be queued for the visitor.

Is the chat data secure?

All traffic is over HTTPS. Bot tokens are encrypted at rest. The widget uses domain validation to prevent unauthorized embedding.

Ready to get started?

Set up takes less than 3 minutes. No credit card required.

Create Free Account Back to Home