Skip to main content
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.
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:):
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: 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:
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):
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.