Fathom CI Integration

Prerequisites

• A protected repository, mocked fixtures, required checks, and a separate scoped development credential for optional integration tests.

Instructions

1. Run deterministic schema/mapping/template/unit checks on pull requests without credentials.
2. Run live synthetic integration checks only from trusted protected workflows.
3. Bound retries and resources, retain redacted evidence, and keep production deployment approval separate.

Output

• A credential-free PR validation lane and a trusted development integration lane with redacted receipts.

Examples

Run mocked meeting/CRM mapping tests on every pull request, then execute one synthetic protected-branch check using a development secret. If it fails, record opaque IDs/status and back off; never expose Fathom/CRM credentials or real meeting data to forked code.

Overview

Set up CI/CD for Fathom meeting intelligence integrations: run unit tests with mocked transcript and action-item responses on every PR, validate live API connectivity against the Fathom meetings endpoint on merge to main. Fathom provides AI-generated meeting summaries, transcripts, and action items, so CI pipelines focus on verifying data parsing logic and webhook handling for real-time meeting events.

GitHub Actions Workflow

# .github/workflows/fathom-ci.yml
name: Fathom CI
on:
  pull_request:
    paths: ['src/fathom/**', 'tests/**']
  push:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test -- --reporter=verbose

  integration-tests:
    if: github.ref == 'refs/heads/main'
    needs: unit-tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:integration
        env:
          FATHOM_API_KEY: ${{ secrets.FATHOM_API_KEY }}

Mock-Based Unit Tests

// tests/fathom-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { extractActionItems } from '../src/fathom-service';

const mockMeeting = {
  id: 'mtg_abc123',
  title: 'Sprint Planning',
  date: '2026-04-01T10:00:00Z',
  transcript: 'We need to fix the login bug by Friday...',
  action_items: [
    { assignee: 'Alice', task: 'Fix login bug', due: '2026-04-05' },
    { assignee: 'Bob', task: 'Update API docs', due: '2026-04-07' },
  ],
};

