Agent Quickstarts

# MeetStream Agent Guide
You are building on MeetStream, an API that sends bots into Zoom, Google Meet, and
Microsoft Teams meetings to record, transcribe, stream, and speak. Follow this guide
exactly. When it conflicts with your prior knowledge of meeting-bot APIs, the guide wins.
When you need a detail that is not here, fetch the docs as Markdown (section 9) or use
the docs-search MCP. Do not guess endpoints or field names.
## 1. Glossary and environment
- human: the person you are working with. Only they can do the steps in section 2.
- agent: you.
- bot: one MeetStream participant in one meeting, identified by `bot_id`.
- MEETSTREAM_API_KEY: REST API key. Read it from the environment. Never log, print,
  commit, or hardcode it.
- PUBLIC_BASE_URL: public HTTPS origin that reaches this app, with no trailing slash.
  In development it is the tunnel URL (ngrok or cloudflared). MeetStream cannot
  reach localhost.
- WEBHOOK_PATH_TOKEN: a long random string you generate and put in the webhook path.
  Per-bot `callback_url` deliveries are not signed, so the unguessable path is what
  keeps strangers from posting fake events.
- MEETSTREAM_WEBHOOK_SECRET (optional): signing secret of a workspace webhook endpoint
  created in the dashboard. Only workspace endpoints are signed.
- callback_url: per-bot URL for lifecycle and post-call webhooks.
- live_transcription_required.webhook_url: per-bot URL for live transcript chunks.
- transcript_id: the key for post-call transcripts. It is not the bot_id, and it is
  never in a webhook.
At startup, fail fast with a clear message if MEETSTREAM_API_KEY or PUBLIC_BASE_URL is
missing, or if PUBLIC_BASE_URL does not start with https://.
## 2. Human-required setup (stop and ask; do not work around these)
The human does these. You check the result.
1. API key: create one at https://app.meetstream.ai/api-key and export it as
   MEETSTREAM_API_KEY. You check: `GET /bots` returns 200 (401 = header missing,
   403 = key rejected).
2. Transcription provider keys: for deepgram, assemblyai, sarvam, or jigsawstack
   (including their streaming variants), add that provider's key in the dashboard at
   https://app.meetstream.ai/integrations. `meetstream_streaming` and `meeting_captions`
   need no external key. You check: a create_bot 400 that names the provider means
   its key is missing. Report it to the human; do not switch providers silently.
3. Public HTTPS URL: webhooks require HTTPS. The human runs `ngrok http <port>` or
   `cloudflared tunnel --url http://localhost:<port>` and gives you the URL as
   PUBLIC_BASE_URL. A reserved or static domain avoids re-creating bots after every
   tunnel restart. You check: a health route you add (for example
   `curl -X POST $PUBLIC_BASE_URL/healthz`) answers from outside the machine.
4. Zoom only: a Zoom Marketplace General App with Meeting SDK enabled, with its Client
   ID and Secret saved in the dashboard Integrations page. Guide:
   https://docs.meetstream.ai/guides/app-integrations/zoom-marketplace-app-setup.md
   Google Meet and Teams need no setup.
5. A live test meeting: the human opens a real meeting, gives you the link, and admits
   the bot from the lobby when it knocks.
The agent does everything else: code, payloads, webhook server, storage, UI, tests.
## 3. Hard rules
- Base URL: `https://api.meetstream.ai/api/v1`.
- REST auth header: `Authorization: Token <key>`. The word is Token, NOT Bearer.
  The MCP server at mcp.meetstream.ai is the exception: it uses `Bearer`.
- Create: `POST /bots/create_bot`. Required: `meeting_link` (NOT `meeting_url`) and
  `bot_name`. Success is 201 with `bot_id`.
- Send an `Idempotency-Key` header on every create. Generate it ONCE, outside the retry
  loop, and reuse it on every attempt. A replay returns 507 with the original bot:
  507 is success, never retry it and never treat it as an error.
- 202 means "accepted, not ready yet". It is in the 2xx range but it is not data.
  Poll with a fixed cap (interval and max attempts). Never loop forever.
- Retry 429 (honor Retry-After), 500, and 503 with exponential backoff. Never retry
  400, 401, 403, or 404: fix the request. 400 is never transient; log its `message`.
- `video_required` defaults to true. Set `"video_required": false` for transcript-only
  bots.
- `automatic_leave.in_call_recording_timeout` has a 600 second floor. Below 600 is a
  400. Only set automatic_leave fields you need, since out-of-range values are 400s.
