> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Live Meeting Events

> Know what is happening in a call while it runs — screen shares, cameras, what is on the stage — as webhooks or a pollable log.

Until now the first thing your server heard about a meeting was `meeting.ended`.
Live meeting events tell you what happens **during** the call, within about a
second, so your systems can react — and so your agent can be told to.

Two ways to consume them, from the same source of truth:

* **Webhooks** — subscribe an endpoint to the event types below, exactly like
  `meeting.ended`. Same envelope, same signature, same retries. See [Webhooks](https://docs.waterr.ai/api-reference/webhooks.md).
* **The event log** — `GET /v1/meetings/{meeting_id}/events` returns everything
  recorded for a meeting, including the actions you pushed in through
  [Meeting Actions](https://docs.waterr.ai/api-reference/meeting-actions.md).

## Event types

| Event | Fires when | `data` |
| - | - | - |
| `meeting.started` | The first participant's client is ready to hear the agent. Once per meeting pipeline. | `pipeline`: `cascade` or `gemini_live` |
| `screen_share.started` | A participant starts sharing their screen into the call | `source: "screenVideo"`, `participant` |
| `screen_share.stopped` | They stop, or leave while sharing (`reason: "participant_left"`) | same |
| `camera.on` / `camera.off` | A participant's camera turns on / off (or they leave with it on) | `source: "camera"`, `participant` |
| `stage.opened` | A screen app was put on the stage — by the agent (`actor: "agent"`), by your server (`api_key:…`, `skill:…`) or a page (`stage_token:…`) | `app`, `placement`, `url`, `actor` |
| `stage.closed` | It was closed (`actor: "page"` when the page closed itself) | `app`, `actor` |
| `stage.interaction` | The participant did something on the presented page (`WaterrScreen.send(...)`) | `app`, `event`, `detail`, `context`, `placement`, `speak` |

`participant` is `{ "id": "<transport session id>", "name": "<display name>" }`.
It identifies the person *within this call*; it is not the `meeting_participants`
row that `participant.joined` carries, because screen and camera state belongs to
a connection, not to an invitation. Use `name` for display and `id` to correlate
events from the same connection.

**Not events (yet):** frames. Nothing here carries an image. A snapshot of the
shared screen or camera on demand is planned as an explicit, per-scenario opt-in.

## Webhook example

```json theme={null}
{
  "id": "evt_8f2c…",
  "event": "screen_share.started",
  "created_at": "2026-10-26T10:12:03.000Z",
  "data": {
    "meeting_id": "8c6e…",
    "scenario_id": "2f1a…",
    "event_id": "9c1f…",
    "source": "screenVideo",
    "participant": { "id": "7d3a…", "name": "Alex" }
  }
}
```

`event_id` is the row in the meeting's event log, so a webhook and a later
`GET …/events` can be matched one to one.

## The event log

```bash theme={null}
curl "https://api.waterr.ai/v1/meetings/{meeting_id}/events?types=screen_share.started,stage.interaction&limit=50" \
  -H "Authorization: Bearer wai_live_xxx"
```

```json theme={null}
{
  "data": [
    {
      "id": "9c1f…",
      "meeting_id": "8c6e…",
      "type": "stage.interaction",
      "actor": "page",
      "skill_id": null,
      "participant_id": null,
      "data": { "app": "plan_picker", "event": "plan_chosen", "detail": { "plan": "pro" }, "placement": "card", "speak": true },
      "created_at": "2026-10-26T10:12:03.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

| Query | Meaning |
| - | - |
| `types` | Comma-separated list to keep, e.g. `camera.on,camera.off,action.say`. Omit for everything. |
| `limit`, `cursor` | [Cursor pagination](https://docs.waterr.ai/api-reference/pagination.md): pages run newest-first and `next_cursor` walks back in time. Without them you get the newest 200 as `{ "data": [...] }`, oldest first, ready to replay. |

Rows of type `action.<type>` (`action.say`, `action.context`, `action.stage.open`, …)
are the [Meeting Actions](https://docs.waterr.ai/api-reference/meeting-actions.md) you or a skill pushed
in, with the action body in `data`. They are recorded but **not** delivered as
webhooks — you sent them.

Who may read: anyone who may read the meeting (the scenario's workspace). A
meeting outside your workspace answers `404`.

## What the agent hears

Every `screen_share.*` and `camera.*` transition also lands in the agent's
context as a one-line silent note ("Alex started sharing their screen."), so it
can respond to what it is now looking at without being told again. Stage events
reach it the way [screen apps](https://docs.waterr.ai/api-reference/screen-apps.md#what-the-agent-sees)
always have.

## Where it works

Studio meetings, the inline embed and the sidebar assistant: all events. Google
Meet, Zoom and Teams bot calls: `meeting.started` only for now — the bot sees the
room as a composite video, so it cannot tell whose camera or screen changed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.