Tluma Widget

https://tluma.ai/widget-docs
Admin
Tluma Widget is an embeddable Ask AI chat widget that adds conversational AI to websites, allowing...
Tokens:2,762
Snippets:18
Trust Score:2.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Tluma Widget with Configuration

Source: https://tluma.ai/widget-docs

This snippet demonstrates how to install the Tluma widget by adding a configuration object and the widget script to your HTML. The configuration object allows customization of various aspects like the project source, theme, brand color, button placement, and more. Ensure the `window.tlumaConfig` object is defined before the widget script is loaded.

```html
<script>
  window.tlumaConfig = {
    source: "owner/repo",
    theme: "auto",
    brandColor: "blue",
    button: "bottom-right",
    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",
    autoOpen: false
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>
```

--------------------------------

### Widget Installation and Configuration

Source: https://tluma.ai/widget-docs

This section details how to install the Tluma widget by adding a configuration object and the script tag to your HTML. It also outlines the various configuration parameters available to customize the widget's behavior and appearance.

```APIDOC
## Widget Installation and Configuration

### Description
Install the Tluma widget by including a `window.tlumaConfig` object with desired settings before loading the widget script. This section details the available configuration options.

### Method
HTML Snippet

### Endpoint
N/A (Client-side script)

### Parameters
#### Configuration Options
- **`source`** (string) - Required - Project source to load. Use GitHub `owner/repo` shorthand or a non-GitHub website URL.
- **`theme`** (string) - Optional - Controls widget color mode. Supported values: `dark`, `light`, `auto`. Default: `auto`.
- **`brandColor`** (string) - Optional - Controls launcher and accent colors. Supported values: `blue`, `red`, `orange`, `green`, `slate`. Default: `blue`.
- **`button`** (string) - Optional - Controls launcher placement for floating widgets. Supported values: `bottom-right`, `bottom-left`, `top-right`, `top-left`, `hidden`. Default: `bottom-right`. (*Not used when `containerId` is set*).
- **`edgePadding`** (string) - Optional - Distance between the floating widget and the viewport edge. Accepts any valid CSS length. Default: `1rem`. (*Not used when `containerId` is set*).
- **`desktopFullscreenByDefault`** (boolean) - Optional - For floating widgets, opens the desktop panel in expanded viewport mode by default. Default: `false`. (*Not used when `containerId` is set*).
- **`preloadAfterMs`** (number | false) - Optional - Starts loading the hidden iframe this many milliseconds after `DOMContentLoaded`. Set `false` to disable background preload or `0` to start immediately. Default: `1000`.
- **`containerId`** (string) - Optional - Mounts the widget into an existing element ID instead of `document.body`. This enables embedded mode.
- **`prefillStarterPrompt`** (string) - Optional - Seeds the chat input with text without sending it, for fresh chats.
- **`autoSendStarterPrompt`** (string) - Optional - Opens the widget and submits the prompt automatically once the embedded chat is ready, for fresh chats.
- **`autoOpen`** (boolean) - Optional - Opens the widget panel automatically after the script loads. Default: `false`. (*Not used when `containerId` is set*).

### Request Example
```html
<script>
  window.tlumaConfig = {
    source: "owner/repo",
    theme: "auto",
    brandColor: "blue",
    button: "bottom-right",
    edgePadding: "1rem",
    autoOpen: false
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>
```

### Response
N/A (Client-side script execution)

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Initialize Tluma AI Widget with Minimal Configuration

Source: https://tluma.ai/widget-docs

The minimal setup requires defining the source repository in the window.tlumaConfig object before loading the widget script.

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

--------------------------------

### Prefill and Auto-send Starter Prompts

Source: https://tluma.ai/widget-docs

Configures the widget to either pre-populate the input field or automatically send a prompt upon the first load.

```html
<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>

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

--------------------------------

### Enable Desktop Fullscreen Mode

Source: https://tluma.ai/widget-docs

Forces the widget to open in a fullscreen layout on desktop devices by default.

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

--------------------------------

### Configure Hidden Launcher and Manual Opening

Source: https://tluma.ai/widget-docs

Disables the default launcher button and prevents automatic opening, allowing the widget to be triggered exclusively via JavaScript.

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

--------------------------------

### Configure Widget Theme and Appearance

Source: https://tluma.ai/widget-docs

Customizes the widget's visual style using theme and brandColor properties, along with positioning options like button and edgePadding.

```html
<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>
```

--------------------------------

### Interact with Widget via JavaScript API

Source: https://tluma.ai/widget-docs

Provides methods to programmatically open, close, toggle, prefill, send prompts, or destroy the widget instance.

```javascript
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();
```

--------------------------------

### Theme Behavior

Source: https://tluma.ai/widget-docs

Explains how the Tluma widget determines its theme when the `theme` configuration is set to `auto`, prioritizing specific HTML attributes and browser settings.

```APIDOC
## Theme Behavior

### Description
When the `theme` configuration option is set to `auto`, the widget resolves the effective theme by checking the following in order:

1.  `html[data-theme]` attribute.
2.  `html[data-color-mode]` attribute.
3.  `html.dark` class.
4.  Browser's `prefers-color-scheme` setting.

This allows the widget to automatically match common documentation and application themes without requiring explicit integration code.

### Method
Client-side Theme Resolution

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Mount Widget Inline in a Container

Source: https://tluma.ai/widget-docs

Renders the widget inside a specific DOM element using containerId, transforming it into an embedded component.

```html
<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>
```

--------------------------------

### Floating vs. Embedded Mode

Source: https://tluma.ai/widget-docs

Differentiates between the floating and embedded modes of the Tluma widget, explaining their characteristics, use cases, and how certain configuration options behave differently in each mode.

```APIDOC
## Floating vs. Embedded Mode

### Description
The Tluma widget operates in two modes: **floating** (default) and **embedded**. The mode is determined by the presence of the `containerId` configuration option.

### Floating Mode
- Activated when `containerId` is **not** set.
- The widget appears as a floating element, typically with a launcher button.
- On mobile, it always opens fullscreen and lacks a resize control.
- On desktop, it can switch between a compact panel and an expanded viewport.
- Options marked with `*` in the configuration table are applicable.

### Embedded Mode
- Activated when `containerId` **is** set.
- The widget mounts inline within the specified container element.
- Does not use fixed viewport positioning.
- Opens immediately without a launcher.
- Renders without close or fullscreen controls.
- Ignores floating-only options (marked with `*`).
- Waits up to 10 seconds for the target container element to appear.

### Method
Widget Operational Mode

### Endpoint
N/A

### Parameters
N/A

### Request Example
**Floating Mode (Default):**
```html
<script>
  window.tlumaConfig = {
    source: "owner/repo"
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>
```

**Embedded Mode:**
```html
<script>
  window.tlumaConfig = {
    source: "owner/repo",
    containerId: "my-widget-container"
  };
</script>
<script src="https://tluma.ai/widget.js" async></script>
```

### Response
N/A

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Disable Background Preload

Source: https://tluma.ai/widget-docs

Disables the automatic background warming of the iframe to prevent early resource loading.

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