Quick start

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', modality: 'VOICE' })">
  Start
</button>

Or render it inline via iframe:

<iframe
  src="https://handhold.io/demo/your-id-here/embedded?locale=en&modality=voice"
  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 Q&A agent

Add the agent iframe. It renders as a launcher your visitors can open.

<iframe
  src="https://handhold.io/demo/your-id-here/tour?locale=en&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 launcher at runtime, so the launcher 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 Q&A 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).

Draggable. Visitors can drag the launcher to a different side. Their chosen side persists in the browser across page reloads.

Next steps

• Open Onboarding agents at the right moment with programmatic triggers
• Pass customer data and control agents from code with the API reference
• Serve visitors in their own language (see supported languages)
• Feed agent activity into your analytics with tracking events
• Integrating from React or Vue? See the framework examples