Tluma Widget API

Tluma Widget adds an embeddable Ask AI chat to your website. It opens a hosted Tluma chat panel for a project source, so users can ask questions about your project without leaving your docs or product pages.

Install

Add a config object before loading the widget script:

<script>
  window.tlumaConfig = {
    source: "owner/repo",
    theme: "auto",
    brandColor: "blue",
    button: "bottom-right",
    // optional: welcomePulse: false,
    edgePadding: "1rem",
    // optional: desktopFullscreenByDefault: false,
    // optional: preloadAfterMs: 1000, // set to false to disable background preload 
    // optional: containerId: "ask-ai-demo",
    // optional: prefillStarterPrompt: "How do I deploy this?",
    // optional: autoSendStarterPrompt: "Show me the quickest local setup",
    // optional: iframeAttributes: { "data-my-attr": "x" },
    autoOpen: false
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

What It Does

• Embeds Tluma Ask AI as a floating or embedded website widget.

• Loads a chat panel for a project source and keeps users on your site.

• Supports theme syncing, floating launcher placement, responsive fullscreen behavior, accent color selection, and programmatic control.

Configuration

* Not used when containerId is set.

Theme Behavior

When theme is set to auto, the widget resolves the effective theme in this order:

1. html[data-theme]

2. html[data-color-mode]

3. html.dark

4. Browser prefers-color-scheme

This lets the widget match common docs and application themes without extra integration code.

Floating vs Embedded Mode

When containerId is not set, the widget is considered a floating widget.

If containerId is set, the widget is considered an embedded widget.

Floating mode is a default and should be used in a most cases. Embedded mode is a rare advanced use case for mounting the widget into a specific container on the page instead of document.body.

• Floating widgets always open fullscreen on mobile-width parent viewports and do not show a resize control.

• On desktop, floating widgets can switch between the compact panel and the expanded viewport mode.

• desktopFullscreenByDefault only changes the default desktop open state.

• Embedded widgets mount inline, do not use fixed viewport positioning, always open immediately, render without a launcher, and do not show close or fullscreen controls.

• Only the options marked with * in the configuration table are ignored when containerId is set.

Options Not Used In Embedded Mode

Embedded widgets still respect theme, brandColor, prefillStarterPrompt, and autoSendStarterPrompt.

Examples

Minimal Setup

<script>
  window.tlumaConfig = {
    source: "owner/repo"
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

Add Custom Attributes To The Widget Iframe

<script>
  window.tlumaConfig = {
    source: "owner/repo",
    iframeAttributes: { "data-my-attr": "x" }
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

Light Theme With Custom Brand Color

<script>
  window.tlumaConfig = {
    source: "owner/repo",
    theme: "light",
    brandColor: "green",
    button: "bottom-left",
    edgePadding: "24px"
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

Hidden Launcher

Use button: "hidden" when the widget should only open through JavaScript.

<script>
  window.tlumaConfig = {
    source: "owner/repo",
    button: "hidden",
    autoOpen: false
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

Open Expanded On Desktop By Default

<script>
  window.tlumaConfig = {
    source: "owner/repo",
    desktopFullscreenByDefault: true
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

Disable Background Preload

By default the widget warms the iframe in the background after DOMContentLoaded + 1000ms to reduce the first-open delay.

<script>
  window.tlumaConfig = {
    source: "owner/repo",
    preloadAfterMs: false
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

Mount Inline In A Container (Embedded Widget)

When containerId is set, the widget mounts into that element instead of the page body, so it behaves like inline page content rather than a fixed floating widget. Embedded widgets always open immediately, render without a launcher, do not show close or fullscreen controls, and ignore button, welcomePulse, edgePadding, desktopFullscreenByDefault, preloadAfterMs, and autoOpen.

<div id="ask-ai-demo"></div>

<script>
  window.tlumaConfig = {
    source: "owner/repo",
    containerId: "ask-ai-demo"
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

Prefill A Starter Prompt Without Sending

<script>
  window.tlumaConfig = {
    source: "owner/repo",
    prefillStarterPrompt: "How do I configure the GitHub auth flow?"
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

Send A Starter Prompt On First Fresh Load

<script>
  window.tlumaConfig = {
    source: "owner/repo",
    autoSendStarterPrompt: "Give me the quickest local development setup"
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>

JavaScript API

After the widget loads, the latest instance is available at window.TlumaAskAi.

window.TlumaAskAi.open();
window.TlumaAskAi.close();
window.TlumaAskAi.toggle();
window.TlumaAskAi.prefillPrompt("How do I configure SSO?");
window.TlumaAskAi.sendPrompt("Show me the fastest production deploy path");
window.TlumaAskAi.destroy();

• prefillPrompt(text) sets the input text without opening or sending the message.

• sendPrompt(text) opens the widget if needed and submits the prompt once the embedded chat is ready.

• close() and the closing side of toggle() are ignored for embedded widgets mounted with containerId.

If you render multiple widgets on one page, all instances are available in window.TlumaAskAi.instances, and the most recent one is also exposed as window.TlumaAskAi.latest.

Notes

• Define window.tlumaConfig before loading widget.js.

• source is the only required parameter.

• Use owner/repo for GitHub projects. Full GitHub URLs are not supported.

• Use iframeAttributes when you need the generated iframe to carry extra custom attributes.

• You do not need to pass internal iframe query parameters manually.

• preloadAfterMs defaults to 1000, which preloads the hidden iframe shortly after page load so the first open is faster. It is ignored when containerId is set.

• containerId accepts an element id. A leading # is also accepted.

• Embedded widgets mounted with containerId always open inline without a launcher and do not show close or fullscreen controls.

• button, welcomePulse, edgePadding, desktopFullscreenByDefault, preloadAfterMs, and autoOpen are ignored when containerId is set.

• Floating widgets always open fullscreen on mobile and hide the resize toggle there.

• prefillStarterPrompt and autoSendStarterPrompt are ignored when Tluma restores an existing session or the chat already contains content.

• For floating widgets, button: "hidden" and autoOpen: false keep the widget closed until you open it through the JavaScript API.

GitHub button

If you have no website and want to allow your GitHub users to ask questions about your project, you can still just link to the widget by using plain Markdown in your README.md or other docs:

[![Ask AI](https://tluma.ai/badge)](http://tluma.ai/ask-ai/<your_github_org>/<your_github_repo>)

Dont forget to replace <your_github_org> and <your_github_repo> with your actual GitHub organization and repository name. This will create a clickable badge in your README that takes users directly to the Tluma Ask AI widget for your project.