Docs / Chat Widget

Embeddable Chat Widget

Add an AI-powered expert chat to any website with a single script tag.

No backend required on your site — authentication, billing, and session management all happen on SageTube.

Quick Start

Paste this snippet before </body> on any page:

<script
  src="https://sagetube.ai/embed/widget.js"
  data-expert-token="YOUR_EXPERT_TOKEN"
  async
></script>

A floating chat bubble appears in the bottom-right corner. Clicking it opens a chat panel powered by your Expert's knowledge base.

Getting Your Expert Token

Go to your Expert's settings in the SageTube dashboard
Enable Public Sharing to generate a shared link (/s/{token})
Enable Embed Widget in the sharing settings
Copy the embed snippet — it includes your expert token

The expert token is the same token used in your public shared link. It is not a secret — it identifies which Expert to chat with.

Customization

<script
  src="https://sagetube.ai/embed/widget.js"
  data-expert-token="YOUR_EXPERT_TOKEN"
  data-position="bottom-right"
  data-primary-color="#6366f1"
  data-greeting="Ask me anything!"
  async
></script>

Attribute	Required	Default	Description
`data-expert-token`	Yes	—	Your Expert's public sharing token
`data-position`	No	`bottom-right`	`bottom-right` or `bottom-left`
`data-primary-color`	No	`#2b6783`	Bubble and accent color (any CSS color)
`data-greeting`	No	`Ask me anything!`	Initial greeting shown in the chat panel

How It Works

Shadow DOM isolation: The widget renders inside a Shadow DOM so your site's CSS never affects it, and vice versa.
iframe-based chat: The chat UI loads in an iframe from sagetube.ai. No credentials are ever exposed to your page.
Session persistence: Conversations persist across page navigations via localStorage on your domain.
Mobile responsive: On small screens (under 480px), the chat opens full-screen.
Lazy loading: The iframe is only created when the visitor first opens the chat bubble.

Events

The widget dispatches CustomEvents on the widget host element that bubble up to document. You can listen for these to react to chat activity:

document.addEventListener('sagetube:message', (e) => {
  console.log('New message:', e.detail);
});

Event	Payload	Description
`sagetube:ready`	`{ height }`	Chat loaded and ready
`sagetube:message`	`{ role }`	A message was sent or received
`sagetube:resize`	`{ height }`	Chat content height changed
`sagetube:limit`	`{ type }`	Query limit reached (`daily` or `rate`)
`sagetube:error`	`{ code }`	Expert unavailable or balance empty
`sagetube:close`	`{}`	User closed the chat

Billing & Limits

Billing: Widget queries are billed to the Expert owner's wallet at the standard pay-as-you-go rate.
Daily query cap: Each embedded Expert has a configurable daily query cap (default: 500) to prevent runaway costs.
Rate limiting: 30 requests per minute per IP address.
Free queries: Each visitor session gets a limited number of free queries before seeing a signup prompt.

Privacy & GDPR

The widget stores a session identifier in localStorage on your domain (no cookies).
No personal data is collected unless the visitor chooses to type it into the chat.
If your site is subject to EU/UK privacy regulations, you may need to disclose the widget in your cookie/storage consent banner.

Need More Control?

For server-side integrations or full control over the chat UI, use the SageTube API instead.