Documentation

Everything you need to add live chat to your site and receive messages in Telegram.

Quick Start

Get from zero to a working chat widget in under 5 minutes.

1. 1
   Create an account

   Sign up at dash.bubblegram.co.

2. 2
   Create a project

   Enter a name and your site's domain (e.g. example.com).

3. 3
   Connect Telegram

   Link a Telegram group so messages are delivered there. See Telegram Setup.

4. 4
   Embed the script tag

   Paste one line of HTML into your site. See Embed the Widget.

5. 5
   Done.

   The chat bubble appears on your site. Visitors send messages; you reply in Telegram. Replies are delivered back to the widget in real time.

Telegram Setup

Bubblegram delivers visitor messages to a Telegram group. Each visitor gets a dedicated topic thread so conversations stay organized.

1. Create a Telegram group

1. Open Telegram and tap the pencil icon (or "New Message").
2. Choose New Group.
3. Add at least one member (you can add yourself from another account, or a teammate).
4. Give the group a name, then create it.

2. Enable Topics (Forum mode)

Topics allow each visitor to get their own thread inside the group. Without this, all messages arrive in one mixed stream.

1. Open the group, tap the group name at the top.
2. Tap Edit (pencil icon).
3. Go to Group Type and enable Topics.
4. Set the topic display to Display as List. This makes it easier to scan and manage multiple visitor conversations.
5. Save.

3. Add the bot

In the dashboard, open your project and click Link Telegram. This generates a unique link that adds the bot to your group and grants it admin rights automatically.

1. Click the Link Telegram button in your project.
2. Tap the link — Telegram opens and prompts you to add the bot.
3. Confirm. The bot joins the group and requests admin permissions.
4. Approve the permission request.

4. Link your group

If you're using the manual flow (bot already in the group), send this command in the group:

/start YOUR_LINK_TOKEN

The bot replies: "Project linked successfully." Your project's status in the dashboard will show Linked.

Embed the Widget

The widget loads from a CDN and is initialized with your project's API key.

Script tag

Add this to your HTML, just before the closing </body> tag:

<script
  src="https://cdn.bubblegram.co/widget.js"
  data-key="pk_live_YOUR_KEY_HERE"
  async
></script>

Your API key is shown in the project's Embed section in the dashboard, visible after your Telegram group is linked.

Attributes

JavaScript API

After the script loads, a Bubblegram object is available on window. You can control the widget programmatically:

Bubblegram.open()     // open the chat panel
Bubblegram.close()    // close the chat panel
Bubblegram.connect()  // reconnect WebSocket (if disconnected)

For React or other SPAs, inject the script dynamically:

useEffect(() => {
  const script = document.createElement('script')
  script.src = 'https://cdn.bubblegram.co/widget.js'
  script.setAttribute('data-key', 'pk_live_YOUR_KEY_HERE')
  script.async = true
  document.body.appendChild(script)
}, [])

Widget Customization

All visual settings are configured in the Project Builder in your dashboard. Changes are reflected in the live preview as you edit and applied to your site when you click Publish changes.

Multiple Sites

Each project in Bubblegram corresponds to one website and one Telegram group. Every project is fully isolated:

• Its own API key for the embed script
• Its own widget configuration (colors, messages, logo)
• Its own Telegram group with separate topic threads
• Its own message history and analytics

To add a second site, create a new project in the dashboard and run through the Telegram setup again for that site's group.

Dashboard Overview

The dashboard at dash.bubblegram.co has four main sections:

Troubleshooting