- Live-streamed bot audio — transcripts and patterns update during the call instead of only after Recall finishes processing the recording.
- 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.
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.
config.yml, under recall:):
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 underrecall: 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:
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:- Connect flow (
api/crates/api/src/routes/calendar/calendar_routes.rs,calendar_oauth_callback_routes.rs):GET /api/calendar/google/startsigns an HMAC-SHA256 state param (util/oauth_state.rs, 10-minute TTL) and returns Google’s OAuth consent URL. Google redirects back toGET /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 storecalendar_accounts.recall_calendar_idplus bookkeeping (email, status). Re-authorising aneeds_reauthaccount PATCHes the same Recall calendar with a fresh refresh token rather than creating a duplicate. - Events live in Recall, not in our database. There is no
calendar_eventstable. The dashboard and Settings list upcoming events withGET /api/v2/calendar-events/?calendar_id=…&is_deleted=false&start_time__gte=now&start_time__lte=now+28d. Title comes fromraw.summary(Google) orraw.subject(Outlook). Meetings without ameeting_urlare omitted from the dashboard widget (the bot cannot join them). - 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_foris the start time. - Sync → Add/Remove Bot (
calendar_webhook_handlers.rs): Recall postscalendar.sync_eventswhen events change. We re-fetch the changed events and resolve auto-join (per-event override incalendar_auto_join_rules, else the calendar-wide default whererecall_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_atis the eventstart_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. Parsebots[].bot_id(notid). - 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.
- Auto-join on + meeting URL + not ended → always
calendar.update: retrieve the Recall calendar; if status isdisconnected, mark the local accountneeds_reauth.- Immediate apply:
PUT /api/calendar/accounts/:id/auto-joinsaves the rule then callsapply_auto_join_now(one event, or every upcoming event without an override when the calendar-wide default changes). - Frontend: Settings → Integrations (
ui/src/lib/components/settings/CalendarIntegrationsSection.svelte, sidebar itemsettings.tab_integrations) and the dashboard Upcoming meetings widget (ui/src/lib/components/dashboard/MeetingsWidget.svelte) fed byGET /api/calendar/meetings. Row click opens/sessions/{id}only when a bot (and therefore a session) already exists.
config.yml, new top-level google_calendar: block — omit entirely to keep the feature off):
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 schedulescalendar.update— calendar disconnected / needs re-auth
- OAuth consent screen scopes:
.../auth/calendar.events.readonlyand.../auth/userinfo.email(both requested bybuild_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’sconfig.ymlsets), 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_reauthweekly until the app is published.
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_idis 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 arebots[].bot_id(serde also acceptsidas an alias).calendar_accountsstores no OAuth tokens — Recall holds those. If a token needs revoking, that happens on Recall’s side; disconnect here is a best-effortDELETE /calendars/:id/to Recall plus a local row delete (disconnect_calendar_account_impl).- Add Bot can return 507 (capacity) or 409;
recall_calendar.rsretries those with backoff. - Do not add a local
calendar_eventstable. 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’srender_pr_configderivesconfig.staging.pr{N}.ymlstraight fromconfig.staging.yml, database URL included — seeapi/crates/cli/src/main.rs). An uncommitted migration applied against staging leaves aseaql_migrationsrow 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(seem20260317_000001_replace_audit_logs_with_audit_trail.rs, queryable viaaudit_trail/dba.v_performance_metrics).calendar_accounts,calendar_auto_join_rules, andrecall_bot_sessionsare 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.