- One transcription provider per request under `recording_config.transcript.provider`.
- MIA voice agents: pass `agent_config_id` and nothing else agent-related. Do NOT send
  `socket_connection_url` or `live_audio_required` with it. Those are for bring-your-own
  bridges, and adding them is the usual cause of an agent that joins but never speaks.
- `GET /bots/{bot_id}/remove_bot` makes a bot leave (it is a GET). Data is kept.
  `DELETE /bots/{bot_id}/delete` destroys data and is irreversible: never call it
  without the human's explicit confirmation.
- Media and transcript download URLs are presigned and expire (about 1 hour). Store
  `bot_id` and `transcript_id`, never the URLs. Re-fetch a URL when you need it.
- Webhooks are delivered once and NOT retried. Return 2xx immediately, then process
  asynchronously. A slow or failing handler loses events.
- Echo your own IDs through `custom_attributes` on create. They are echoed back on
  lifecycle webhooks and live transcript chunks (not on `data_deletion`), which is
  how you route events to your own records.
## 4. API client with retries (TypeScript)
Use the official SDK (`@meetstream/sdk`, `meetstream-sdk` for Python) when the project
allows dependencies. Otherwise use this helper for every call.
```ts
const BASE_URL = 'https://api.meetstream.ai/api/v1';
const RETRYABLE = new Set([429, 500, 503]);
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const backoff = (n: number) => Math.min(30_000, 1_000 * 2 ** n) + Math.random() * 250;
export class MeetStreamError extends Error {
  constructor(public status: number, public body: string) {
    super(`MeetStream ${status}: ${body}`);
  }
}
// Returns { status, data }. 201/200 = done, 202 = not ready (caller polls with a cap),
// 507 = idempotent replay of an earlier create (success, same bot).
export async function meetstream<T = any>(
  path: string,
  init: RequestInit & { headers?: Record<string, string> } = {},
  maxRetries = 4,
): Promise<{ status: number; data: T }> {
  for (let attempt = 0; ; attempt++) {
    let res: Response;
    try {
      res = await fetch(`${BASE_URL}${path}`, {
        ...init,
        headers: {
          Authorization: `Token ${process.env.MEETSTREAM_API_KEY}`,
          'Content-Type': 'application/json',
          ...init.headers,
        },
      });
    } catch (err) {
      // Network failure. Safe to retry a create only because it carries an Idempotency-Key.
      if (attempt >= maxRetries) throw err;
      await sleep(backoff(attempt));
      continue;
    }
    const text = await res.text();
    let data: any = null;
    try { data = text ? JSON.parse(text) : null; } catch { data = text; }
    if (res.ok || res.status === 507) return { status: res.status, data };
    if (!RETRYABLE.has(res.status) || attempt >= maxRetries) {
      throw new MeetStreamError(res.status, text); // 400/401/403/404: fix, don't retry
    }
    const retryAfter = Number(res.headers.get('retry-after'));
    await sleep(res.status === 429 && retryAfter > 0 ? retryAfter * 1000 : backoff(attempt));
  }
}
```
Creating a bot:
```ts
import { randomUUID } from 'node:crypto';
const idempotencyKey = randomUUID(); // once, outside any retry loop
const { status, data } = await meetstream('/bots/create_bot', {
  method: 'POST',
  headers: { 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify(payload),
});
// status is 201 (created) or 507 (replayed the same bot). Both are success.
const botId: string = data.bot_id;
```
## 5. Create-bot payloads
Post-call transcript (notetaker):
```json
{
  "meeting_link": "https://meet.google.com/abc-defg-hij",
  "bot_name": "Notetaker",
  "video_required": false,
  "callback_url": "https://PUBLIC_BASE_URL/webhooks/meetstream/WEBHOOK_PATH_TOKEN",
  "custom_attributes": { "meeting_id": "your-internal-id" },
  "recording_config": {
    "transcript": { "provider": { "deepgram": { "model": "nova-3", "language": "en" } } }
  }
}
```
Other post-call providers: `assemblyai`, `sarvam`, `jigsawstack`, `meetstream`. Read the
provider page before changing its config block.
Real-time transcript (streaming):
```json
{
  "meeting_link": "https://meet.google.com/abc-defg-hij",
  "bot_name": "Live Captions",
  "video_required": false,
  "callback_url": "https://PUBLIC_BASE_URL/webhooks/meetstream/WEBHOOK_PATH_TOKEN",
  "live_transcription_required": {
    "webhook_url": "https://PUBLIC_BASE_URL/webhooks/meetstream-live/WEBHOOK_PATH_TOKEN"
  },
  "recording_config": {
    "transcript": { "provider": { "meetstream_streaming": {} } }
  }
}
```
Other streaming providers: `deepgram_streaming`, `assemblyai_streaming`,
`jigsawstack_streaming`, `meeting_captions`. Setting `live_transcription_required`
without a streaming provider is a 400.
Optional on any bot: `join_at` (ISO 8601) to schedule ahead,
`recording_config.retention` as `{ "type": "timed", "hours": N }` (default 720 hours).
## 6. Webhooks
The verified model (checked against 4,139 production deliveries). Trust it over
older examples.
Envelope
- Every delivery has `event`. Most also have `bot_event`, which equals `event` on every
  event EXCEPT terminals. Some deliveries have no `bot_event` (manifest.completed,
  manifest.skipped, bot.transcriptionready, bot.uploading, participant_events.*), so
  read `bot_event ?? event` for the specific name.
