Browse docs
Getting Started
Channels
Tickets
AI
Workflows
Teams
Reports
Integrations

Support Bubble

Overview

The support bubble lets visitors get help directly from your website. You add a small script to your site and a chat bubble appears in the corner. Depending on the mode you choose, visitors can either chat with an AI assistant or submit a contact form. Messages submitted through the bubble become tickets in your There There inbox, just like email.

Each support bubble is linked to an email channel. When a visitor submits a message (via AI escalation or contact form), a ticket is created on the linked email channel so your team can reply.

Widget modes

There are two modes for the support bubble:

AI Chat

The default mode on paid plans. Visitors chat with an AI assistant that searches your brain (articles and documentation sources) to answer questions. If the AI cannot resolve the issue, it can escalate to a human by creating a ticket.

Contact Form

A simple form where visitors enter their message, email, and optionally their name, subject, and a topic. Submitting the form creates a ticket immediately. Use this mode when you want a straightforward way for visitors to reach your team without AI involvement.

Plan availability

The Contact Form mode is available on every plan, including Free. The AI Chat mode (and the Live Chat mode that is coming soon) require a Standard or Business subscription, because they depend on the AI features. Free workspaces that try to switch to a non-form mode will see an upgrade prompt in the setup UI.

Branding

The bubble shows a small "Powered by There There" line in its footer by default. You can hide this on the Business plan. Free and Standard workspaces keep the branding visible; the toggle is disabled on those plans with a prompt to upgrade.

You can configure the contact form with:

  • Topics: A dropdown list of predefined topics (e.g. "Billing", "Technical issue", "Feature request"). The selected topic is included in the ticket subject.
  • Optional fields: Choose whether to show the Name and Subject fields alongside the required Email and Message fields.

Creating a support bubble

Go to Settings > Channels and create a new channel with the Widget type. You'll configure:

  • Name: An internal label for the channel.
  • Mode: AI Chat or Contact Form.
  • Linked email channel: The email channel where tickets created by this bubble will appear.
  • Position: Bottom right or bottom left.
  • Primary color: The accent color for the bubble, to match your brand.
  • Logo: An optional logo shown in the bubble header and welcome screen.
  • Title: The heading shown in the bubble header (e.g. "Acme Support").
  • Subtitle: Text below the title (e.g. "How can we help?").
  • Welcome message: The heading on the welcome screen (AI Chat mode only).
  • Welcome subtext: Text below the welcome message (AI Chat mode only).
  • Placeholder text: Hint text in the message input (AI Chat mode only).

Embedding the bubble

After creating the channel, copy the embed code from the Install tab. Add this script tag to your website:

<script
    src="https://there-there.app/storage/widget-assets/loaders/your-widget-id.js"
    async
></script>

Place this snippet before the closing </body> tag on every page where you want the bubble to appear. The script is lightweight and loads asynchronously, so it won't slow down your page.

The bubble does not make any requests to There There until the visitor actually opens it. This means the script has zero performance impact on your page load.

JavaScript API

The embed script exposes a global ThereThere object with the following methods:

ThereThere.identify(data)

Pass the logged-in user's identity so the bubble knows who they are. When identified, the contact form hides the email and name fields (since they're already known), and the AI assistant receives the visitor's identity in its context.

ThereThere.identify({
    email: 'john@example.com',
    name: 'John Doe',
    userId: 'usr_12345', // optional, your internal user ID
    signature: 'hmac_hash', // optional, for identity verification
});

Call identify() as early as possible, ideally right after the embed script loads. It accepts both userId and user_id as the key name.

ThereThere.open() / ThereThere.close()

Programmatically open or close the bubble. Useful for triggering the bubble from a custom "Contact us" button.

document.querySelector('#help-btn').addEventListener('click', () => {
    ThereThere.open();
});

ThereThere.show() / ThereThere.hide()

Show or hide the bubble button entirely. The bubble is visible by default.

Domain restrictions

For security, you can restrict which domains are allowed to embed your bubble. Add your allowed domains in the channel settings (e.g. yourcompany.com). Wildcard patterns like *.yourcompany.com are supported. If no domains are specified, the bubble can be embedded on any site.

Identity verification

By default, anyone who visits your site can use the bubble. Enable "Require identification" to restrict it to authenticated users only.

When enabled, your server must verify the visitor's identity with a signature. Here's how:

1. Find your secret key in Settings > Channels > [your widget] > Identity verification. You can rotate this key at any time (all existing signatures become invalid immediately).

2. Generate the signature on your server. The signature is an HMAC-SHA256 hash of the user's lowercased email, using your secret key.

// Laravel / PHP
$signature = hash_hmac('sha256', strtolower($user->email), config('services.there-there.widget_secret'));

# Ruby
signature = OpenSSL::HMAC.hexdigest('sha256', widget_secret, user.email.downcase)

# Python
import hmac, hashlib
signature = hmac.new(widget_secret.encode(), user.email.lower().encode(), hashlib.sha256).hexdigest()

// Node.js
const crypto = require('crypto');
const signature = crypto
    .createHmac('sha256', widgetSecret)
    .update(user.email.toLowerCase())
    .digest('hex');

3. Pass the signature to the widget on the client side. Your backend should render the signature into the page (e.g. as a data attribute or inline variable) so the JavaScript can pick it up:

ThereThere.identify({
    email: user.email,
    name: user.name,
    signature: signatureFromServer,
});

The bubble will send the signature with every API request. If it doesn't match, the visitor sees an error and cannot use the widget.

If you do not need strict verification but still want to pre-fill visitor details, call identify() without a signature. The email and name will be used but not cryptographically verified.

Bot protection

The bubble is protected against automated abuse with a hidden honeypot field and per IP rate limiting on the contact form. This runs silently and requires no configuration on your part.

Dark mode

The bubble automatically detects whether your site uses dark mode and adapts its appearance. It checks both the operating system preference (prefers-color-scheme: dark) and class-based dark mode (a dark class on the <html> element, as used by Tailwind CSS). When the visitor toggles dark mode on your site, the bubble updates in real time.

Consent banner

Enable "Require consent" in the channel settings to show a consent banner before the visitor can start chatting. This is useful for GDPR compliance. The visitor's consent is stored in localStorage and remembered across page loads.

How tickets are created

Both AI Chat escalations and Contact Form submissions create tickets on the linked email channel. The ticket includes:

  • The visitor's message (or AI conversation transcript for escalations)
  • The visitor's email and name (from identification or form input)
  • A link back to the widget session, visible in the ticket sidebar under "Support bubble"

Your team can reply to these tickets the same way they reply to email tickets. The visitor sees replies in real time through the bubble (AI Chat mode) or receives them by email (Contact Form mode).

Usage and billing

Every support bubble conversation counts toward your monthly conversation limit, alongside email tickets. This includes AI Chat conversations (whether resolved by AI or escalated) and Contact Form submissions. Check your current usage in Settings > Billing.