Tracking events
Subscribe to SDK events (session starts, user messages, captured fields, and action clicks) for your analytics.
The SDK emits events you can subscribe to for analytics. You need the embed.js script from the quick start on the page.
window.handhold only exists once embed.js has executed, so attach listeners from the script's load event (or any code that is guaranteed to run after it):
<script
async
src="https://handhold.io/demo/embed.js"
onload="window.handhold.addEventListener('onusermessage', (data) => console.log(data))"
></script>Unsubscribe with window.handhold.removeEventListener('onusermessage', handler). Attaching from React or Vue components is shown in the framework examples.
Events
| Event name | Description | Payload |
|---|---|---|
onusermessage | User sends a message via the input | { event, agentId, sessionId } |
onclose | User closes the demo overlay | { event, agentId, sessionId? } |
onfieldvalueset | A discovery field value is captured | { event, agentId, sessionId, field: { id, name, type }, value } |
onsessionstarted | A session starts | { event, agentId, sessionId, qualificationFieldPresets? } |
onsessionfinished | AI agent completes the session | { event, agentId, sessionId } |
onactionclick | User clicks one of the agent's calls to action, or a button the agent shows during the conversation | { event, agentId, sessionId?, actionId, label? } |
When a visitor has the same conversation open in several tabs, each event fires on one page only: the page where the visitor acted or, for onfieldvalueset and onsessionfinished, the page the visitor last used.
A click on a Contact support button fires onactionclick. Once your support chat opens, the session ends without onclose or onsessionfinished.
For AI agents: a clean Markdown version is available at /docs/events.md.