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

# Meeting bot: live audio & calendar auto-join

> Recall.ai meeting bot with live-streamed audio and Google Calendar auto-join.

Two additions to the existing Recall meeting-bot integration:

1. **Live-streamed bot audio** — transcripts and patterns update *during* the call instead of only after Recall finishes processing the recording.
2. **Google Calendar auto-join** — link a Google Calendar via Recall's Calendar V2 API and have the meeting bot join upcoming events automatically, without a human pasting a meeting link.

Both are off by default and require config before they do anything (see below).

***

## Feature 1: live-streamed bot audio

**Why:** Previously, a Recall bot only handed us audio once the meeting ended and Recall finished processing (`audio_mixed_mp3`). Moderators had no live transcript/pattern feed for bot-recorded sessions the way they do for browser/device recordings.

**How it works:** Recall bots can push raw mixed audio frames to a websocket URL we control, in near-real-time, if the bot is created with a `realtime_endpoints` config pointing at us. New bots receive a per-row stream token: `wss://{realtime_ws_base_url}/api/meeting-bot/stream/{row_id}/{token}` (hash stored in `recall_bot_sessions.stream_token_hash`). The legacy path `GET /api/recall/stream/:stream_id` remains for pre-cutover rows until Step 1b.

Recall connects with Svix-signed upgrade requests verified against `realtime_verification_secret`, with a one-release fallback to `webhook_secret` (logged at startup) when the dedicated secret is not yet configured. Incoming frames are base64-decoded PCM (`util/recall_stream.rs::decode_audio_frame`), buffered by `ChunkAssembler` into \~15s windows, WAV-encoded, then fed through `handle_chunked_upload`. `recall_bot_sessions.next_chunk_sequence` tracks position across websocket reconnects. Stream paths are redacted in audit events and request tracing; configure Traefik/nginx access logs to strip `/api/meeting-bot/stream/{row_id}/{token}` down to `{row_id}/[redacted]` (the API never logs the token).

**Cutover:** set `recall.stream_cutover_at` in the **same deploy** that enables tokenised stream URLs, then run the cutover job against pending calendar/manual bots so Recall's `realtime_endpoints` URL picks up the token path. Config validation refuses to start the API if `realtime_ws_base_url` is set without `stream_cutover_at`. Re-run safely if the job crashes (`token_migration_state = migrating`); the job takes a Postgres advisory lock and uses `FOR UPDATE SKIP LOCKED` per row.

```bash theme={null}
# From the api/ directory with CONFIG_PATH pointing at the environment config:
cargo run --bin kair-cli -- meeting-bot-stream-cutover --dry-run   # counts only (no tokens logged)
cargo run --bin kair-cli -- meeting-bot-stream-cutover             # applies migration
```

The job loads Postgres and Recall credentials from config, calls Recall's bot/calendar APIs, and persists stream token hashes in the database. It never logs stream tokens.

**Config (`config.yml`, under `recall:`):**

```yaml theme={null}
recall:
  api_key: ...
  webhook_secret: ...
  # New — unset disables Feature 1 entirely; bots still record via
  # audio_mixed_mp3 as before, just without the live feed.
  realtime_ws_base_url: "wss://kair.is"   # public wss:// this environment's bots can reach
  # Required for websocket upgrade verification (distinct from webhook_secret).
  # When unset, the API logs a startup warning and accepts recall.webhook_secret for
  # realtime upgrade verification until this is set.
  realtime_verification_secret: "whsec_..."
  # Required when recall is configured — hostnames only (port 443 implied). Copy the
  # host from a real Recall `download_url` in your workspace (US docs often show
  # recallai-production-bot-data.s3.amazonaws.com; EU may differ).
  allowed_download_hosts:
    - recallai-production-bot-data.s3.amazonaws.com
  # Set at deploy time when enabling tokenised stream URLs (see cutover above).
  stream_cutover_at: "2026-10-14T12:00:00Z"
```

**Startup validation:** when `realtime_ws_base_url` is set, `stream_cutover_at` must also be set — the API refuses to start otherwise.

**Infra requirement:** Traefik/nginx in front of the API must proxy the websocket upgrade through to `/api/meeting-bot/stream/:row_id/:token` (and legacy `/api/recall/stream/:stream_id` until cutover completes) on whatever host `realtime_ws_base_url` points at. No new port — same API container, same `/api` path prefix as everything else. For Traefik access logs, add a redaction rule or post-process paths so stream tokens never appear in edge logs.

### Config changes required in this deploy

Set these under `recall:` in each environment's `config.yml` (or generated PR preview config) when enabling tokenised stream URLs:

