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

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:

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

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.