- Every delivery has an ISO 8601 `timestamp`.
- Dedupe on `{bot_id, bot_event ?? event, timestamp}`.
- `participant_events.*` are nested: the bot id is at `data.bot.id`, and there is no
  top-level bot_id, bot_status, or bot_event.
- `transcript_id` is never in a webhook. `data_deletion` has no custom_attributes.
Terminals (two layers)
- Every ending arrives exactly once with `event: "bot.stopped"`. `bot_event` is the reason:
  | bot_event      | status_code | bot_status              | meaning                              |
  |----------------|-------------|-------------------------|--------------------------------------|
  | bot.stopped    | 200         | Stopped                 | clean exit (meeting ended, removed, timeout) |
  | bot.kicked     | 200         | Stopped                 | a participant removed the bot        |
  | bot.notallowed | 500         | NotAllowed              | never admitted (lobby timeout)       |
  | bot.denied     | 500         | Denied                  | host refused entry or recording      |
  | bot.failed     | usually 500 | FAILED / ERROR / Failed | crashed                              |
- No delivery ever has `event: "bot.kicked"` (or notallowed, denied, failed). Those
  names only appear in `bot_event`.
- `status_code` is not always 200 on bot.stopped. Branch on `bot_event`, not
  `bot_status` (a kick and a clean exit both say "Stopped", and failure casing varies).
  If `bot_event` is missing, map `bot_status` case-insensitively: notallowed ->
  bot.notallowed, denied -> bot.denied, error or failed -> bot.failed, else bot.stopped.
- `bot.error` is NOT terminal (a streaming provider hiccup); the bot keeps running.
Typical order
bot.scheduled (if join_at) -> bot.joining -> bot.in_waiting_room -> bot.inmeeting ->
bot.recording -> participant_events.* -> bot.leaving -> bot.stopped ->
audio.processed / manifest.completed (either order) -> [post-call providers only:
transcription.processed or transcription.failed, then bot.transcriptionready] ->
video.processed (if video) -> bot.done -> data_deletion (after delete or retention expiry).
Never admitted: bot.joining -> bot.in_waiting_room -> bot.leaving -> bot.stopped
(bot_event bot.notallowed) -> bot.done.
Also possible: audio.skipped, manifest.skipped, transcription.skipped, bot.uploading.
bot.done is the final event on EVERY path, including streaming-only bots and bots
that never got in. Use it as the single "session finished" signal. Never treat
audio.processed as final.
Handler (Express):
```ts
import express from 'express';
const app = express();
type StopReason = 'bot.stopped' | 'bot.kicked' | 'bot.notallowed' | 'bot.denied' | 'bot.failed';
export function stopReason(p: any): StopReason {
  if (p.bot_event) return p.bot_event;
  const s = String(p.bot_status ?? '').toLowerCase();
  if (s === 'notallowed') return 'bot.notallowed';
  if (s === 'denied') return 'bot.denied';
  if (s === 'error' || s === 'failed') return 'bot.failed';
  return 'bot.stopped';
}
const seen = new Set<string>(); // use your database or Redis in production
app.post('/webhooks/meetstream/:token', express.raw({ type: '*/*' }), (req, res) => {
  if (req.params.token !== process.env.WEBHOOK_PATH_TOKEN) return res.sendStatus(404);
  // Workspace endpoints only: verify X-MeetStream-Signature over the raw bytes here.
  res.sendStatus(200); // ack first: deliveries are not retried
  let p: any;
  try { p = JSON.parse(req.body.toString('utf8')); } catch { return; }
  const botId: string | undefined = p.bot_id ?? p.data?.bot?.id;
  const key = `${botId}|${p.bot_event ?? p.event}|${p.timestamp}`;
  if (!botId || seen.has(key)) return;
  seen.add(key);
  setImmediate(() => handle(p, botId).catch((e) => console.error('webhook', e)));
});
async function handle(p: any, botId: string) {
  switch (p.event) {
    case 'bot.stopped':             return onEnded(botId, stopReason(p), p.message);
    case 'transcription.processed': return onTranscriptReady(botId);
    case 'transcription.failed':    return onTranscriptFailed(botId, p.message);
    case 'bot.done':                return onSessionFinished(botId); // always last
    default:                        return recordEvent(botId, p.bot_event ?? p.event, p.timestamp);
  }
}
```
## 7. Transcription
Post-call flow (deepgram, assemblyai, sarvam, jigsawstack, meetstream):
1. Create the bot with `recording_config.transcript.provider` set to a post-call provider.
2. Wait for the `transcription.processed` webhook. (`transcription.failed` means the
   run failed: surface `message`, then offer a re-run with `POST /bots/{bot_id}/transcribe`.)
