> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 (current TTS) and Pulse (current
> STT). Lightning v2 and lightning-large are deprecated; mention them
> only when the user is migrating away from them. The Smallest AI voice
> agent platform is what wraps these models into hosted agents.

# Widget

> Embed your voice agent directly on your website.

![Widget configuration](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/f6342ed4a319aa7a70f44e732632d0199e50aa4abd38e54aea1ee15dcb21acc1/products/atoms/pages/platform/building-agents/images/widget-full.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060202Z&X-Amz-Expires=604800&X-Amz-Signature=c6919498be15bdaa4c5fc55d09fb2a7aa1650721fa43607949f0d5d93c9b0536&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Embed Code

At the top, you'll find your embed snippet. Copy this and paste it into your website's HTML.

```html
<atoms-widget assistant-id="YOUR_AGENT_ID"></atoms-widget>
<script src="https://unpkg.com/atoms-widget-core@latest/dist/embed/widget.umd.js"></script>
```

That's it — the widget will appear on your site. Everything else on this page customizes how it looks and behaves.

## Mode

Choose how users interact with your widget:

| Mode      | Description                                                                       |
| --------- | --------------------------------------------------------------------------------- |
| **Chat**  | Users type messages. Good for quieter environments or when voice isn't practical. |
| **Voice** | Users speak directly. The full voice agent experience in the browser.             |

Pick based on your audience. Voice feels more natural for most support scenarios. Chat works better for quick questions or when users might be in public.

## Allowlist

By default, any website can embed your widget. That's convenient for testing, but risky for production.

**Set up an allowlist** before going live. Without one, anyone could embed your agent on their site, potentially running up your usage or misrepresenting your brand.

Click **+ Add host** to specify which domains can use your widget:

```
yourdomain.com
app.yourdomain.com
```

Only these sites will be able to load the widget.

## Appearance

### Variant

How much screen space should the widget take?

#### Tiny

![Tiny widget](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/e7b3874b2044e41827313e21b12545c640251fe7fc44610343ec215357c78b5c/products/atoms/pages/platform/building-agents/images/widget-tiny.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060202Z&X-Amz-Expires=604800&X-Amz-Signature=52cfbfd347ba36d98dad0beff2e21bb128bc449e1e1f1ec8da6847a05777d8f6&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Minimal footprint. Just a small button that expands when clicked. Best when you want the widget available but unobtrusive.

#### Compact

![Compact widget](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/9298f6ec41c744bfb0e5e1c1a488a83e94b59b7b5a6dac7033cfa36b86d488b7/products/atoms/pages/platform/building-agents/images/widget-compact.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060202Z&X-Amz-Expires=604800&X-Amz-Signature=5f12ecb5c9fd8aa3435b01953f136b35ebcd888bdeb891227a158b01ab6482de&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Balanced size. Visible enough to invite interaction, but doesn't dominate the page. Good default for most sites.

#### Full

![Full widget](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/e217eacdf715037812c14b7c6ec84ddfd529074b937ba17f47070a45da7e8b7a/products/atoms/pages/platform/building-agents/images/widget-full-variant.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060202Z&X-Amz-Expires=604800&X-Amz-Signature=02bae1c9d8b91260e938988ffc37700eafed02b9a208ba10d041d67c2e836869&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Prominent and hard to miss. Use when the widget is a primary way users should interact with your site.

### Placement

Where the widget button appears on screen. Currently supports **Bottom-right**.

The preview on this page always shows bottom-right. The placement you choose applies when embedded on your actual site.

## Theme

Make the widget match your brand.

| Setting                      | What it affects                 | Default   |
| ---------------------------- | ------------------------------- | --------- |
| **Widget Background Color**  | Main widget background          | `#ffffff` |
| **Brand Accent Color**       | Buttons, highlights             | `#2d9d9f` |
| **Agent Message Background** | Agent response bubbles          | `#f3f4f6` |
| **Text on Accent Color**     | Text on accent-colored elements | `#FFFFFF` |
| **Primary Text Color**       | Main text                       | `#111827` |
| **Secondary Text Color**     | Subtitles, hints                | `#6b7280` |

Click any color to open a picker, or paste a hex code directly.

## Avatar

Upload an image to represent your agent in the widget. This appears in the chat interface and helps humanize the experience.

| Spec                  | Value         |
| --------------------- | ------------- |
| **Recommended size**  | 172px × 172px |
| **Maximum file size** | 2MB           |
| **Format**            | PNG, JPG      |

Drag and drop or click to upload.

## Text Contents

Customize the copy users see.

| Field                      | What it controls                     | Default                |
| -------------------------- | ------------------------------------ | ---------------------- |
| **Start Button Text**      | Button to begin conversation         | "Start"                |
| **End Button Text**        | Button to end conversation           | "End"                  |
| **Chat Placeholder**       | Input field placeholder              | "Type your message..." |
| **CTA Name** (optional)    | Call-to-action text on widget button | "Talk to Atoms"        |
| **Widget Name** (optional) | Name displayed in widget header      | "Atoms"                |

Make these match your brand voice. "Chat with us" feels different than "Get help" or "Ask a question."

## Terms & Conditions

If you need users to agree to terms before using the widget, enable **Require consent**.

When enabled, users see a checkbox they must tick before starting. This is useful for:

* GDPR compliance
* Recording consent
* Specific terms of service

## Preview

As you make changes, the widget preview updates in real-time in the bottom-right corner of the page. Test different settings before deploying.

## Deploying

Once configured, copy the embed code and add it to your website. For detailed installation instructions across different platforms:

#### [Adding to Your Website](/voice-agents/platform/create-agent/agent-settings/widget)

Step-by-step deployment guide