> ## Documentation Index
> Fetch the complete documentation index at: https://anam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the Anam Widget

> Configure the Anam Widget with HTML attributes and Lab settings, then control its appearance, position, persona, and runtime behaviour.

The widget loads its configuration from your published persona settings in [Anam Lab](https://lab.anam.ai). You can override any setting by adding HTML attributes directly to the `<anam-agent>` element.

## Layout modes

### Floating

The default mode. The widget renders as a fixed-position overlay, anchored to a corner of the viewport. Users click to expand it into a conversation panel.

```html theme={"system"}
<anam-agent
  agent-id="your-persona-id"
  layout="floating"
  position="bottom-right"
  initial-state="minimized"
></anam-agent>
```

The `initial-state` attribute controls whether the widget starts expanded or minimized:

* `"expanded"` (default) the conversation panel is open immediately
* `"minimized"` only the floating orb is visible; the user clicks to expand

### Inline

The widget fills its parent container and becomes part of your page layout. There is no floating orb or expand/collapse behavior.

```html theme={"system"}
<div style="width: 100%; max-width: 720px; aspect-ratio: 3/2;">
  <anam-agent
    agent-id="your-persona-id"
    layout="inline"
  ></anam-agent>
</div>
```

> [!TIP]
>
> The inline widget inherits the dimensions of its parent. Make sure the parent has explicit width and height (or aspect-ratio) set.

## Custom positioning

For `floating` layout, the `position` attribute supports both predefined corners and custom CSS values using bracket syntax.

### Predefined positions

| Value | CSS Result |
| - | - |
| `"bottom-right"` | `bottom: 24px; right: 24px` |
| `"bottom-left"` | `bottom: 24px; left: 24px` |
| `"top-right"` | `top: 24px; right: 24px` |
| `"top-left"` | `top: 24px; left: 24px` |

### Bracket syntax

For precise control, use bracket syntax to set arbitrary CSS position values:

```html theme={"system"}
{/*  20px from the top, flush to the right edge  */}
<anam-agent
  agent-id="..."
  position="[top-20,right-0]"
></anam-agent>

{/*  100px from the bottom, 40px from the left  */}
<anam-agent
  agent-id="..."
  position="[bottom-100,left-40]"
></anam-agent>
```

The format is `[property-value,property-value,...]` where:

* Allowed properties: `top`, `right`, `bottom`, `left`, `margin`, `margin-top`, `margin-right`, `margin-bottom`, `margin-left`
* Bare numbers are treated as pixels (e.g., `top-20` becomes `top: 20px`)
* CSS units can be specified directly (e.g., `top-2rem`)

## Preview video

Before a call starts, the widget plays a short, muted loop of the avatar over its still image. To show only the still image, turn off **Preview video** under **Interface** in the **Embed** tab in Anam Lab, then publish the persona. Embedded widgets can take a few minutes to pick up the change. You can also set the attribute on the element:

```html theme={"system"}
<anam-agent
  agent-id="your-persona-id"
  ui-preview-video="false"
></anam-agent>
```

With the preview video off, the widget doesn't download the video. The attribute overrides the Lab setting for that element.

## Attributes reference

`agent-id` is required. All other attributes are optional and will fall back to your Lab configuration.

| Attribute | Type | Default | Description |
| - | - | - | - |
| `agent-id` | `string` | | Persona ID. Required for fetching config and creating sessions. |
| `api-base-url` | `string` | `https://api.anam.ai` | API URL override. Only needed for non-production environments. |
| `layout` | `"floating"` \| `"inline"` | `"floating"` | Widget layout mode. |
| `initial-state` | `"expanded"` \| `"minimized"` | `"expanded"` | Initial state when layout is `floating`. Ignored for `inline`. |
| `position` | `string` | `"bottom-right"` | Corner position or custom bracket syntax. Only applies to `floating` layout. |
| `ui-mute-button` | `"true"` \| `"false"` | `"true"` | Show the microphone mute button. |
| `ui-text-input` | `"true"` \| `"false"` | `"true"` | Show the text input field. |
| `call-to-action` | `string` | `"Talk to our assistant"` | Custom text for the start button. |
| `avatar-url` | `string` | | Override avatar thumbnail image URL. |
| `avatar-video-url` | `string` | | Override avatar preview video URL. |
| `ui-preview-video` | `"true"` \| `"false"` | `"true"` | Play the avatar preview video before a call. `"false"` shows the still image. |
| `agent-name` | `string` | | Override persona name displayed in the default CTA. |

> [!TIP]
>
> You can get avatar preview media from [GET `/v1/avatars/{id}`](https://anam.ai/docs/api-reference/avatars/get-avatar).
> The returned `videoUrl` expires after 1 hour, so use a freshly fetched URL or
> self-host the MP4 before putting it in long-lived widget configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.