Quick start

Add a Handhold agent to your website. Load the SDK script, then set up your agent type.

Note: the integration interface may change as we iterate. We will notify you of any breaking changes.

Add the SDK script to your page, then follow the setup for your agent type. The snippets below are ready-made for you (with your agent's ID filled in) in the agent's Embed dialog in Handhold.

<!-- Load the SDK -->
<script async src="https://handhold.io/demo/embed.js"></script>

Demo agent

Open the demo in an overlay from any button or link on your page:

<button type="button" onclick="window.handhold.openDemo({ id: 'your-id-here' })">Start</button>

Or render it inline via iframe:

<iframe
  src="https://handhold.io/demo/your-id-here/embedded"
  allow="autoplay; microphone"
  style="width:100%;height:100%;overflow:hidden;border:none;border-radius:12px;"
></iframe>

openDemo also accepts known customer data and UTM attribution; see the API reference.

Onboarding / Inbound agent

Add the agent iframe. The mode parameter in its src sets how the agent appears:

  • mode=launcher: a launcher button your visitors click to open the agent.
  • mode=input: an always-open chat bar at the bottom center of the page.
<iframe
  src="https://handhold.io/demo/your-id-here/tour?mode=launcher"
  allow="autoplay; microphone"
  style="position:fixed;bottom:16px;right:16px;z-index:9999;border:none;outline:none;height:0px;width:0px;pointer-events:auto;"
></iframe>

The iframe deliberately starts at 0×0: embed.js sizes and positions the agent at runtime, so the agent only appears when the SDK script is also on the page.

To open an Onboarding agent from your own UI (a help button, a stuck moment) use programmatic triggers. To open an Inbound agent with a visitor's question, pass initialQuery to openDemo.

Position. The launcher anchors to the bottom-right by default. Add &position=left or &position=center to the iframe src to anchor it elsewhere (three values: left, center, right). The inline style should match (e.g. left:16px for left, left:50%;transform:translateX(-50%) for center). The chat bar ignores position.

Draggable. Visitors can drag the launcher to a different side. Their chosen side persists in the browser across page reloads. Visitors can also drag an Onboarding agent's chat bar away from the bottom center, for example when it covers a button: it shrinks into a small button and rests on the left or right of the page. Clicking that button, dragging it back, or starting a conversation brings the chat bar back to the bottom center. Otherwise it stays collapsed for the rest of their visit. On a page as narrow as the chat bar, such as a phone, it doesn't move.

Next steps

For AI agents: a clean Markdown version is available at /docs.md.