vi.mock('../src/fathom-client', () => ({
  FathomClient: vi.fn().mockImplementation(() => ({
   …

Fathom Common Errors

Overview

Diagnose Fathom meeting, transcript, integration, CRM-sync, and authorization issues with minimal redacted evidence and reversible fixes.

Prerequisites

• A bounded non-sensitive reproduction, environment/version, consent/data policy, and approved diagnostic channel.

Instructions

1. Identify affected meeting/action state and collect only opaque IDs, status, configuration version, and timing.
2. Validate scope, access, consent, mapping, and rate-limit conditions before applying a correction.
3. Test the smallest safe fix with synthetic records and document the verified result.

Output

• A classified failure with redacted evidence, bounded remediation, owner, and verified recovery/escalation.

Error Handling

Examples

For a missing follow-up, verify the synthetic meeting's action ID, consent state, mapping version, and CRM result in development. Escalate with redacted evidence if unresolved; do not inspect or share a customer recording to troubleshoot it.

Error Reference

1. 401 Unauthorized

Fix: Regenerate API key at Settings > Integrations > API Access.

2. 429 Rate Limited

Limit: 60 calls per minute across all API keys. Fix: Implement exponential backoff. Batch requests.

3. Empty Transcript

Causes: Meeting still processing, recording too short, or audio quality issues. Fix: Wait 5-10 minutes after recording. Check recording in Fathom UI.

4. Missing Summary

Cause: AI processing not complete. Fix: Poll the recording endpoint until summary is available.

5. Webhook Not Firing

Fix: Verify webhook URL in Settings > Integrations > Webhooks. Test with:

curl -X POST https://your-url.com/webhooks/fathom \
  -H "Content-Type: application/json" \
  -d '{"type": "test"}'

6. OAuth Token Expired

Fix: Refresh the access token using your refresh token.

Quick Diagnostics

# Test API key
curl -s -o /dev/null -w "%{http_code}" -H "X-Api-Key: ${FATHOM_API_KEY}" \
  https://api.fathom.ai/external/v1/meetings?limit=1

Resources

• …

Fathom Core Workflow: Meeting Analytics

Prerequisites

• A meeting-recording/consent policy, data owner, scoped access, retention rules, and synthetic fixture for validation.

Output

• A consent-aware meeting analytics workflow with approved access, redacted reporting, owner, and a safe disable/rollback action.

Error Handling

Examples

Use a synthetic meeting record to validate analytics fields, summary workflow, access restriction, and retention outcome. Record only opaque IDs and aggregate status; do not use participant recordings, transcripts, or personal data for testing.

Overview

Build automated meeting analytics: extract action items, sync to project management tools, analyze meeting patterns, and create follow-up workflows.

Instructions

Step 1: Batch Meeting Export

from fathom_client import FathomClient
from datetime import datetime, timedelta

client = FathomClient()

# Get all meetings from last 7 days
week_ago = (datetime.utcnow() - timedelta(days=7)).isoformat() + "Z"
meetings = client.list_meetings(
    limit=50,
    created_after=week_ago,
    include_summary="true",
)

for meeting in meetings:
    print(f"Meeting: {meeting['title']}")
    print(f"  Date: {meeting['created_at']}")
    print(f"  Summary: {meeting.get('summary', 'N/A')[:100]}...")
    for item in meeting.get("action_items", []):
        print(f"  Action: {item['text']} -> {item.get('assignee', 'unassigned')}")
    print()

Step 2: Action Item Extraction Pipeline

def extract_action_items(meetings: list[dict]) -> list[dict]:
    items = []
    for meeting in meetings:
        for action in meeting.get("action_items", []):
            items.append({
                "meeting_title": meeting["title"],
                "meeting_date": meeting["created_at"],
                "action_text": action["text"],
                "assignee": action.get("assignee", "unassigned"),
                "meeting_id": meeting["id"],
            })
    return items

# Sync to task tracker
def sync_to_linear(items: list[dict], api_key: str):
    for item in items:
        # C…

Fathom Core Workflow: CRM Sync & Follow-Up

Prerequisites

• Approved CRM mapping, consent/recording policy, scoped credentials, owner, and synthetic test meeting data.

Output

• A reviewed Fathom-to-CRM follow-up workflow with explicit field mapping, consent/data controls, idempotency, and rollback/disable action.

Error Handling

Examples

Use a synthetic meeting summary and test CRM contact to verify field mapping, follow-up creation, and deduplication in development. Record only opaque IDs and outcomes; do not use customer recordings, transcripts, or contacts as a tutorial fixture.

Overview

Automate post-meeting workflows: sync meeting notes to CRM opportunities, send follow-up emails with action items, and maintain a meeting history database.

Instructions

Meeting-to-CRM Sync

def sync_meeting_to_crm(meeting: dict, crm_client):
    summary = meeting.get("summary", "")
    action_items = meeting.get("action_items", [])
    participants = meeting.get("participants", [])

    # Find matching CRM contact/opportunity by participant email
    for email in participants:
        contact = crm_client.find_contact(email=email)
        if contact:
            crm_client.log_activity(
                contact_id=contact["id"],
                type="meeting",
                subject=meeting["title"],
                body=f"Summary: {summary}\n\nAction Items:\n" +
                     "\n".join(f"- {a['text']}" for a in action_items),
                date=meeting["created_at"],
            )

Automated Follow-Up Email

def generate_followup_email(meeting: dict) -> str:
    actions = meeting.get("action_items", [])
    action_list = "\n".join(f"- {a['text']}" for a in actions)

    return f"""Hi team,

Thanks for the meeting: {meeting['title']}

Summary:
{meeting.get('summary', 'No summary available')}

Action Items:
{action_list if action_list else '- None recorded'}

Best regards"""

Meeting History Database

CREATE TABLE fathom_meetings (
    id VARCHAR PRIMARY KEY,
    title VARC…

Fathom Cost Tuning

Prerequisites

• An aggregate usage/cost baseline, budget owner, recording/consent policy, quality/delivery SLO, and synthetic evaluation fixture.

Instructions

1. Measure aggregate meeting volume, processing, sync/follow-up behavior, errors, and cost by approved scope.
2. Change one reversible setting and compare against the baseline and consent/delivery safeguards.
3. Retain the change only after owner approval; restore the prior setting on regression.

Output

• A measured cost decision with owner, data/consent/delivery guardrails, and rollback threshold.

Examples

Evaluate a development workflow with synthetic meeting metadata, reduce duplicate processing or unnecessary integration calls, and compare aggregate cost/latency/error metrics. Revert on quality, consent, or CRM-sync regression; do not disable audit, retention, or access controls to save cost.

Overview

Fathom pricing scales with per-seat licensing for team features, with primary cost drivers being transcript storage volume and recording hours consumed. Every meeting generates a transcript and AI summary that persist in storage. For organizations running dozens of meetings daily, unchecked transcript accumulation and redundant API polling for meeting data create unnecessary spend. Optimizing retrieval patterns and storage lifecycle directly reduces both API costs and plan overhead.

Cost Breakdown

API Call Reduction

class FathomTranscriptCache {
  private cache = new Map<string, { transcript: string; summary: string }>();

  async getTranscript(meetingId: string, apiFn: () => Promise<any>): Promise<any> {
    // Transcripts are immutable after generation — cache permanently
    if (this.cache.has(meetingId)) return this.cache.get(meetingId);
    const result = await apiFn();
    this.cache.set(meetingId, result);
    return result;
  }

  async listMeetings(params: { include_summary: boolean }): Promise<any[]> {
    // Always use include_summary=…

Fathom Debug Bundle

Prerequisites

• An issue owner, affected environment, approved incident/support destination, and strict redaction policy for meeting content and credentials.

Instructions

1. Collect only correlation IDs, environment, versions, configuration state, status classes, and aggregate timing.
2. Review the bundle for recordings, transcripts, participant data, CRM records, tokens, and private links before distribution.
3. Reproduce with a synthetic meeting/test account and retain the minimum approved evidence.

Output

• A minimal redacted diagnostic bundle with owner, scope, evidence, and safe escalation/recovery path.

Error Handling

Examples

For a CRM-sync failure, collect opaque meeting/action IDs, environment, mapping version, status class, and timestamp, then reproduce with a synthetic record. Do not attach recordings, transcript text, contact details, or tokens to the case.

Overview

Collect Fathom API connectivity status, meeting recording metadata, transcript availability, and authentication state into a single diagnostic archive. This bundle helps troubleshoot missing transcripts, failed meeting syncs, webhook delivery issues, and API authentication problems. Attach the output to Fathom support tickets so engineers can diagnose integration failures without back-and-forth.

Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-fathom-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Fathom Debug Bundle ===" | tee "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "FATHOM_API_KEY: ${FATHOM_API_KEY:+[SET]}" >> "$BUNDLE/summary.txt"

# API connectivity
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "X-Api-Key: ${FATHOM_API_KEY}" \
  https://api.fathom.ai/external/v1/meetings?limit=1 2>/dev/null || echo "000")
echo "API Status: HTTP $HTTP" >> "$BUNDLE/summary.txt"

# Recent meetings (last 5)
curl -s -H "X-Api-Key: ${FATHOM_API_KEY}" \
  "https://api.fathom.ai/external/v1/meetings?limit=5" \
  > "$BUNDLE/recent-meetings.json" 2>&1 || true

# Check transcript availability for latest meeting
MEETING_ID=$(curl -s -H "X…

Fathom Deploy Integration

Prerequisites

• A versioned deployment/configuration, approved tenant/data/consent policy, scoped secret reference, owner, and rollback plan.

Instructions

1. Deploy to development/staging with synthetic meeting data and validate access, mapping, callbacks, redacted telemetry, and recovery.
2. Promote only through an approved production canary with named observer.
3. Roll back or pause on consent, access, data, delivery, or reliability regression.

Output

• A staged deployment receipt with owner approval, synthetic validation, canary evidence, and rollback reference.

Examples

Deploy a versioned CRM-sync integration to staging with scoped credentials, test a synthetic meeting/action, and verify mappings and alerts. Promote an approved canary only; restore the prior configuration if unexpected access, follow-up, or data behavior occurs.

Overview

Deploy a containerized Fathom AI meeting integration service with Docker. This skill covers building a production image that connects to the Fathom API for processing meeting transcripts, summaries, and action items. Includes environment configuration for webhook handling, health checks that verify Fathom API connectivity and transcript retrieval, and rolling update strategies to maintain continuous meeting data processing without losing webhook events.

Docker Configuration

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:20-slim
RUN addgroup --system app && adduser --system --ingroup app app
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

Environment Variables

export FATHOM_API_KEY="fthm_live_xxxxxxxxxxxx"
export FATHOM_BASE_URL="https://api.fathom.video/v1"
export FATHOM_WEBHOOK_SECRET="whsec_xxxxxxxxxxxx"
export LOG_LEVEL="info"
export PORT="3000"
export NODE_ENV="production"

Health Check Endpoint

import express from 'express';

const app = express();

app.get('/health', async (req, res) => {
  try {
    const response = await fetch(`${process.env.FATHOM_BASE_URL}/meetings`, {
      headers: { 'Authorization': `Bearer ${process.env.FATHOM_API_KEY}` },
    });
    if (!response.ok) throw new Error(`Fathom API returned ${response.status}`);
    res.json({ status: 'healthy', service: 'fathom-integration', timestamp: new Date().toISOStrin…

Fathom Hello World

Examples

Create a development-only synthetic meeting/test account, verify the basic Fathom workflow and any resulting summary/action state, then remove or expire the fixture under policy. Record only environment and opaque result IDs; never use a customer recording, transcript, participant identity, or production CRM contact as a tutorial example.

Overview

First API calls against Fathom: list meetings, get a transcript, retrieve AI-generated summaries and action items.

Prerequisites

• Completed fathom-install-auth setup
• At least one recorded meeting in Fathom

Instructions

Step 1: List Meetings

curl -s -H "X-Api-Key: ${FATHOM_API_KEY}" \
  "https://api.fathom.ai/external/v1/meetings?limit=5" \
  | jq '.meetings[] | {id, title, created_at, duration_seconds}'

Step 2: Get Meeting Transcript

RECORDING_ID="your-recording-id"

curl -s -H "X-Api-Key: ${FATHOM_API_KEY}" \
  "https://api.fathom.ai/external/v1/recordings/${RECORDING_ID}/transcript" \
  | jq '.segments[] | {speaker, text, start_time}'

Step 3: Get AI Summary and Action Items

# Get meeting with summary included
curl -s -H "X-Api-Key: ${FATHOM_API_KEY}" \
  "https://api.fathom.ai/external/v1/meetings?include_summary=true&limit=1" \
  | jq '.meetings[0] | {title, summary, action_items}'

Step 4: Filter Meetings by Date

# Meetings from the last 7 days
curl -s -H "X-Api-Key: ${FATHOM_API_KEY}" \
  "https://api.fathom.ai/external/v1/meetings?created_after=2026-03-15T00:00:00Z&limit=20" \
  | jq '.meetings | length'

Output

• List of meetings with IDs and metadata
• Full transcript with speaker labels and timestamps
• AI-generated summary and action items

Error Handling

Resources

• Fathom API Reference
• Get Transcript

Next Steps

Proceed to fathom-loca…

Fathom Install & Auth

Output

• A scoped Fathom credential/integration reference for the intended environment, with a verified low-impact connection test.
• A credential ownership, rotation, and revocation path that protects meeting content and contacts.

Examples

Configure a development credential from the approved secret manager and verify access against a synthetic meeting/test account, recording only environment and result. If a token appears in code, logs, or support material, revoke it immediately and issue a replacement before further diagnosis.

Overview

Set up Fathom AI API access for retrieving meeting transcripts, summaries, and action items. The API at api.fathom.ai/external/v1 uses X-Api-Key header authentication with per-user API keys.

Prerequisites

• Fathom account (free or Team plan)
• API access enabled in Settings

Instructions

Step 1: Generate API Key

1. Log in to https://fathom.video
2. Navigate to Settings > Integrations > API Access
3. Click Generate API Key
4. Copy and store the key securely

export FATHOM_API_KEY="your-api-key-here"

# Verify the key works
curl -s -H "X-Api-Key: ${FATHOM_API_KEY}" \
  https://api.fathom.ai/external/v1/meetings?limit=1 | jq .

Step 2: Configure Environment

# .env -- NEVER commit
FATHOM_API_KEY=your-api-key
FATHOM_BASE_URL=https://api.fathom.ai/external/v1

# .gitignore
.env
.env.local

Step 3: Test API Connectivity

# List recent meetings
curl -s -H "X-Api-Key: ${FATHOM_API_KEY}" \
  "https://api.fathom.ai/external/v1/meetings?limit=5" \
  | jq '.meetings[] | {id: .id, title: .title, date: .created_at}'

Step 4: OAuth Setup (For Public Apps)

# For building integrations others will use, register an OAuth app
# at developers.fathom.ai for marketplace listing eligibility

# OAuth apps cannot use include_transcript or include_summary
# in list requests -- use individual recording endpoints instead

Error Handling

Resources

Fathom Local Dev Loop

Overview

Use Fathom integrations in the normal local development loop: narrow change, synthetic validation, review, focused tests, and reversible commit.

Prerequisites

• A clean or recoverable branch, development credential, synthetic meeting/CRM fixtures, repository rules, and test commands.

Instructions

1. Make one scoped integration/configuration change using development-only data and identity.
2. Inspect the diff, run focused mock/unit checks, and execute a bounded synthetic workflow test.
3. Commit reviewed changes separately and promote only through normal protected workflow.

Output

• A small reviewed change with test evidence and a normal rollback path, without production meeting or contact data.

Error Handling

Examples

Update one mapping using a synthetic meeting/action, run its focused test, inspect the redacted result, and commit it separately. If the test fails or unrelated files change, revert/split the work rather than disabling checks or pointing local tooling at production.

Project Structure

fathom-integration/
├── src/
│   ├── fathom_client.py
│   ├── transcript_processor.py
│   └── webhook_handler.py
├── tests/
│   ├── fixtures/
│   │   ├── meeting.json
│   │   └── transcript.json
│   └── test_processor.py
├── .env.local
└── requirements.txt

Mock Meeting Data

MOCK_MEETING = {
    "id": "mtg-123",
    "title": "Product Review Q1",
    "created_at": "2026-03-20T14:00:00Z",
    "duration_seconds": 1800,
    "participants": ["alice@example.com", "bob@example.com"],
    "summary": "Discussed Q1 roadmap priorities. Agreed to focus on API improvements.",
    "action_items": [
        {"text": "Alice to draft API spec by Friday", "assignee": "alice@example.com"},
        {"text": "Bob to review competitor analysis", "assignee": "bob@example.com"}
    ]
}

MOCK_TRANSCRIPT = {
    "segments": [
        {"speaker": "Alice", "text": "Let us review the Q1 priorities.", "start_time": 0.0},
        {"speaker": "Bob", "text": "I think the API work should come first.…

Fathom Performance Tuning

Prerequisites

• A baseline for processing latency, sync/delivery error, quality, and an approved data/consent policy.
• Synthetic meeting metadata, an owner, and a reversible performance-change threshold.

Instructions

1. Measure aggregate processing, sync, and alert behavior without using meeting content as diagnostic data.
2. Change one approved queue/concurrency/integration setting and compare against baseline.
3. Revert on quality, consent, delivery, or reliability regression.

Output

• A measured performance recommendation with data/consent guardrails, owner, and rollback record.

Examples

Use synthetic meetings to measure processing and CRM-sync latency, change one bounded concurrency setting, and compare aggregate results. Revert if errors or incorrect follow-up behavior increases; do not bypass review or retention controls to improve performance.

Overview

Fathom's meeting intelligence API serves transcript downloads, bulk meeting sync, and action item aggregation. Transcript payloads are large (50-500KB each), making bulk sync of historical meetings a major latency bottleneck. The 60 req/min rate limit requires careful batching. Caching immutable transcripts aggressively while keeping action item data fresh reduces download latency by 70% and prevents rate limit errors during bulk operations.

Caching Strategy

const cache = new Map<string, { data: any; expiry: number }>();
const TTL = { transcript: 3_600_000, actionItems: 120_000, meetings: 300_000 };

async function cached(key: string, ttlKey: keyof typeof TTL, fn: () => Promise<any>) {
  const entry = cache.get(key);
  if (entry && entry.expiry > Date.now()) return entry.data;
  const data = await fn();
  cache.set(key, { data, expiry: Date.now() + TTL[ttlKey] });
  return data;
}
// Transcripts are immutable — cache 1hr. Action items change — cache 2min.

Batch Operations

async function syncMeetingsBatch(client: any, ids: string[], batchSize = 50) {
  const results = [];
  for (let i = 0; i < ids.length; i += batchSize) {
    const batch = ids.slice(i, i + batchSize);
    const res = await Promise.all(batch.map(id => client.getTranscript(id)));
    results.push(...res);
    if (i + batchSize < ids.length) await new Promise(r => setTimeout(r, 61_000)); // 60 req/min
  }
  return results;
}

Connection Pooling

import { Agent } from 'https';
const agent = new Agent({ keepAlive: true, maxSockets: 6, maxFreeSockets: 3, timeout: 45_000 });
// Transcript downloads are large — longer timeout, fewer concurrent sockets

Rate Limit Management

async function withFa…

Fathom Production Checklist

Prerequisites

• A named tenant/data owner, approved recording/consent/data-use policy, identity/secret boundary, and rollback plan.

Instructions

1. Complete evidence gates for access, consent, retention, integrations, CRM mapping, observability, incident response, and rollback.
2. Validate a synthetic or approved canary workflow and verify its access/data boundaries.
3. Block production enablement when any data, consent, security, ownership, or recovery gate is unverified.

Output

• A production-readiness receipt with evidence, owner, exceptions, canary result, and tested rollback path.

Examples

Pilot a production-like configuration using approved synthetic meeting data, verify consent/access/CRM behavior and alert routing, then observe the stated window. Restore the prior configuration if any gate fails; do not widen access or send real follow-ups to conceal a defect.

Overview

Fathom provides AI-powered meeting intelligence with automated transcription, summaries, and action item extraction. A production integration ingests meeting recordings, processes transcripts, and syncs action items to downstream systems. Failures mean lost meeting context, missed follow-ups, or transcript data leaking outside authorized channels. This checklist ensures reliable, compliant meeting data pipelines.

Authentication & Secrets

• [ ] FATHOM_API_KEY stored in secrets manager (not environment files)
• [ ] OAuth app registered if building public-facing integration
• [ ] Key rotation schedule documented (90-day cycle)
• [ ] Separate credentials for dev/staging/prod environments
• [ ] Webhook signing secret configured for payload verification

API Integration

• [ ] Production base URL configured (https://api.fathom.video/v1)
• [ ] Rate limit handling with backoff (60 req/min standard tier)
• [ ] Webhook endpoint registered and tested with sample payloads
• [ ] Meeting recording retrieval handles large file downloads
• [ ] Transcript pagination implemented for long meetings (>60 min)
• [ ] Action item extraction tested with various meeting formats
• [ ] Calendar integration sync verified (Google Calendar / Outlook)

Error Handling & Resilience

• [ ] Circuit breaker configured for Fathom API outages
• [ ] Retry with exponential backoff for 429/5xx responses
• [ ] Empty or partial transcript handling (silent meetings, poor audio)
• [ ] Webhook delivery failures trigger re-fetch via polling
• [ ] Meeting data PII handling documented (GDPR consent, retention)
• [ ] Backup webhook URL configured for failover

Monitoring & Alerting

• [ ] API latency tracked per endpoint (…

Fathom Rate Limits

Prerequisites

• Current provider limits, aggregate baseline, stable request/event IDs, synthetic test data, and a capacity owner.

Instructions

1. Bound concurrency and preserve idempotency for meeting, sync, and follow-up operations.
2. Monitor throttling, queue age, errors, and duplicate-action risk using redacted aggregate metrics.
3. Back off with jitter on transient limits and reduce load before replaying failed work.

Output

• A rate-aware workflow with bounded retry, idempotency, redacted monitoring, and safe recovery ownership.

Examples

Increase synthetic development workload gradually below approved limits, record aggregate 429s/latency/completion, and apply backoff on throttling. Do not retry meeting/CRM follow-up actions without checking stable IDs, consent, and current state.

Overview

Fathom's API enforces a strict 60 requests-per-minute cap per user across all API keys. Since meeting transcripts and action items are often fetched in bulk after a day of calls, this limit becomes a real constraint for teams processing large meeting backlogs. Transcript endpoints are especially heavy because they return full conversation text, making pagination and careful throttling essential for any integration that syncs meeting intelligence into CRMs or project trackers.

Rate Limit Reference

Rate Limiter Implementation

class FathomRateLimiter {
  private tokens: number = 60;
  private lastRefill: number = Date.now();
  private queue: Array<{ resolve: () => void }> = [];

  async acquire(): Promise<void> {
    this.refill();
    if (this.tokens >= 1) { this.tokens -= 1; return; }
    return new Promise(resolve => this.queue.push({ resolve }));
  }

  private refill() {
    const now = Date.now();
    const elapsed = now - this.lastRefill;
    this.tokens = Math.min(60, this.tokens + (elapsed / 60_000) * 60);
    this.lastRefill = now;
    while (this.tokens >= 1 && this.queue.length) {
      this.tokens -= 1;
      this.queue.shift()!.resolve();
    }
  }
}

const limiter = new FathomRateLimiter();

Retry Strategy

async function fathomRetry<T>(fn: () => Promise<Response>, maxRetries =…

Fathom Reference Architecture

Overview

Define meeting ingestion, consent, Fathom processing, CRM/follow-up integration, redacted observability, retention, and incident boundaries as an owned system.

Prerequisites

• A documented data/consent model, environment boundaries, integration owners, and approved data-retention policy.

Instructions

1. Map meeting sources, identities, processing, integrations, access, and audit paths to owners.
2. Separate development/staging/production credentials and use role-limited access at every boundary.
3. Build idempotent integrations and fallback/rollback decisions before production automation.

Output

• An architecture record with trust boundaries, ownership, consent/data controls, and reversible integration points.

Error Handling

Examples

Model a development flow from a synthetic meeting to a scoped Fathom integration and test CRM record, retaining only opaque correlation/audit metadata. Promote the reviewed version through staging before a production canary; do not make summary output an unreviewed system of record.

Architecture

┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│  Fathom AI   │────▶│  Webhook        │────▶│  Meeting DB      │
│  (Recordings)│     │  Handler        │     │  (PostgreSQL)    │
└──────────────┘     └─────────────────┘     └────────┬─────────┘
                                                       │
                     ┌─────────────────┐     ┌────────▼─────────┐
                     │  Action Item    │     │  CRM Sync        │
                     │  Extractor      │────▶│  (Salesforce/    │
                     └─────────────────┘     │   HubSpot)       │
                            │                └──────────────────┘
                     ┌──────▼──────────┐
                     │  Follow-up      │
                     │  Email Sender   │
                     └─────────────────┘

Project Structure

fathom-platform/
├── src/
│   ├── fathom_client.py
│   ├── webhook_handler.py
│   ├── transcript_processor.py
│   ├── action_extractor.py
│   ├── crm_sync.py
│   └── email_sender.py
├── sql/
│   └── schema.sql
├── tests/
│   ├── fixtures/
│   └── test_processor.py
└── deploy/
    ├── cloud-function/
    └── docker-compose.yaml

Key Design Decisions

Fathom SDK Patterns

Overview

Build a narrow Fathom client boundary that makes consent, data handling, idempotency, redaction, and human ownership explicit.

Prerequisites

• Scoped development credentials, an approved recording/data policy, synthetic fixtures, and existing test conventions.

Instructions

1. Inject credentials only from the approved secret manager and validate request/response contracts at the boundary.
2. Use stable IDs, bounded retries, and redacted telemetry for sync/follow-up actions.
3. Unit-test with mocks and run one synthetic development integration check before promotion.

Output

• A test-backed SDK boundary with scoped credentials, safe errors, redacted observability, and rollback-friendly behavior.

Examples

Instantiate the client with a development secret reference, send a synthetic meeting/action event with an idempotency key, and assert the mocked CRM-sync payload. Record only opaque IDs/results; never log a recording, transcript, contact, or token.

Python Client

import os, requests
from dataclasses import dataclass
from typing import Optional

@dataclass
class FathomConfig:
    api_key: str
    base_url: str = "https://api.fathom.ai/external/v1"
    timeout: int = 30

class FathomClient:
    def __init__(self, config: Optional[FathomConfig] = None):
        self.config = config or FathomConfig(api_key=os.environ["FATHOM_API_KEY"])
        self.session = requests.Session()
        self.session.headers.update({"X-Api-Key": self.config.api_key})

    def list_meetings(self, limit: int = 20, **filters) -> list[dict]:
        params = {"limit": limit, **filters}
        resp = self.session.get(f"{self.config.base_url}/meetings", params=params, timeout=self.config.timeout)
        resp.raise_for_status()
        return resp.json().get("meetings", [])

    def get_transcript(self, recording_id: str) -> dict:
        resp = self.session.get(f"{self.config.base_url}/recordings/{recording_id}/transcript", timeout=self.config.timeout)
        resp.raise_for_status()
        return resp.json()

    def get_summary(self, recording_id: str) -> dict:
        resp = self.session.get(f"{self.config.base_url}/recordings/{recording_id}/summary", timeout=self.config.timeout)
        resp.raise_for_status()
        return resp.json()

TypeScript Client

class FathomClient {
  private apiKey: string;
  private baseUrl: string;

  constructor(apiKey?: string) {
    this.apiKey = apiKey ?? process.env.FATHOM_API_KEY!;
    this.baseUrl = "https://api.fathom.ai/external/v1";
  }

  private async get<T>(path: string, params?: Record<string, string>): Promise<T> {
    const url = new URL(`${this…

Fathom Security Basics

Prerequisites

• A current recording/data classification, consent policy, scoped identity/secrets, and incident owner.

Instructions

1. Apply least-privilege roles and approved recording/transcript access settings.
2. Keep credentials in the secret manager and meeting content out of logs and test fixtures.
3. Validate integrations and sharing controls with synthetic records before broad rollout.
4. Revoke access and follow the incident process on suspected exposure.

Output

• A controlled Fathom deployment with data/consent safeguards, scoped credentials, access review, and incident path.

Examples

Verify a development role can access only its synthetic meeting record and cannot retrieve production content, then record the redacted result and review date. If a token, recording, transcript, or participant data is exposed, contain/revoke first and follow the data incident process.

Overview

Fathom records and transcribes meetings, producing transcripts and action items that contain participant PII (names, emails, spoken content), confidential business decisions, and potentially sensitive negotiations. API keys are per-user and grant access to all meetings the user recorded or that were shared to their team. Protect recording consent workflows, transcript storage, and any analytics pipeline touching meeting content.

API Key Management

function createFathomClient(): { apiKey: string; baseUrl: string } {
  const apiKey = process.env.FATHOM_API_KEY;
  if (!apiKey) {
    throw new Error("Missing FATHOM_API_KEY — store in secrets manager, never in code");
  }
  // Fathom keys are per-user — never share across team members
  console.log("Fathom client initialized (key hash:", apiKey.slice(-4), ")");
  return { apiKey, baseUrl: "https://api.fathom.video/v1" };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyFathomWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-fathom-signature"] as string;
  const secret = process.env.FATHOM_WEBHOOK_SECRET!;
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const MeetingQuerySchema = z.object({
  meeting_id: z.string().uuid(),
  include_transcript: z.boolean().default(false),
  date_from: z.string().regex(/^…

Fathom Upgrade & Migration

Prerequisites

• Current/target version inventory, compatibility notes, synthetic fixtures, acceptance criteria, and rollback owner.

Instructions

1. Inventory configuration, credentials, CRM mappings, access, retention, and consent behavior.
2. Test the target in development/staging with synthetic meetings and records.
3. Compare aggregate quality, delivery, error, access, and policy results before a bounded canary.
4. Pause or roll back on regression and retain the prior configuration until sign-off.

Output

• A staged upgrade record with evidence, owner, observation window, and rollback revision.

Examples

Upgrade the integration in staging, run mock/unit and synthetic workflow checks against prior and target versions, and compare aggregate sync/follow-up behavior. Roll back on consent, access, mapping, or reliability regression; do not replay customer meetings to validate a migration.

Overview

Fathom is an AI meeting assistant that records, transcribes, and summarizes meetings. The API operates under /external/v1 and exposes endpoints for meetings, transcripts, and action items. Tracking API changes is important because Fathom iterates rapidly on transcript schema fields (speaker attribution, sentiment data, highlight clips) and breaking changes to response shapes can silently corrupt downstream integrations that consume meeting data for CRM sync or analytics pipelines.

Version Detection

const FATHOM_BASE = "https://api.fathom.video/external/v1";

interface FathomVersionCheck {
  apiVersion: string;
  knownFields: string[];
  detectedFields: string[];
  newFields: string[];
  removedFields: string[];
}

async function detectFathomApiChanges(apiKey: string): Promise<FathomVersionCheck> {
  const res = await fetch(`${FATHOM_BASE}/meetings?limit=1`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const data = await res.json();
  const knownFields = ["id", "title", "created_at", "duration", "attendees", "transcript_url"];
  const detectedFields = data.meetings?.[0] ? Object.keys(data.meetings[0]) : [];
  return {
    apiVersion: res.headers.get("x-api-version") ?? "v1",
    knownFields,
    detectedFields,
    newFields: detectedFields.filter((f) => !knownFields.includes(f)),
    removedFields: knownFields.filter((f) => !detectedFields.includes(f)),
  };
}

Migration Checklist

• [ ] Review Fathom product updates for API changes and deprecations
• [ ] Audit all endpoints referencing /external/v1 in codebase
• [ ] Verify meeting list response schema matches current field expectations
• [ ] Check transcript endpoint for new speaker attribution …

Fathom Webhooks & Events

Prerequisites

• A verified callback endpoint, signature/authentication rule, idempotency store, redaction policy, and event owner.

Instructions

1. Validate signatures before parsing payloads and acknowledge within the documented timeout.
2. Deduplicate events using stable opaque IDs and record only necessary redacted metadata.
3. Apply bounded retry/backoff for transient errors and quarantine malformed terminal failures.

Output

• A signed, idempotent webhook/event flow with redacted observability, recovery ownership, and a safe replay decision path.

Error Handling

Examples

Test a development callback using a synthetic event, verify signature, deduplication, and a bounded failure path, then record only event ID/state/result. Do not persist transcript text, meeting content, contacts, or webhook secrets in the diagnostics.

Overview

Fathom webhooks send meeting data to your URL when recordings are ready. Webhooks can include summary, transcript, and action items. Configure in Settings or via API.

Webhook Setup

Via API

curl -X POST -H "X-Api-Key: ${FATHOM_API_KEY}" \
  -H "Content-Type: application/json" \
  https://api.fathom.ai/external/v1/webhooks \
  -d '{
    "url": "https://your-app.com/webhooks/fathom",
    "include_summary": true,
    "include_transcript": true,
    "include_action_items": true,
    "fire_on_own_meetings": true,
    "fire_on_shared_meetings": false
  }'

Via Settings

Navigate to Settings > Integrations > Webhooks > Create Webhook.

Webhook Payload

{
  "type": "meeting_content_ready",
  "recording_id": "rec-abc123",
  "url": "https://fathom.video/call/abc123",
  "share_url": "https://fathom.video/share/abc123",
  "title": "Product Review Q1",
  "summary": "Discussed roadmap priorities...",
  "transcript": [...],
  "action_items": [...]
}

Webhook Handler

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/fathom", method…