---
title: Tracking events
description: Subscribe to SDK events (session starts, user messages, captured fields, and action clicks) for your analytics.
slug: events
order: 4
---

The SDK emits events you can subscribe to for analytics. You need the `embed.js` script from the [quick start](/docs) 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):

```html
<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](/docs/frameworks).

## 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 }` |
| `onnudgeaction`     | User clicks a nudge action                                     | `{ event, agentId, sessionId?, actionId, label? }`                |
| `onsessionstarted`  | A session starts                                               | `{ event, agentId, sessionId, qualificationFieldPresets? }`       |
| `onsessionfinished` | AI agent completes the session                                 | `{ event, agentId, sessionId }`                                   |
| `onactionclick`     | User clicks an action button (e.g. CTA on the finished screen) | `{ event, agentId, sessionId, actionId, label }`                  |