snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-apps/public/call-recorder/SETUP.md

@@ -0,0 +1,108 @@
+# Call Recorder — Self-hosting setup
+
+This guide is for Twenty **server admins**. It covers connecting Call Recorder
+to the recording service (Recall.ai), the environment variables it reads, and
+how to wire up the webhook.
+
+If you're on **Twenty Cloud**, these credentials may already be configured —
+check with your workspace before setting them.
+
+## What you need to wire up
+
+Call Recorder talks to [Recall.ai](https://recall.ai) to send bots to meetings
+and to receive recordings back. Two things must be configured:
+
+1. A **Recall.ai API key** (and optionally a region), so the app can schedule,
+   update, and cancel bots.
+2. A **webhook** from Recall.ai back to your deployment, so the app learns when
+   a recording is ready and can ingest it.
+
+Transcription runs on Recall.ai's own provider by default, which needs no extra
+credentials. If a workspace switches `CALL_RECORDER_TRANSCRIPT_PROVIDER` to
+Gladia, add a **Gladia API key** in the Recall.ai dashboard
+(**Transcription → Gladia**) for every region in use, or transcripts for that
+workspace fail.
+
+## Server variables
+
+Set these on the application registration after installing
+(**Settings → Applications → Call Recorder**):
+
+| Server variable | Required | Purpose |
+|---|---|---|
+| `RECALL_API_KEY` | Yes | Recall.ai API key for the configured region; used to schedule, update, and cancel bots. |
+| `RECALL_REGION` | No | Recall.ai region for API requests. Defaults to `eu-central-1` (Europe / Frankfurt). |
+| `CALL_RECORDER_RECORDING_RETENTION_HOURS` | No | How long Recall.ai retains the source media after processing. Defaults to `166` hours (6 days 22 hours), just under Recall's 168-hour free-storage window. Values above `168` may incur Recall storage charges. Twenty's ingested copy is unaffected. |
+| `RECALL_WEBHOOK_SECRET` | Yes | Svix signing secret (`whsec_…`) used to verify incoming Recall webhooks. |
+
+> **Calendar scheduling** (`CALL_RECORDER_CALENDAR_BOT_SCHEDULING_ENABLED`,
+> the "Record my calendar meetings" toggle; turning it off cancels
+> every scheduled recording), **bot behavior settings** (display name,
+> recording notice, join timing, lobby and leave timeouts), the transcription
+> provider
+> (`CALL_RECORDER_TRANSCRIPT_PROVIDER`) and the summary settings
+> (`CALL_RECORDER_SUMMARY_ENABLED`,
+> `CALL_RECORDER_ADDITIONAL_SUMMARY_PROMPT`) are **application variables** that
+> a workspace admin tunes inside the app — not server variables.
+
+## Configuring the Recall webhook
+
+The app exposes a server webhook route that verifies the Recall/Svix signature,
+advances the matching recording's lifecycle status (`JOINING` → `RECORDING` →
+`PROCESSING`, or `FAILED`), and — once the recording finishes — ingests the
+audio, video, and transcript. It never moves a status backward, so out-of-order
+or duplicate deliveries are safe, and it returns a non-2xx response on signature
+failures so Recall retries.
+
+Use this URL on your deployment, replacing only the host:
+
+```text
+https://<your-twenty-host>/webhooks/server/9215afe6-1497-4149-a49d-e608e239bbaf
+```
+
+The ID is the **Recall webhook logic function**.
+
+1. In the Recall.ai dashboard, create a webhook endpoint pointing at your
+   deployment's webhook URL, subscribed to the **bot status-change**,
+   **recording**, and **transcript** events (`bot.status_change`,
+   `recording.done`, `recording.failed`, `transcript.done`,
+   `transcript.failed`). Status-change drives the lifecycle; the recording and
+   transcript events trigger media and transcript ingestion. Subscribing to
+   status changes alone leaves ingestion to the reconciliation backstop.
+2. Copy the endpoint's signing secret — it starts with `whsec_`.
+3. Set it as the `RECALL_WEBHOOK_SECRET` server variable on the **Call Recorder**
+   application registration.
+4. Set `RECALL_API_KEY` (and optionally `RECALL_REGION`) the same way.
+
+## Recording lifecycle
+
+Each recording is stored as a **CallRecording** record and moves through a
+lifecycle status: `SCHEDULED` → `JOINING` → `RECORDING` → `PROCESSING` →
+`COMPLETED`, or `FAILED` (with a failure reason when one is available).
+
+A recording reaches `COMPLETED` only once **both** its audio and video have been
+ingested. Recall produces only the artifacts requested at bot creation (mixed
+MP3 + MP4); if processing fails, the recording is marked `FAILED`.
+
+Recall.ai retains the source media for a limited window (about seven days by
+default) to stay inside its free-storage window. Twenty ingests and stores the
+video, audio, and transcript in its own storage, so they remain available after
+Recall's media expires.
+
+A periodic reconciliation job runs as a safety net, pulling the latest status
+from Recall and keeping recordings and bots in sync even when a real-time
+webhook update is missed.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| No bot joined a meeting | **Recording** was off, the event had no conference link, it wasn't synced from a connected calendar, or `RECALL_API_KEY` isn't set | Confirm the event is on, upcoming, has a video link, and came from a synced calendar; confirm `RECALL_API_KEY` is set |
+| Recording never reaches `COMPLETED` | A Recall webhook was missed, or only one of audio/video was produced | The reconciliation job pulls the latest status from Recall within a few minutes; if it is marked `FAILED`, inspect the bot in the Recall dashboard |
+| Transcript empty, or marked pending/failed | Recall hasn't finished async transcription yet, or transcription failed for that call | Wait for the reconciliation job to ingest the transcript; a persistent failure leaves a marker in the transcript |
+| Webhook rejected with `500` (`Invalid webhook signature`, Recall keeps retrying) | `RECALL_WEBHOOK_SECRET` doesn't match the Recall endpoint's signing secret | Re-copy the `whsec_…` secret from the Recall webhook endpoint into the `RECALL_WEBHOOK_SECRET` server variable |
+| Webhook rejected with `500` (`RECALL_WEBHOOK_SECRET … not set`) | `RECALL_WEBHOOK_SECRET` is not set | Set it on the application registration |
+| Bot left almost immediately | No one was admitted before the lobby / empty-meeting timeout, or everyone left | Adjust the lobby / empty-meeting timeouts in the app settings (see **Customize the bot** in the README) if they're too aggressive |
+| Bot joined a meeting you didn't want recorded | Recording is on by default | Set the event's **Recording** field to Off; the scheduled bot is canceled |
+| Summary stays empty after the transcript arrives | Summaries are disabled, or the summarizer run failed (for example, out of AI credits) | Confirm `CALL_RECORDER_SUMMARY_ENABLED` isn't `false` and the workspace has AI credits |
+| Summary shows "No summary available." | The transcript was empty or unintelligible | No action needed; this is the expected outcome for low-quality transcripts |