recall_ai

# Recall.ai

Records video meetings (Zoom, Google Meet, Teams, Webex, GoToMeeting), generates
speaker-attributed transcripts, and produces downloadable audio/video files.

## Status Reference

**Bot lifecycle status** (from `get_bot`):
| Status | Meaning |
|--------|---------|
| `pending` | Bot created, not yet attempting to join |
| `joining` | Bot is connecting to the meeting |
| `joined` | Bot is in the meeting, recording NOT started |
| `recording` | Bot is actively recording |
| `stopped` | Recording stopped, processing in progress |
| `done` | Bot left and all processing complete |

**Artifact status** (`media_shortcuts.*.status.code`):
| Status | Meaning |
|--------|---------|
| `waiting` | Not started |
| `processing` | Being generated |
| `done` | Ready to retrieve |
| `failed` | Generation failed — retry or contact support |
| `deleted` | Artifact was removed |

---

## CRITICAL: Async Lifecycle

Creating a bot does NOT start recording. The full sequence is async:

```
create_bot → [wait: pending→joining→joined] → start_recording → [meeting runs] → leave_call/stop_recording → [wait: processing] → get_transcript → download_transcript
```

**Do NOT call `get_transcript` immediately after `create_bot`.** You will get an error or empty data. Always poll first.

**Polling intervals:**

- While status is `pending` or `joining`: every 10–15 seconds (max 2 minutes — if longer, the meeting URL may be invalid or the meeting hasn't started)
- While status is `recording`: every 30 seconds
- After `stop_recording` or `leave_call`, while transcript is `processing`: every 15 seconds

---

## Recipe A: Record a meeting and get the transcript

```bash
# 1. Create the bot (schedule 10+ minutes ahead for reliability)
earl call --yes --json recall_ai.create_bot \
  --meeting_url "https://zoom.us/j/123456789" \
  --bot_name "Notetaker" \
  --join_at "2026-02-23T15:00:00Z"
# → SAVE the returned id as bot_id

# 2. Poll until the bot has joined (repeat every 10–15s)
earl call --yes --json recall_ai.get_bot --bot_id <bot_id>
# → Wait until status == "joined"

# 3. Start recording
earl call --yes --json recall_ai.start_recording --bot_id <bot_id>

# 4. (Meeting runs — poll every 30s if you need to monitor)
earl call --yes --json recall_ai.get_bot --bot_id <bot_id>

# 5. When the meeting ends, leave the call
earl call --yes --json recall_ai.leave_call --bot_id <bot_id>

# 6. Poll until transcript is ready (repeat every 15s)
earl call --yes --json recall_ai.get_bot --bot_id <bot_id>
# → Wait until media_shortcuts.transcript.status.code == "done"
# → Read media_shortcuts.transcript.id from the response

# 7. Get transcript metadata (includes download URL)
earl call --yes --json recall_ai.get_transcript --transcript_id <transcript_id>
# → Read data.download_url from the response

# 8. Download full transcript text
earl call --yes --json recall_ai.download_transcript --url "<data.download_url>"
# → Returns speaker-attributed transcript text — summarize, extract action items, etc.
```

---

## Recipe B: Retrieve a video or audio recording

```bash
# 1. Get bot to find media IDs and confirm artifacts are ready
earl call --yes --json recall_ai.get_bot --bot_id <bot_id>
# → Read media_shortcuts.video_mixed.id and media_shortcuts.audio_mixed.id
# → If media_shortcuts.video_mixed.status.code != "done", poll every 15s until it is

# 2. Get video download URL
earl call --yes --json recall_ai.get_video --video_id <video_mixed_id>
# → Returns data.download_url — share this link with the user (expires in ~5 hours)

# 3. Get audio download URL
earl call --yes --json recall_ai.get_audio --audio_id <audio_mixed_id>
# → Returns data.download_url — share this link with the user (expires in ~5 hours)
```

**Important:** Do not attempt to download or process binary video/audio content.
Present the download URL to the user as a clickable link.

---

## Recipe C: Control a live meeting

```bash
# Stop recording early (bot stays in meeting; triggers transcript processing)
earl call --yes --json recall_ai.stop_recording --bot_id <bot_id>
# → After stopping, poll get_bot until media_shortcuts.transcript.status.code == "done"

# Pause recording during a sensitive segment
earl call --yes --json recall_ai.pause_recording --bot_id <bot_id>

# Resume when ready
earl call --yes --json recall_ai.resume_recording --bot_id <bot_id>

# Send a message to meeting participants
earl call --yes --json recall_ai.send_chat_message \
  --bot_id <bot_id> \
  --message "Action items so far: 1) Alice to send report 2) Bob to schedule follow-up"
```

**`stop_recording` vs `leave_call`:** `stop_recording` stops capturing but keeps the bot present. `leave_call` removes the bot from the meeting entirely. Both trigger transcript processing.

---

## Finding a lost bot_id

If you don't have the bot_id, use `list_bots` to find it:

```bash
# List all bots
earl call --yes --json recall_ai.list_bots

# List only future scheduled bots
earl call --yes --json recall_ai.list_bots --join_at_after "2026-02-23T00:00:00Z"
```

Sort the results by `join_at` or `created_at` to find the most recent bot.
Never create a duplicate bot for a meeting — check the list first.

---

## Scheduling constraint

For reliable joins, `join_at` must be at least **10 minutes in the future**.
Ad-hoc bots (no `join_at`) join immediately from a warm pool but may fail with
507 errors during peak usage. For production workflows, always schedule ahead.

**Earl limitation:** The `create_bot` template always sends `join_at` in the request
body. When omitted, it sends `"join_at": ""`. If the recall.ai API rejects this,
always provide `--join_at` with a valid ISO 8601 timestamp. Similarly, `list_bots`
always sends `join_at_after` in the query — provide a value or expect a possible 400
if the API validates the empty string.

---

## Download URL expiry

`data.download_url` values are pre-signed AWS S3 URLs that expire in approximately
**5 hours**. Retrieve and process transcript/media in the same session. Do not save
the URL for later use.