Configuration

Configure the widget with HTML attributes, Lab settings, and custom positioning

The widget loads its configuration from your published persona settings in Anam Lab. 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.

<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.

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

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:

{/*  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)

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.
agent-name	string		Override persona name displayed in the default CTA.

You can get avatar preview media from GET /v1/avatars/{id}. 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.