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

# Embed on your website

> Add your published agent to your own website as a floating widget.

Once your agent is [published](/agents/publishing/publish-agent), you can embed it on your own website. The embed adds a floating button to your pages; when a visitor clicks it, the agent opens in a full-screen overlay — the same public page, framed inside your site.

<Info>
  Publish your agent first. The embed uses your agent's publish token, so the agent must be published for the widget to work. If you unpublish, the widget stops working.
</Info>

## Add the widget

1. On the agent's publish page, open the **Embed** section.
2. Copy the `<script>` snippet. It already includes your agent's token and the appearance you configured.
3. Paste it into your website's HTML, just before the closing `</body>` tag, on every page where you want the widget to appear.

A snippet looks like this:

```html theme={null}
<script
  src="https://cdn-dev.tryhamsa.com/assets/embed.js"
  data-embed-token="YOUR_AGENT_TOKEN"
  data-position="bottom-right"
></script>
```

<Info>
  Always copy the snippet from your dashboard — it has the correct token and your configured appearance. The attributes below are for reference.
</Info>

## Configuration

Add `data-*` attributes to the `<script>` tag. Position, size, label, and auto-start can also be set visually in the dashboard and are baked into the copied snippet.

| Attribute          | Values                                         | Default         | Description                                                                                                  |
| ------------------ | ---------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
| `data-embed-token` | your agent token                               | —               | **Required.** Which published agent to load.                                                                 |
| `data-position`    | `bottom-right`, `bottom-left`, `bottom-center` | `bottom-right`  | Where the floating button sits.                                                                              |
| `data-label`       | any text                                       | *(none)*        | Text next to the button (a pill). Omit it for a round icon button.                                           |
| `data-size`        | `sm`, `md`, `lg`                               | `md`            | Size of the floating button.                                                                                 |
| `data-accent`      | hex color                                      | `#6366f1`       | Color of the floating button.                                                                                |
| `data-auto-start`  | `false`                                        | *(auto-starts)* | By default the call starts as soon as the widget opens. Set to `false` to let the visitor press Start first. |
| `data-launcher`    | `auto`, `always`, `never`                      | `auto`          | Controls our floating button (see [Use your own button](#use-your-own-button)).                              |

## Use your own button

To open the widget from your own button or link, add `data-hamsa-trigger` to any element:

```html theme={null}
<button data-hamsa-trigger>Talk to us</button>
```

By default (`data-launcher="auto"`), our floating button hides automatically when you add your own trigger. To always hide our button, set `data-launcher="never"`:

```html theme={null}
<script
  src="https://cdn-dev.tryhamsa.com/assets/embed.js"
  data-embed-token="YOUR_AGENT_TOKEN"
  data-launcher="never"
></script>
<button data-hamsa-trigger>Talk to us</button>
```

You can add `data-hamsa-trigger` to as many elements as you like, including ones added after the page loads.

## How it works

* The script adds a floating button to your page.
* Clicking the button (or any `data-hamsa-trigger` element) opens the agent in a full-screen overlay on top of your site.
* The visitor talks to the agent just like on the public page.
* Closing the overlay (the close button or the **Esc** key) returns them to your site.

## Related

<CardGroup cols={2}>
  <Card title="Publish agent" icon="globe" href="/agents/publishing/publish-agent">
    Create the public page the widget loads.
  </Card>
</CardGroup>