| Key | Production | Staging | PR previews |
| - | - | - | - |
| `allowed_download_hosts` | Hostnames from real Recall `download_url` values in that workspace | Set on the deploy host in `/configs/kair-voice/config.staging.yml` (EU buckets may differ — copy the host from a real `download_url`) | Copied from staging — API startup fails if missing or empty |
| `stream_cutover_at` | ISO-8601 instant in the **same deploy** that turns on tokenised URLs | Set when staging exercises stream cutover | Injected as `2020-01-01T00:00:00Z` when staging has `realtime_ws_base_url` but no cutover — set a real value on `/configs/kair-voice/config.staging.yml` for meaningful stream tests |
| `realtime_verification_secret` | Dedicated Svix secret for websocket upgrades | Staging secret (not production's) | Optional for preview startup — API falls back to `webhook_secret` with a warning |

**Pre-deploy duplicate check (every deploy):** before each deploy that runs API migrations or the stream cutover job, confirm no duplicate non-null `recall_bot_id` values exist:

```sql theme={null}
SELECT recall_bot_id, count(*) AS n
FROM recall_bot_sessions
WHERE recall_bot_id IS NOT NULL
GROUP BY recall_bot_id
HAVING count(*) > 1;
```

Resolve any rows returned before proceeding. Migration `m20261014_000001_meeting_bot_provider` refuses to run when duplicates are present; `kair-cli meeting-bot-stream-cutover --dry-run` (and the cutover job itself) run the same check up front with a clear error instead of crash-looping mid-deploy.

**Large databases:** migration `m20261014_000001_meeting_bot_provider` sets `lock_timeout = '5s'` and creates the `(provider, recall_bot_id)` unique index without `CONCURRENTLY`. On production tables with heavy write load, create the same index manually with `CREATE UNIQUE INDEX CONCURRENTLY …` before deploy, then run migrations (the migration becomes a no-op if the index already exists only when you align names — otherwise plan a maintenance window).

**Rollback note:** rolling back migration `m20261014_000001` after stream cutover removes `stream_token_hash` / provider columns and breaks authentication for bots already moved to the tokenised `/api/meeting-bot/stream/{row_id}/{token}` route. Only roll back before cutover completes, or re-run cutover after restoring the migration.

**Backstory for the next dev:** we don't have a confirmed sample of Recall's real-time audio payload shape from their docs at the time this was built — `decode_audio_frame` was written from the "audio\_mixed\_raw\.data" event description and is defensive/fail-soft (logs and drops malformed frames rather than crashing the stream). If live audio silently isn't arriving, check Recall's dashboard for what it's actually sending to the websocket and compare against `util/recall_stream.rs`.

***

## Feature 2: Google Calendar auto-join

**Why:** Instead of a human copying a meeting link into the Meeting Bot form every time, a workspace member connects their Google Calendar once and flags which meetings (or all meetings, by default) should get a bot automatically.

**How it works:**

1. **Connect flow** (`api/crates/api/src/routes/calendar/calendar_routes.rs`, `calendar_oauth_callback_routes.rs`): `GET /api/calendar/google/start` signs an HMAC-SHA256 state param (`util/oauth_state.rs`, 10-minute TTL) and returns Google's OAuth consent URL. Google redirects back to `GET /api/calendar/google/callback`, which verifies the state, exchanges the code for tokens (`util/google_oauth.rs`), fetches the user's email, and calls Recall's Create Calendar (v2) API (`util/recall_calendar.rs::create_calendar`) — Recall holds the OAuth refresh token and does the actual Google Calendar polling, not us. We only store `calendar_accounts.recall_calendar_id` plus bookkeeping (email, status). Re-authorising a `needs_reauth` account PATCHes the same Recall calendar with a fresh refresh token rather than creating a duplicate.
2. **Events live in Recall, not in our database.** There is no `calendar_events` table. The dashboard and Settings list upcoming events with `GET /api/v2/calendar-events/?calendar_id=…&is_deleted=false&start_time__gte=now&start_time__lte=now+28d`. Title comes from `raw.summary` (Google) or `raw.subject` (Outlook). Meetings without a `meeting_url` are omitted from the dashboard widget (the bot cannot join them).
3. **A Kair session is created only when a bot is scheduled.** Toggling auto-join off does not dump meetings onto the workspace timeline. Session lookup for the widget is `recall_bot_sessions.recall_calendar_event_id`. Session title is the calendar event title; `metadata.scheduled_for` is the start time.
4. **Sync → Add/Remove Bot** (`calendar_webhook_handlers.rs`): Recall posts `calendar.sync_events` when events change. We re-fetch the changed events and resolve auto-join (per-event override in `calendar_auto_join_rules`, else the calendar-wide default where `recall_calendar_event_id IS NULL`). Auto-join is **off by default**.
   * Auto-join **on** + meeting URL + not ended → always `POST /api/v2/calendar-events/{id}/bot/` (Recall requires a fresh Add Bot when start time or meeting URL changes). `join_at` is the event `start_time`. Dedup key is `{start_time}-{meeting_url}-{event.id}` — one bot per connected calendar / one Kair session. Reuse the existing session row if we already scheduled this event. Parse `bots[].bot_id` (not `id`).
   * Auto-join **off** + a bot already scheduled → `DELETE /api/v2/calendar-events/{id}/bot/` (404 is fine). The Kair session stays.
   * Deleted events are skipped; Recall unschedules those itself.
5. **`calendar.update`**: retrieve the Recall calendar; if status is `disconnected`, mark the local account `needs_reauth`.
6. **Immediate apply**: `PUT /api/calendar/accounts/:id/auto-join` saves the rule then calls `apply_auto_join_now` (one event, or every upcoming event without an override when the calendar-wide default changes).
7. **Frontend**: Settings → Integrations (`ui/src/lib/components/settings/CalendarIntegrationsSection.svelte`, sidebar item `settings.tab_integrations`) and the dashboard **Upcoming meetings** widget (`ui/src/lib/components/dashboard/MeetingsWidget.svelte`) fed by `GET /api/calendar/meetings`. Row click opens `/sessions/{id}` only when a bot (and therefore a session) already exists.

**Config (`config.yml`, new top-level `google_calendar:` block — omit entirely to keep the feature off):**

```yaml theme={null}
google_calendar:
  client_id: "..."
  client_secret: "..."
  # Must be on OUR domain, not Recall's, and match a redirect URI registered
  # on the Google Cloud OAuth client exactly (http:// allowed for local dev).
  redirect_uri: "https://kair.is/api/calendar/google/callback"
```

**Recall dashboard webhooks (required ops, not in git):** the workspace webhook (e.g. `https://braid-api.kair.is/api/webhooks/recall`) must subscribe to:

* **Bot status change events** (`bot.joining_call`, `bot.in_waiting_room`, `bot.in_call_not_recording`, `bot.in_call_recording`, `bot.call_ended`, `bot.done`, `bot.fatal`, …) — without these, the Tracks panel stays on **Joining** even though the bot is already in Meet and recording. Explorer → Events shows Recall's own timeline; it is **not** proof the webhook reached Kair. Prefer the dashboard's "View Webhooks" delivery log. As a safety net, live-sources / meeting-bot-status will reconcile from Retrieve Bot while the row is still Pending/Joined, and a connected realtime audio websocket also promotes the row to Recording.
* `audio_mixed.done` — recording finished (existing live-audio / finalisation path)
* `calendar.sync_events` — event changes; without this, auto-join never schedules
* `calendar.update` — calendar disconnected / needs re-auth

These are configured in the Recall dashboard for the workspace, not in this repo.

**Google Cloud setup (one-time, per OAuth client):**

* OAuth consent screen scopes: `.../auth/calendar.events.readonly` and `.../auth/userinfo.email` (both requested by `build_authorization_url`).
* Authorised redirect URIs: register `{redirect_uri}` for every environment sharing this client (production, staging, and — if used — each PR preview host), since Google validates the redirect URI in the auth request against its registered list. Only one value is ever *sent* per environment (whatever that environment's `config.yml` sets), so registering ones you don't currently use is harmless.
* While the OAuth app is in **Testing**, Google refresh tokens expire after **7 days**. Users will hit `needs_reauth` weekly until the app is published.

**Env vars:** none required beyond the config block above — `client_id`/`client_secret`/`redirect_uri` are config-file-only (like Recall's `api_key`), not read from the environment.

**Backstory / gotchas for the next dev:**

* Calendar V2 (app-managed scheduling) is a separate API version from the v1 Bot API, on the same region host (`https://{region}.recall.ai/api/v2`). Do not mix Calendar V1.
* `recall_bot_sessions.recall_bot_id` is nullable specifically for this flow: a calendar-scheduled bot is *requested* (session + row created) before Recall's response tells us the actual bot id, unlike the manual "paste a link" flow where Create Bot returns one synchronously. Don't assume it's always present. Add Bot returns the updated event; bots are `bots[].bot_id` (serde also accepts `id` as an alias).
* `calendar_accounts` stores no OAuth tokens — Recall holds those. If a token needs revoking, that happens on Recall's side; disconnect here is a best-effort `DELETE /calendars/:id/` to Recall plus a local row delete (`disconnect_calendar_account_impl`).
* Add Bot can return 507 (capacity) or 409; `recall_calendar.rs` retries those with backoff.
* **Do not add a local `calendar_events` table.** Listing from Recall keeps us on Recall event IDs (required for Add/Remove Bot) and avoids a migration. PR preview environments share the real staging database (`kair-cli`'s `render_pr_config` derives `config.staging.pr{N}.yml` straight from `config.staging.yml`, database URL included — see `api/crates/cli/src/main.rs`). An uncommitted migration applied against staging leaves a `seaql_migrations` row with no matching file, which blocks *every* PR's migrations until someone deletes that row by hand.
* Every application table gets a `create_full_audit_trigger`/`create_update_audit_trigger` (see `m20260317_000001_replace_audit_logs_with_audit_trail.rs`, queryable via `audit_trail`/`dba.v_performance_metrics`). `calendar_accounts`, `calendar_auto_join_rules`, and `recall_bot_sessions` are wired into full audit as of this migration — if you add another table here, wire it in too rather than letting it slip through unaudited.


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