3. `GET /bots/{bot_id}/detail` and read `bot_details.transcript_id`. Fallback:
   `GET /bots/{bot_id}/transcriptions` lists every run with its `transcript_id` and status.
4. `GET /transcript/{transcript_id}/get_transcript` returns an array of segments:
   `{ speaker, transcript, start_time, end_time, words[] }`. The text field is
   `transcript`, NOT `text`. Add `?raw=true` for the provider's raw output.
```ts
export async function fetchTranscript(botId: string, attempts = 20, intervalMs = 15_000) {
  const { data: detail } = await meetstream(`/bots/${botId}/detail`);
  let transcriptId: string | undefined = detail?.bot_details?.transcript_id;
  if (!transcriptId) {
    const { data } = await meetstream(`/bots/${botId}/transcriptions`);
    transcriptId = data?.transcriptions?.find((t: any) => t.status === 'Success')?.transcript_id;
  }
  if (!transcriptId) throw new Error(`No post-call transcript for ${botId}`);
  for (let i = 0; i < attempts; i++) {
    const { status, data } = await meetstream(`/transcript/${transcriptId}/get_transcript`);
    if (status === 200) return data as { speaker: string; transcript: string; start_time: number; end_time: number }[];
    await sleep(intervalMs); // 202: still processing
  }
  throw new Error(`Transcript ${transcriptId} still not ready after ${attempts} polls`);
}
```
Four ways to get a finished transcript, pick by where you are:
| From | Call | Use when |
|------|------|----------|
| The MCP server | `get_transcript` with `bot_id` (optional `wait`) | Prototyping or debugging in chat. It resolves transcript_id for you |
| A bot id (REST) | `/bots/{bot_id}/detail` -> `bot_details.transcript_id` -> `/transcript/{id}/get_transcript` | The default in app code (fetchTranscript above) |
| All runs of a bot | `/bots/{bot_id}/transcriptions` | After a re-transcribe, to pick or compare runs |
| Native captions | `bot_details.caption_file` on `/detail` | The bot used `meeting_captions` |
Render segments for people (and for LLM prompts) with one helper, not ad hoc joins:
```ts
type Segment = { speaker?: string; transcript?: string; start_time?: number };
const mmss = (s = 0) =>
  `${String(Math.floor(s / 60)).padStart(2, '0')}:${String(Math.floor(s % 60)).padStart(2, '0')}`;
// Merges consecutive segments from the same speaker into one turn.
export function toReadable(segments: Segment[]): string {
  const turns: { speaker: string; start: number; text: string[] }[] = [];
  for (const s of segments) {
    const speaker = s.speaker || 'Unknown speaker';
    const text = (s.transcript ?? '').trim();
    if (!text) continue;
    const last = turns[turns.length - 1];
    if (last && last.speaker === speaker) last.text.push(text);
    else turns.push({ speaker, start: s.start_time ?? 0, text: [text] });
  }
  return turns.map((t) => `[${mmss(t.start)}] ${t.speaker}: ${t.text.join(' ')}`).join('\n');
}
```
Real-time flow (meetstream_streaming, deepgram_streaming, assemblyai_streaming,
jigsawstack_streaming, meeting_captions):
1. Set a streaming provider AND `live_transcription_required: { webhook_url }`.
2. Chunks POST to that URL during the meeting. Fields: `bot_id`, `speakerName`,
   `timestamp`, `transcript` (current buffer, may be partial), `words[]` (word, start,
   end, confidence, speaker, punctuated_word), `is_final` (false = interim, will be
   replaced; true = committed), `end_of_turn`, `transcription_mode` (observed "raw" for
   meetstream_streaming), `custom_attributes`. Some providers also send `word_is_final`
   per word; treat it as optional and decide on the top-level `is_final`.
