Website Chat Widget

Every bot in Annie has a unique Widget ID used to connect the chat widget to your assistant.

Open the Annie Portal

Go to Settings

Navigate to Settings and set up your chat widget. Your Widget ID will be displayed here — copy it for use in the embed code below.

Add the following snippet to your website. Replace YOUR_WIDGET_ID with your actual Widget ID. You can also find this install script in the widget settings in your Annie Portal.

<!DOCTYPE html>
<html>
<head>
    <title>Your Website</title>
</head>
<body>
    <!-- Your website content -->

    <!-- Annie Chat Widget -->
    <script src="https://widget.helloannie.co/api/embed/v2" async></script>

    <annie-widget widget-id="YOUR_WIDGET_ID"></annie-widget>

</body>
</html>

The widget will appear as a floating chat bubble in the bottom-right corner of your page.

Configuration

Most widget settings are managed from the Settings area of your Annie Portal. For per-page overrides, use the <annie-widget> element instead of the query-string install. Drop the widgetId parameter from the script URL and add an <annie-widget> element with your attributes:

<script src="https://widget.helloannie.co/api/embed/v2" async></script>

<annie-widget widget-id="YOUR_WIDGET_ID" position="left"></annie-widget>

Any attribute set on <annie-widget> overrides the portal configuration for that page.

Position

Control where the chat bubble appears on your page.

<!-- Bottom-right (default) -->
<annie-widget widget-id="YOUR_WIDGET_ID" position="right"></annie-widget>

<!-- Bottom-left -->
<annie-widget widget-id="YOUR_WIDGET_ID" position="left"></annie-widget>

Default State

Control how the widget appears when the page first loads.

<!-- Show a preview label with a greeting (default) -->
<annie-widget widget-id="YOUR_WIDGET_ID" default-state="preview"></annie-widget>

<!-- Open the chat automatically -->
<annie-widget widget-id="YOUR_WIDGET_ID" default-state="open" default-state-mobile="closed"></annie-widget>

<!-- Just show the bubble, nothing else -->
<annie-widget widget-id="YOUR_WIDGET_ID" default-state="closed"></annie-widget>

You can set a different default state for mobile devices using default-state-mobile.

Delay

Wait a number of seconds before showing the widget when the page first loads.

<!-- Wait 3 seconds before showing -->
<annie-widget widget-id="YOUR_WIDGET_ID" delay="3"></annie-widget>

Mobile Margins

Adjust how far the chat bubble sits from the edges of the screen on mobile. Useful when your page has a sticky footer or bottom navigation the bubble would otherwise cover.

<!-- Raise the chat bubble 60px on mobile (e.g., above a sticky footer) -->
<annie-widget
  widget-id="YOUR_WIDGET_ID"
  margin-bottom-mobile="60"
></annie-widget>

Both margin-bottom-mobile and margin-side-mobile can also be set in the Annie Portal under the widget’s Advanced section. The attribute values override whatever is configured in the portal, so you can adjust placement per-page.

Inline Mode (Custom Position)

Instead of a floating bubble, you can embed the widget directly into your page layout. This is useful for landing pages, contact pages, or any place where you want the chat to be part of the page content. Set position="custom" and the widget renders inline at its default size with no floating button.

<annie-widget
  widget-id="YOUR_WIDGET_ID"
  position="custom"
></annie-widget>

Custom Size

Override the default dimensions with width and height attributes.

<annie-widget
  widget-id="YOUR_WIDGET_ID"
  position="custom"
  width="500px"
  height="700px"
></annie-widget>

In inline mode, the widget is always visible — there is no open/close button. Use the JavaScript API below if you need to show or hide it programmatically.

JavaScript API

The widget exposes a global API at window.__annie.widget for programmatic control.

// Open the chat
window.__annie.widget.open()

// Close the chat
window.__annie.widget.close()

// Toggle open/closed
window.__annie.widget.toggle()

// Check if the chat is open
window.__annie.widget.isOpen() // true or false

Full Example

Here’s a complete example with common options configured:

<script src="https://widget.helloannie.co/api/embed/v2" async></script>

<annie-widget
  widget-id="YOUR_WIDGET_ID"
  position="right"
  default-state="preview"
  default-state-mobile="closed"
  delay="2"
></annie-widget>

Attribute Reference

Attribute	Type	Default	Description
`widget-id`	`string`	required	Your bot’s Widget ID
`position`	`"right"` \| `"left"` \| `"custom"`	`"right"`	Where the widget appears. `"custom"` enables inline mode.
`default-state`	`"open"` \| `"closed"` \| `"preview"`	`"preview"`	Initial state on desktop
`default-state-mobile`	`"open"` \| `"closed"` \| `"preview"`	`"closed"`	Initial state on mobile
`delay`	`number`	`0`	Seconds to wait before showing the widget
`margin-bottom-mobile`	`number`	`20`	Space in px between the chat bubble and the bottom of the screen on mobile. Overrides the value set in the Annie Portal.
`margin-side-mobile`	`number`	`20`	Space in px between the chat bubble and the side of the screen on mobile. Overrides the value set in the Annie Portal.
`width`	`string`	`"380px"`	Widget width (inline mode only)
`height`	`string`	`"612px"`	Widget height (inline mode only)

Get Your Widget ID

Install the Widget

Configuration

Position

Default State

Delay

Mobile Margins

Inline Mode (Custom Position)

Custom Size

JavaScript API

Full Example

Attribute Reference

​Get Your Widget ID

​Install the Widget

​Configuration

​Position

​Default State

​Delay

​Mobile Margins

​Inline Mode (Custom Position)

​Custom Size

​JavaScript API

​Full Example

​Attribute Reference

Get Your Widget ID

Install the Widget

Configuration

Position

Default State

Delay

Mobile Margins

Inline Mode (Custom Position)

Custom Size

JavaScript API

Full Example

Attribute Reference