Meeting Bots on Butterbase

Guide for building features that spawn meeting bots via ctx.ai.meetings. Covers the four SDK methods, webhook handling, idempotency, and cost-aware design.

---

1. When to Use

Reach for this skill when your feature involves any of:

• Meeting notetaker — bot joins a recurring standup or sales call and stores a transcript.
• Sales call enricher — join a customer call, wait for bot.done, then run an LLM over the transcript to populate a CRM record.
• Interview pipeline — record and transcribe candidate interviews, then score against a rubric.
• Voice-of-customer transcripts — capture support or discovery calls; feed chunks into a RAG collection for future search.

If you need only audio/video file upload without a live meeting join, use manage_storage instead.

---

2. The Four SDK Methods

Method	What it does	One-line example
bb.ai.meetings.start(opts)	Spawns a bot and returns immediately with status: "joining"	const { data: bot } = await bb.ai.meetings.start({ meetingUrl, transcript: true })
bb.ai.meetings.get(id)	Fetches current status + artifact URLs	const { data } = await bb.ai.meetings.get(bot.id)
bb.ai.meetings.stop(id)	Removes the bot from the call early	await bb.ai.meetings.stop(bot.id)
bb.ai.meetings.list(opts)	Lists bots with optional status, limit, cursor filters	await bb.ai.meetings.list({ status: 'done', limit: 50 })

All methods return { data, error } — always check error before using data.

---

3. Typical Flow

1. Configure webhook — call manage_ai with action: "configure_meetings_webhook", passing forward_url pointing at a deployed Butterbase function or your own endpoint.
2. Start the bot — app calls bb.ai.meetings.start(...). Status begins as joining.
3. Bot joins — status progresses joining → waiting_room → in_call → recording. The bot.in_call_recording event fires.
4. Call ends — bot status moves to ended, then done once artifacts are processed.
5. Webhook fires bot.done — your handler receives the event. The bot's recordingUrl and transcriptUrl are now populated.
6. Fetch artifacts — download the recording or transcript using the URLs from bb.ai.meetings.get(id).
7. Write to substrate / database — store the transcript text, link to the relevant entity (deal, candidate, customer), or insert into a RAG collection.
8. Trigger downstream extract — run an LLM summarization, action-item extraction, or scoring job.

---

4. Webhook Handler Skeleton

Deploy this as a Butterbase function with trigger: { type: "http", config: { method: "POST", auth: "none" } }.

export async function handler(req: Request, ctx: any): Promise<Response> {
  const event = req.headers.get('x-bb-event');
  const body = await req.text();
  const payload = JSON.parse(body);

  const botId: string = payload.data?.bot_id ?? payload.data?.id;

  // Idempotency: skip if we already processed this bot + event combo.
  const claimed = await ctx.idempotency.claim(`meeting:${botId}:${event}`);
  if (!claimed) {
    return new Response('duplicate', { status: 200 });
  }

  switch (event) {
    case 'bot.done': {
      // Artifacts are ready — store a reference or kick off extraction.
      await ctx.db.query(
        `UPDATE meeting_jobs SET status = 'done', bot_id = $1 WHERE external_ref = $2`,
        [botId, payload.data?.metadata?.jobRef ?? botId]
      );
      break;
    }
    case 'transcript.done': {
      // Transcript artifact URL is now available. Kick off downstream processing.
      await ctx.db.query(
        `INSERT INTO transcript_queue (bot_id, created_at) VALUES ($1, now())`,
        [botId]
      );
      break;
    }
    case 'bot.fatal': {
      await ctx.db.query(
        `UPDATE meeting_jobs SET status = 'fatal' WHERE bot_id = $1`,
        [botId]
      );
      break;
    }
    default:
      // Other events (bot.in_call_recording, recording.done, transcript.failed) — handle as needed.
      break;
  }

  return new Response('ok', { status: 200 });
}

Key points:

• Use ctx.idempotency.claim(key) — the meetings service may retry for up to 24 hours.
• Verify x-bb-key-id matches the first 16 characters of your current webhook secret to detect stale post-rotation events.
• Return 200 even for events you don't handle — a non-2xx response triggers a retry.

---

5. Cost-Aware Design

Before dispatching a bot in a user-pays context, call estimateCost and surface the projected charge:

const { data: estimate } = await bb.ai.meetings.estimateCost({
  durationMinutes: 60,
  transcript: true,
});
// estimate.usd — show this to the user or check against a quota

Rates (v1):

Dimension	Rate
Recording (mp4 or audio_only)	$0.50/hr + markup, prorated per second
Transcription	$0.15/hr + markup, prorated per second

Both charges are applied against the app's AI credit balance once the bot reaches done.

For user-pays apps, hold a projected credit reservation at bot-start time and display a live cost counter using the bot's current duration (polled from bb.ai.meetings.get).

---

6. Vendor-Neutral Note

The underlying meetings infrastructure may change providers without notice. Do not depend on undocumented fields in the event payload or on provider-specific bot behavior.

---

7. What This Skill Does NOT Cover

• Real-time streaming transcripts — word-by-word transcript streaming during an active call is on the roadmap; not available in v1.
• Multi-region bot routing — all bots are spawned from US East in v1; per-region dispatch is on the roadmap.
• Browser-side recording — ctx.ai.meetings must be called from a serverless function or server-side code, not directly from the browser. Use a Butterbase function as a backend proxy.