Configuration

Configure the widget’s appearance and behavior with HTML attributes on the script tag. Everything on this page mirrors the widget source; when an attribute is absent, the tenant’s dashboard configuration applies.

<script
  src="https://cdn.animam.ai/widget.js"
  data-tenant="your-slug"
></script>

The three display modes

Mode	What it looks like	When to use
`bubble` (default)	Floating chat bubble, bottom corner, opens a modal overlay	The classic website assistant
`sidebar`	Launcher button + a docked side panel	Agent-heavy sites where the conversation stays open while browsing
`inline`	The chat renders inside a container of your page	A dedicated “assistant” page or embedded support area

<!-- Sidebar, 480px wide, pushing the page content instead of overlaying it -->
<script src="https://cdn.animam.ai/widget.js"
  data-tenant="your-slug"
  data-mode="sidebar"
  data-sidebar-width="480"
  data-sidebar-push="true"
></script>

<!-- Inline, inside your own container -->
<div id="my-chat" style="height: 480px"></div>
<script src="https://cdn.animam.ai/widget.js"
  data-tenant="your-slug"
  data-mode="inline"
  data-target="#my-chat"
></script>

Attribute reference

Attribute	Type	Description	Default
`data-tenant`	string	Tenant slug (required)	—
`data-mode`	string	`bubble` \| `inline` \| `sidebar`	`bubble`
`data-segment`	string	Contextual segment slug	`default`
`data-color`	string	Primary color (hex)	Tenant config
`data-avatar`	string	Avatar image URL	Tenant config / chat icon
`data-position`	string	`right` \| `left`	`right`
`data-locale`	string	Widget language (e.g. `fr`, `en`)	Browser language
`data-auto-open`	boolean	Open the chat automatically	`false`
`data-auto-open-delay`	number	Seconds before auto-open	`15`
`data-auto-open-scroll`	number	Scroll % that triggers auto-open	`30`
`data-teaser`	string	Teaser text shown next to the bubble	Tenant config
`data-pyrotechnics`	boolean	Attention effects on the bubble (pulse) — set `"false"` to disable	`true`
`data-target`	string	CSS selector of the container (inline mode)	—
`data-sidebar-width`	number	Panel width in px, clamped 280–560 (sidebar mode)	`400`
`data-sidebar-push`	boolean	Squeeze page content instead of overlaying (sidebar, desktop)	`false`
`data-visitor-identify`	string	Identified-visitor payload (visitor auth)	—
`data-visitor-token`	string	Signed visitor JWT (visitor auth)	—

Precedence: attributes override the tenant’s dashboard configuration for that page only. Anything not set here (welcome screen, booking CTA, AI-transparency banner, “powered by”) is resolved server-side from the tenant config — the persona itself (name, tone, avatar) lives in Dashboard → Agent → Personality.

Auto-open

Auto-open fires once per visitor session, whichever comes first of the delay or the scroll threshold:

<script src="https://cdn.animam.ai/widget.js"
  data-tenant="your-slug"
  data-auto-open="true"
  data-auto-open-delay="10"
  data-auto-open-scroll="50"
></script>

JavaScript API

The widget exposes window.AnimamChat once loaded (listen for the animam:ready event):

window.addEventListener('animam:ready', () => {
  AnimamChat.open()
  AnimamChat.close()
  AnimamChat.toggle()
  AnimamChat.isOpen()                  // boolean
  AnimamChat.sendMessage('Hello!')     // send programmatically

  AnimamChat.onMessage((m) => console.log(m))
  AnimamChat.onOpen(() => {})
  AnimamChat.onClose(() => {})
  AnimamChat.on('escalated', () => {}) // full event list: see Events
  AnimamChat.off('escalated', handler)

  // WebMCP "site actions" — register a client-side tool the agent can call
  AnimamChat.registerTool(tool)
  AnimamChat.unregisterTool('tool-name')
})

Full event list (message, open, close, ready, escalated, human_message, status_change, tool_call): see Events. For client-side tools: see WebMCP site actions.

Examples

Open from your own button

<script src="https://cdn.animam.ai/widget.js" data-tenant="your-slug" data-pyrotechnics="false"></script>
<button onclick="AnimamChat.open()">Need help?</button>

<script src="https://cdn.animam.ai/widget.js"
  data-tenant="your-slug"
  data-mode="sidebar"
  data-teaser="A question? I know this site by heart."
></script>

Two sibling scripts share the same tenant config:

Form widget (form.js) — renders one of your form tools as a standalone form: data-tenant, data-tool, data-target, data-color, data-submit-text, data-success-redirect.
Voice button (voice-enabled tenants) — data-tenant, data-target, data-label, data-position, data-style, data-color, data-segment.

Getting Started

For AI Agents

Widget

Customization

MCP Server

WordPress

Guides

The three display modes

Attribute reference

Auto-open

JavaScript API

Examples

Open from your own button

Sidebar assistant with a custom teaser

​The three display modes

​Attribute reference

​Auto-open

​JavaScript API

​Examples

​Open from your own button

​Sidebar assistant with a custom teaser

​Related widgets

The three display modes

Attribute reference

Auto-open

JavaScript API

Examples

Open from your own button

Sidebar assistant with a custom teaser

Related widgets