Live Meeting Events

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.
The event log — GET /v1/meetings/{meeting_id}/events returns everything recorded for a meeting, including the actions you pushed in through Meeting Actions.

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

{
  "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

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

{
  "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: 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 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 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.

Getting Started

Meetings

Scenarios

Personas

Tools

Extend Meetings

Embed Scenario

More APIs

Guides

Integrations

Agent Skills

Live Meeting Events

Event types

Webhook example

The event log

What the agent hears

Where it works

​Event types

​Webhook example

​The event log

​What the agent hears

​Where it works

Event types

Webhook example

The event log

What the agent hears

Where it works