> ## Documentation Index
> Fetch the complete documentation index at: https://anam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed Anam on your website

> Add an Anam avatar to any website using the Widget, Player, or SDK.    Compare options and follow platform-specific setup guides.

There are three ways to add an Anam avatar to your site: the Widget, the Player, or the SDK.

## Which option should I use?

<Tip>
  **Widget** — A pre-built Web Component. The avatar loads directly on your page with its own UI. You can listen to events, handle tool calls, and control it from JavaScript.

  **Player** — A single iframe. The avatar runs inside a sandboxed frame, completely isolated from your page. The most compatible option across website builders, but you can't interact with it from your own code.

  **SDK** — A JavaScript library for building your own interface from scratch. Use this when the pre-built UIs don't fit your design and you want full control over the experience.
</Tip>

## Widget

The Widget loads as a `<anam-agent>` [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_Components) on your page. It handles its own authentication, renders inside a Shadow DOM (so it won't clash with your styles), and dispatches DOM events you can listen to.

<Tabs>
  <Tab title="Features">
    * Floating overlay or inline layout modes
    * DOM events for analytics, error handling, and custom behavior
    * Supports tool calls and text input
    * Configure appearance from Lab or HTML attributes
  </Tab>

  <Tab title="Requirements">
    * Your site must allow external JavaScript
    * Your domain must be added to the allowed list in Lab's Widget tab
    * Microphone access required for voice
  </Tab>

  <Tab title="Example code">
    ```html theme={"system"}
    <anam-agent agent-id="your-persona-id"></anam-agent>
    <script src="https://unpkg.com/@anam-ai/agent-widget" async></script>
    ```
  </Tab>
</Tabs>

See the [Widget documentation](/embed/widget/overview) for configuration, events, and framework-specific setup.

## Player

The Player runs inside an iframe. Your page and the avatar are fully isolated from each other — different JavaScript contexts, different stylesheets, no interaction between the two. This makes it the most broadly compatible option, especially on platforms that restrict custom JavaScript.

<Tabs>
  <Tab title="Features">
    * Full Anam interface in a sandboxed frame
    * Isolated from your site's CSS and JavaScript
    * Works on platforms that block custom scripts but allow iframes
  </Tab>

  <Tab title="Requirements">
    * Your site must allow iframe embedding
    * HTTPS required
    * Microphone access required for voice
  </Tab>

  <Tab title="Example code">
    ```html theme={"system"}
    <iframe
      src="https://lab.anam.ai/frame/SHARE_TOKEN"
      width="720"
      height="480"
      allow="microphone"
      style="border: none;">
    </iframe>
    ```
  </Tab>
</Tabs>

## SDK

The SDK gives you a JavaScript client and raw media streams. There's no pre-built UI — you build your own. Use this when you need complete control over how the avatar looks and behaves on your page.

<Tabs>
  <Tab title="Features">
    * Full control over layout and appearance
    * Direct access to video/audio streams
    * Programmatic session management
  </Tab>

  <Tab title="Requirements">
    * Your site must allow external JavaScript
    * HTTPS required
    * Microphone access required for voice
  </Tab>
</Tabs>

See the [SDK Reference](/javascript-sdk/reference/basic-usage) for usage details.

## Platform compatibility

Not every website builder supports every embed type. This depends on whether the platform lets you add custom JavaScript, iframes, or both.

| Platform      | Widget | Player | SDK | Notes                                            |
| ------------- | ------ | ------ | --- | ------------------------------------------------ |
| WordPress.org | ✅      | ✅      | ✅   |                                                  |
| Webflow       | ✅      | ✅      | ✅   | May need enterprise plan for script whitelisting |
| Squarespace   | ✅      | ✅      | ✅   | Requires paid plan                               |
| Jimdo Creator | ✅      | ✅      | ✅   | Requires paid plan                               |
| Shopify       | ✅      | ✅      | ❌   |                                                  |
| WordPress.com | ✅      | ✅      | ❌   | Requires paid plan                               |
| GoDaddy       | ✅      | ✅      | ❌   |                                                  |
| Wix           | ✅      | ❌      | ❌   | Requires paid plan                               |

<Accordion title="Platform-specific instructions">
  ### WordPress.com

  Requires Business plan (\$25/month) or higher. Add Widget or Player code via Custom HTML block. SDK is not supported.

  ### WordPress.org (self-hosted)

  All three embed options work. Add code via the Gutenberg editor (Custom HTML block), your theme's `footer.php`, or a plugin like "Insert Headers and Footers".

  ### Shopify

  **Player:** Go to Online Store > Themes > Customize, add a "Custom Liquid" section, paste the iframe code.

  **Widget/SDK:** Go to Online Store > Themes > Actions > Edit code, open `theme.liquid`, add the code before `</body>`. You may need to update your theme's Content Security Policy.

  ### Wix

  Requires a paid plan for custom code. Add Widget or Player code via Wix's HTML/Embed elements. SDK is not supported.

  ### Squarespace

  Requires Business plan or higher. Use a Code Block (HTML mode) for the Player, or Settings > Advanced > Code Injection for Widget/SDK.

  ### Webflow

  **Player:** Add an Embed element and paste the iframe code. Check Site Settings > Security > Secure Frame Headers if it doesn't load.

  **Widget/SDK:** Go to Project Settings > Custom Code, add to Footer Code. Changes aren't visible in the designer — publish first.

  ### GoDaddy

  **Widget/Player:** Add a "Custom Code" section and paste the embed code. SDK is not supported.

  ### Jimdo Creator

  Requires "Creator" mode (not "Dolphin"). Add an HTML/Widget element for the Player, or use Settings > Edit Head for Widget/SDK scripts.
</Accordion>

## Security

All embed options require HTTPS and microphone access. Users are prompted for microphone permissions the first time they interact with the avatar.

### Content Security Policy (CSP)

If your site has a CSP, add these directives for the option you're using:

```http theme={"system"}
# Widget
Content-Security-Policy: script-src https://unpkg.com/@anam-ai/; connect-src https://api.anam.ai wss://connect.anam.ai wss://connect-us.anam.ai wss://connect-eu.anam.ai;

# Player
Content-Security-Policy: frame-src https://lab.anam.ai;

# SDK
Content-Security-Policy: connect-src https://api.anam.ai wss://connect.anam.ai wss://connect-us.anam.ai wss://connect-eu.anam.ai;
```

### Browser support

Chrome/Edge 80+, Firefox 75+, Safari 14.1+, iOS Safari 14.5+, Chrome Android 80+.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Embed not appearing">
    * Check that your share token (Player) or agent ID (Widget) is correct
    * Open browser DevTools (F12) and look for errors in the console
    * Confirm your site is served over HTTPS, not HTTP
    * Check that your platform plan supports custom embeds
    * Try disabling ad blockers
  </Accordion>

  <Accordion title="Microphone not working">
    * Click the lock icon in the address bar to check permissions
    * Microphone only works over HTTPS
    * Try Chrome or Edge for best compatibility
    * Disable privacy extensions that might block permissions
    * Look for "NotAllowedError" or "NotFoundError" in the console
  </Accordion>

  <Accordion title="Cross-origin errors">
    * Add the required domains to your Content Security Policy (see above)
    * For Player: check that X-Frame-Options isn't set to DENY
    * For Widget: make sure your domain is in the allowed list in Lab
    * Some platforms have non-configurable security policies
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use multiple embed options on the same page?">
    No. Use one Anam instance per page.
  </Accordion>

  <Accordion title="What's the difference between a share token and an agent ID?">
    The Player uses a share token (generated from the Share button in Lab). The Widget uses an agent ID (your persona's ID) and handles authentication automatically via domain allowlisting.
  </Accordion>

  <Accordion title="Can I customize the appearance?">
    **Widget:** Yes — layout, position, UI toggles, and more. Configure from Lab or with HTML attributes. See [Widget configuration](/embed/widget/configuration).

    **Player:** Limited to sizing the iframe.

    **SDK:** Full control — you build the UI yourself.
  </Accordion>

  <Accordion title="What if users deny microphone access?">
    The Widget and SDK support text input as a fallback (enable with the `ui-text-input` attribute or SDK configuration). The Player shows a message asking users to grant access.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Widget documentation" icon="puzzle-piece" href="/embed/widget/overview">
    Configuration, events, and framework-specific setup guides.
  </Card>

  <Card title="SDK reference" icon="code" href="/javascript-sdk/reference/basic-usage">
    Build your own interface with the JavaScript SDK.
  </Card>
</CardGroup>