Skip to main content
Once your agent is published, 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.
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.

​
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: 
<script
  src="https://cdn-dev.tryhamsa.com/assets/embed.js"
  data-embed-token="YOUR_AGENT_TOKEN"
  data-position="bottom-right"
></script>
Always copy the snippet from your dashboard — it has the correct token and your configured appearance. The attributes below are for reference.

​
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.
AttributeValuesDefaultDescription
data-embed-tokenyour agent token—Required. Which published agent to load.
data-positionbottom-right, bottom-left, bottom-centerbottom-rightWhere the floating button sits.
data-labelany text(none)Text next to the button (a pill). Omit it for a round icon button.
data-sizesm, md, lgmdSize of the floating button.
data-accenthex color#6366f1Color of the floating button.
data-auto-startfalse(auto-starts)By default the call starts as soon as the widget opens. Set to false to let the visitor press Start first.
data-launcherauto, always, neverautoControls our floating button (see 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: 
<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": 
<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.

Publish agent

Create the public page the widget loads.