3. Ack 2xx immediately, same as lifecycle webhooks.
```ts
type LiveChunk = {
  bot_id: string;
  speakerName?: string;
  transcript: string;      // the speaker's current buffer; interim chunks get replaced
  is_final: boolean;       // true = committed text
  end_of_turn?: boolean;
  timestamp: string;
  words?: { word: string; start: number; end: number; speaker?: string; punctuated_word?: string }[];
  custom_attributes?: Record<string, string>;
};
// One interim line per speaker, replaced until it is committed.
const interim = new Map<string, string>(); // key: bot_id|speaker
export function onLiveChunk(c: LiveChunk, commit: (botId: string, speaker: string, text: string) => void) {
  const speaker = c.speakerName ?? 'Unknown speaker';
  const key = `${c.bot_id}|${speaker}`;
  if (c.is_final) {
    interim.delete(key);
    if (c.transcript.trim()) commit(c.bot_id, speaker, c.transcript.trim());
  } else {
    interim.set(key, c.transcript); // render as a grey, replaceable line
  }
}
```
4. Streaming-only bots produce NO post-call transcript: no transcription.processed, and
   get_transcript returns 202 forever. They still get bot.done. If you need a post-call
   transcript too, call `POST /bots/{bot_id}/transcribe` after bot.done with a post-call
   provider in the body; the response carries the new `transcript_id`.
## 8. Verify before you say done
Run every check that applies, and report each result with evidence (status codes,
event names, IDs). If a check needs the human (admitting the bot, speaking), ask them.
- [ ] No API key in source, logs, or git history. Search the repo for the key's value;
      only placeholders such as YOUR_API_KEY may appear.
- [ ] Every REST call sends `Authorization: Token`, and `GET /bots` returns 200.
- [ ] Every create sends `meeting_link` and `bot_name` and an Idempotency-Key made
      once. Replaying the same key returns 507 and your code treats it as success.
- [ ] A 400 is surfaced with its `message` and not retried.
- [ ] PUBLIC_BASE_URL is HTTPS and reachable from outside, and the webhook path
      without the right token returns 404.
- [ ] The webhook route returns 2xx before any slow work, and the same payload sent
      twice is processed once.
- [ ] A real bot ran end to end, and you logged: bot.joining -> bot.inmeeting ->
      bot.stopped (with its bot_event) -> bot.done.
- [ ] A kick (remove the bot from the meeting UI) is recorded as bot.kicked, and a lobby
      timeout as bot.notallowed. Neither is recorded as a clean stop.
- [ ] Post-call: the transcript was fetched via transcript_id, segments render from
      `transcript`, and polling stops after its cap.
- [ ] Real-time: interim chunks are replaced, not appended, and `is_final` chunks commit.
- [ ] Nothing stores a presigned URL.
- [ ] No test bot was left running (`GET /bots/{bot_id}/status`), and no data was deleted
      without the human's confirmation.
## 9. Docs to fetch as Markdown
- Index: https://docs.meetstream.ai/llms.txt
- OpenAPI: https://docs.meetstream.ai/openapi.json
- Webhooks: https://docs.meetstream.ai/guides/webhooks/webhooks-and-events.md
- Local webhooks: https://docs.meetstream.ai/guides/webhooks/local-webhook-server.md
- Signatures: https://docs.meetstream.ai/guides/webhooks/webhook-signature-verification.md
- Post-call: https://docs.meetstream.ai/guides/transcription-recordings/post-call-transcription.md
- Live: https://docs.meetstream.ai/guides/transcription-recordings/live-transcription.md
- Providers: https://docs.meetstream.ai/guides/transcription-recordings/providers/transcription-providers.md
- Errors: https://docs.meetstream.ai/errors.md
- Debugging: https://docs.meetstream.ai/guides/help/debugging-bots.md