Back to Details

sales-fathom

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fathom Platform Help

Fathom 平台帮助

Step 1 — Gather context

步骤1 — 收集上下文

If 
references/learnings.md
exists, read it first for accumulated Fathom knowledge.
  1. What are you trying to do?
    • A) Configure Fathom account/team/plan or understand pricing tiers
    • B) Build a backend integration (API, webhooks, OAuth, SDK)
    • C) Troubleshoot webhook delivery / HMAC signature verification
    • D) Push transcripts/summaries into CRM, data warehouse, or Slack
    • E) Troubleshoot bot joining / Google Meet security flag / Teams/Zoom capture
    • F) Evaluate Fathom vs alternatives — route to 
      /sales-note-taker
  2. Which auth path?
    • A) Personal API key (single user, 
      X-Api-Key
      header)
    • B) OAuth 2.0 app (multi-tenant integration, Marketplace listing)
    • C) Not sure yet
  3. Which Fathom plan?
    • A) Free
    • B) Premium ($20/mo, $16 annual) — for individuals
    • C) Team ($19/user/mo, 2-user min)
    • D) Business ($34/user/mo, 2-user min) — CRM sync
    • E) Special: Qualified Portfolio, nonprofit, Gong switchover
Skip-ahead rule: if the user's prompt already has the context, skip to Step 2.
如果
references/learnings.md
文件存在，请先阅读该文件以获取积累的Fathom相关知识。
  1. 你想要实现什么目标？
    • A) 配置Fathom账户/团队/方案，或了解定价层级
    • B) 构建后端集成（API、Webhook、OAuth、SDK）
    • C) 排查Webhook交付 / HMAC签名验证问题
    • D) 将记录/摘要推送至CRM、数据仓库或Slack
    • E) 排查机器人加入 / Google Meet安全标记 / Teams/Zoom录制问题
    • F) 评估Fathom与竞品的差异 — 路由至
      /sales-note-taker
  2. 采用哪种认证方式？
    • A) 个人API密钥（单用户，使用
      X-Api-Key
      请求头）
    • B) OAuth 2.0应用（多租户集成，市场应用列表）
    • C) 尚未确定
  3. 使用的是Fathom哪类方案？
    • A) 免费版
    • B) Premium版（每月20美元，年付16美元）— 面向个人用户
    • C) Team版（每用户每月19美元，至少2用户）
    • D) Business版（每用户每月34美元，至少2用户）— 支持CRM同步
    • E) 特殊方案：合格投资组合、非营利组织、从Gong迁移用户
跳过规则：如果用户的提问中已包含相关上下文，直接进入步骤2。

Step 2 — Route or answer directly

步骤2 — 路由或直接解答

User situationRoute to
"Fathom vs Fireflies vs Gong vs Avoma — which should we pick"
/sales-note-taker {question}
"Review this Fathom recording and score it"
/sales-call-review {question}
"Manager coaching program using Fathom recordings"
/sales-coaching {question}
"Build a generic Zapier/Make/n8n workflow"
/sales-integration {question}
Anything Fathom-platform-specific (API, webhooks, pricing, integrations, bot behavior)Stay here
When routing, use the exact command: 
/sales-{skill} {user's original question}
.
用户场景路由至
"Fathom、Fireflies、Gong、Avoma之间该选哪一个"
/sales-note-taker {question}
"帮我查看这份Fathom录音并打分"
/sales-call-review {question}
"使用Fathom录音开展经理辅导项目"
/sales-coaching {question}
"搭建通用Zapier/Make/n8n工作流"
/sales-integration {question}
任何Fathom平台相关问题（API、Webhook、定价、集成、机器人行为）留在当前模块
路由时请使用精确命令：
/sales-{skill} {用户原始问题}
。

Step 3 — Fathom platform reference

步骤3 — Fathom平台参考资料

Read 
references/platform-guide.md
 for the full platform reference — modules, pricing tiers, integrations, plan-gated features, special programs.
Read 
references/fathom-api-reference.md
 for verbatim API docs — endpoints, request/response schemas, OAuth flow, webhook HMAC verification, rate limits, SDK methods.
Answer using only the relevant section. Don't dump the entire reference.
**阅读
references/platform-guide.md
**获取完整平台参考内容 — 模块、定价层级、集成功能、方案专属特性、特殊项目。
**阅读
references/fathom-api-reference.md
**获取API文档原文 — 端点、请求/响应 schema、OAuth流程、Webhook HMAC验证、速率限制、SDK方法。
仅使用相关章节内容作答，不要直接输出完整参考资料。

Step 4 — Actionable guidance

步骤4 — 可落地指导

Once you have the relevant reference content:
  1. For API/webhook questions — give a concrete code snippet (cURL, Python, or TypeScript based on user's stack), note the auth header or OAuth scope required, and flag the 60-req/min rate limit if the operation loops over many recordings.
  2. For transcript pipeline design — recommend webhook-first (create one via 
    POST /webhooks
    with 
    include_transcript=true
    and the right 
    triggered_for
    array) and fall back to polling 
    GET /meetings?created_after=...&cursor=...
    for backfill/reconciliation. For OAuth apps, always use the separate 
    GET /recordings/{id}/transcript
    endpoint (the inline 
    include_transcript
    param is disabled for OAuth).
  3. For plan/pricing questions — Team/Business require a 2-user minimum and cap at max 3 CRM users per domain. CRM sync is Business-only.
  4. For bot/capture issues — Google Meet has recently flagged Fathom's default bot mode as a security concern; point at the "Bot-free capture" setting or native Zoom/Teams recording integration as a workaround.
If you discover a gotcha, workaround, or tip not covered in 
references/learnings.md
, append it there with today's date.
获取相关参考内容后：
  1. 针对API/Webhook问题 — 根据用户技术栈提供具体代码片段（cURL、Python或TypeScript），注明所需的认证请求头或OAuth权限范围，若操作涉及遍历大量录音，需提醒每分钟60次请求的速率限制。
  2. 针对记录管道设计 — 优先推荐Webhook方案（通过
    POST /webhooks
    创建Webhook，设置
    include_transcript=true
    并配置正确的
    triggered_for
    数组），回退方案为轮询
    GET /meetings?created_after=...&cursor=...
    以进行数据回填/对账。对于OAuth应用，必须使用独立的
    GET /recordings/{id}/transcript
    端点（OAuth模式下内嵌的
    include_transcript
    参数已禁用）。
  3. 针对方案/定价问题 — Team/Business方案要求至少2用户，且每个域名最多支持3个CRM用户。CRM同步仅Business版可用。
  4. 针对机器人/录制问题 — Google Meet近期已将Fathom默认机器人模式标记为安全风险；可推荐使用“无机器人录制”设置，或Zoom/Teams原生录制集成作为替代方案。
如果发现
references/learnings.md
中未覆盖的陷阱、替代方案或技巧，请添加该内容并标注今日日期。

Gotchas

注意事项

Best-effort from research (2026-04) — review pricing tier limits and plan-gated features before quoting customers.
  • API keys are user-scoped, not workspace-scoped. An admin's key only sees their own recordings plus team-shared ones — it does NOT unlock other users' unshared meetings. For team-wide access, use OAuth with each user's consent or list team members and have each authorize.
  • OAuth apps cannot use 
    include_transcript
    or 
    include_summary
    query params on 
    GET /meetings
    .     Must fetch these separately via 
    GET /recordings/{recording_id}/transcript
    and 
    GET /recordings/{recording_id}/summary
    . Plan this into pipelines — it's 1 extra API call per meeting for OAuth builds.
  • Create-webhook requires at least one of 
    include_transcript
    , 
    include_crm_matches
    , 
    include_summary
    , or 
    include_action_items
     to be 
    true
    . An empty payload is rejected.
  • Rate limit is 60 calls/minute, user-based (not key-based). Creating multiple API keys won't raise it. Bulk backfills must respect this — queue requests and handle 
    429
    with the 
    RateLimit-Reset
    header.
  • Webhook signatures use Svix-style HMAC-SHA256 with three headers (
    webhook-id
    , 
    webhook-timestamp
    , 
    webhook-signature
    ). The secret string starts with 
    whsec_
    — strip that prefix and base64-decode the remainder before HMACing. Signed content is 
    ${id}.${timestamp}.${raw_body}
    . Verify timestamp within 5 minutes to prevent replay.
  • Team/Business plans require 2-user minimum and cap at max 3 CRM users per domain. This is a common surprise when quoting small teams.
  • SDK 0.0.30 introduced breaking changes in both Python and TypeScript — if pinning an older version, consult 
    sdks/breaking-changes/*
    before upgrading.
  • Google Meet security flag: as of late 2025/early 2026 Google Meet flags Fathom's default bot mode as a security risk and may block it. Bot-free capture (native Zoom/Meet app integration) is the workaround.
基于2026年4月的研究整理 — 向客户报价前请确认定价层级限制和方案专属特性。
  • API密钥是用户级而非工作区级。管理员的密钥仅能查看自己的录音及团队共享录音 — 无法访问其他用户未共享的会议。若需团队级访问权限，需使用OAuth获取每个用户的授权，或列出团队成员并逐一获取授权。
  • OAuth应用无法在
    GET /meetings
    请求中使用
    include_transcript
    或
    include_summary
    查询参数    。必须通过
    GET /recordings/{recording_id}/transcript
    和
    GET /recordings/{recording_id}/summary
    分别获取这些内容。在管道设计中需考虑这一点 — OAuth集成需为每个会议额外发起1次API调用。
  • 创建Webhook时必须至少将
    include_transcript
    、
    include_crm_matches
    、
    include_summary
    或
    include_action_items
    中的一项设为
    true
    。空请求体将被拒绝。
  • 速率限制为每分钟60次调用，基于用户而非密钥。创建多个API密钥无法提升限制。批量回填数据时必须遵守该限制 — 对请求进行排队，并根据
    RateLimit-Reset
    请求头处理
    429
    错误。
  • Webhook签名采用Svix风格的HMAC-SHA256算法，包含三个请求头（
    webhook-id
    、
    webhook-timestamp
    、
    webhook-signature
    ）。密钥字符串以
    whsec_
    开头 — 在进行HMAC计算前需移除该前缀并对剩余部分进行base64解码。签名内容格式为
    ${id}.${timestamp}.${raw_body}
    。需验证时间戳在5分钟内，以防止重放攻击。
  • Team/Business方案要求至少2用户，且每个域名最多支持3个CRM用户。这是向小型团队报价时常见的意外限制。
  • SDK 0.0.30版本在Python和TypeScript中均引入了破坏性变更 — 若使用旧版本，升级前请查阅
    sdks/breaking-changes/*
    内容。
  • Google Meet安全标记：截至2025年末/2026年初，Google Meet已将Fathom默认机器人模式标记为安全风险并可能拦截。替代方案为无机器人录制（Zoom/Meet原生应用集成）。

Related skills

相关技能

  • /sales-note-taker
    — Picking a note-taker (Fathom vs Fireflies vs Avoma vs Gong vs Otter vs Fellow vs Grain vs Sembly vs Read.ai) and cross-vendor integration patterns
  • /sales-call-review
    — Review a specific Fathom recording and score against MEDDPICC/SPIN/Challenger
  • /sales-coaching
    — Use Fathom recordings in coaching programs, onboarding, certifications
  • /sales-integration
    — Zapier/Make/n8n workflows to move Fathom data to other tools
  • /sales-salesloft
    — Pair Fathom meetings with Salesloft cadence engagement
  • /sales-zoominfo
    — Alternative conversation intelligence via Chorus if Fathom doesn't fit
  • /sales-do
    — Not sure which skill to use? The router matches any sales objective to the right skill. Install: 
    npx skills add sales-skills/sales --skill sales-do -a claude-code -y
  • /sales-note-taker
    — 选择笔记工具（Fathom vs Fireflies vs Avoma vs Gong vs Otter vs Fellow vs Grain vs Sembly vs Read.ai）及跨厂商集成模式
  • /sales-call-review
    — 查看特定Fathom录音并根据MEDDPICC/SPIN/Challenger模型打分
  • /sales-coaching
    — 将Fathom录音用于辅导项目、入职培训、认证考核
  • /sales-integration
    — 搭建Zapier/Make/n8n工作流以将Fathom数据同步至其他工具
  • /sales-salesloft
    — 将Fathom会议与Salesloft节奏互动相结合
  • /sales-zoominfo
    — 若Fathom不符合需求，可通过Chorus使用ZoomInfo的对话智能方案
  • /sales-do
    — 不确定使用哪个技能？该路由可将任何销售目标匹配至合适的技能。安装命令：
    npx skills add sales-skills/sales --skill sales-do -a claude-code -y

Examples

示例

Example 1: Transcripts not arriving in Snowflake

示例1：记录未同步至Snowflake

User says: "I built a webhook receiver for Fathom but transcripts aren't showing up in Snowflake — webhooks hit but payload looks wrong" Skill does:
  1. Confirms webhook was created with 
    include_transcript=true
    (otherwise payload has no transcript body)
  2. Walks through HMAC verification (whsec_ prefix strip, signed content format, 5-min timestamp tolerance)
  3. Recommends a reconcile-poll pattern: daily 
    GET /meetings?created_after={yesterday}
    to catch any webhook deliveries that failed
  4. Flags the 60-req/min rate limit — if reconciliation fetches many transcripts, queue with 
    Retry-After
    Result: Correct webhook payload shape + reconcile-poll fallback so no transcripts get lost.
用户提问："我为Fathom搭建了Webhook接收器，但记录未显示在Snowflake中 — Webhook已触发但请求体看起来有问题" 技能处理：
  1. 确认创建Webhook时已设置
    include_transcript=true
    （否则请求体中无记录内容）
  2. 逐步讲解HMAC验证流程（移除whsec_前缀、签名内容格式、5分钟时间戳容忍度）
  3. 推荐对账轮询模式：每日调用
    GET /meetings?created_after={yesterday}
    以捕获任何交付失败的Webhook数据
  4. 提醒每分钟60次请求的速率限制 — 若对账需获取大量记录，需根据
    Retry-After
    进行请求排队 结果：修正Webhook请求体格式 + 对账轮询回退方案，确保无记录丢失。

Example 2: Multi-tenant app OAuth design

示例2：多租户应用OAuth设计

User says: "Building a SaaS that lets each customer connect their Fathom — do I use API keys or OAuth?" Skill does:
  1. Recommends OAuth (API keys are user-scoped and don't scale to multi-tenant)
  2. Lists the OAuth steps — register at 
    fathom.video/marketplace_applications/new
    , exchange code for tokens, implement 
    TokenStore
    with persistent storage (SQLite/Postgres/Redis), never use 
    newTokenStore()
    in production
  3. Flags that OAuth apps cannot use 
    include_transcript
    /
    include_summary
    on the 
    /meetings
    endpoint — must fetch per-recording, so plan for N extra calls per listing page
  4. Notes 
    public_api
    is currently the only OAuth scope Result: OAuth architecture plan with token storage, redirect URI, and N+1 call pattern for transcripts.
用户提问："我正在搭建一款SaaS产品，允许每个客户连接他们的Fathom — 应该使用API密钥还是OAuth？" 技能处理：
  1. 推荐使用OAuth（API密钥是用户级，无法扩展至多租户场景）
  2. 列出OAuth步骤 — 在
    fathom.video/marketplace_applications/new
    注册应用、交换代码获取令牌、实现带持久化存储的
    TokenStore
    （SQLite/Postgres/Redis），生产环境中切勿使用
    newTokenStore()
  3. 提醒OAuth应用无法在
    /meetings
    端点使用
    include_transcript
    /
    include_summary
    参数 — 必须按录音单独获取，因此列表页需额外发起N次调用
  4. 说明目前唯一可用的OAuth权限范围是
    public_api
    结果：包含令牌存储、重定向URI、记录获取N+1调用模式的OAuth架构方案。

Example 3: Free tier vs Premium vs Team

示例3：免费版 vs Premium版 vs Team版

User says: "We're 4 reps on Fathom free — what's the cheapest plan that gives us HubSpot sync?" Skill does:
  1. HubSpot sync requires Business tier ($34/user/mo, $25 annual)
  2. 4 reps × $25 annual = $100/mo (not $20/mo as the free tier suggests)
  3. Flags the 2-user minimum and max-3-CRM-users-per-domain caps
  4. Suggests Qualified Portfolio Program (if they're VC-backed) — up to 2 years free Result: Concrete monthly cost + applicable discount paths.
用户提问："我们有4个销售代表使用Fathom免费版 — 能支持HubSpot同步的最便宜方案是什么？" 技能处理：
  1. HubSpot同步仅Business版支持（每月每用户34美元，年付25美元）
  2. 4个代表 × 年付25美元 = 每月100美元（并非免费版显示的每月20美元）
  3. 提醒至少2用户的要求及每个域名最多3个CRM用户的限制
  4. 若为风投支持企业，建议申请合格投资组合项目 — 最长可免费使用2年 结果：明确的月度成本 + 适用的折扣路径。

Troubleshooting

故障排查

Webhook fires but signature verification fails

Webhook已触发但签名验证失败

Cause: Not stripping 
whsec_
prefix before decoding, or comparing raw bytes instead of base64-encoded strings Solution: 
base64.b64decode(secret.split('_')[1])
— HMAC the signed content 
${webhook-id}.${webhook-timestamp}.${raw_body}
(must be raw body, NOT JSON-parsed-and-re-serialized), base64-encode the digest, compare against each signature in the 
webhook-signature
header (strip version prefix 
v1,
first). Verify timestamp within 5 minutes.
原因：未在解码前移除
whsec_
前缀，或直接对比原始字节而非base64编码字符串 解决方案：使用
base64.b64decode(secret.split('_')[1])
— 对签名内容
${webhook-id}.${webhook-timestamp}.${raw_body}
进行HMAC计算（必须使用原始请求体，而非JSON解析后重新序列化的内容），对摘要进行base64编码，与
webhook-signature
请求头中的每个签名对比（需先移除版本前缀
v1,
）。验证时间戳在5分钟内。

429 Too Many Requests
during bulk backfill

批量回填时出现
429 Too Many Requests
错误

Cause: Exceeding the global 60 calls/minute per-user rate limit Solution: Read the 
RateLimit-Remaining
and 
RateLimit-Reset
headers on every response. Queue requests at 1/second (max sustainable). For OAuth apps fetching N meetings + N transcripts + N summaries, that's 3N calls — budget accordingly. Adding more API keys to the same user account doesn't help (limit is user-based, not key-based).
原因：超出了每个用户每分钟60次调用的全局速率限制 解决方案：在每次响应中读取
RateLimit-Remaining
和
RateLimit-Reset
请求头。按每秒1次的频率对请求进行排队（最大可持续速率）。对于需获取N个会议 + N条记录 + N个摘要的OAuth应用，共需3N次调用 — 需提前规划调用量。为同一用户创建多个API密钥无法解决问题（限制基于用户而非密钥）。

OAuth app transcripts are empty

OAuth应用获取的记录为空

Cause: OAuth apps cannot use 
include_transcript=true
on 
GET /meetings
— the field silently returns null Solution: After listing meetings, fetch transcript per recording with 
GET /recordings/{recording_id}/transcript
. Same for summary — use 
GET /recordings/{recording_id}/summary
. Both endpoints support async mode via 
destination_url
query param, which POSTs the result to your URL instead of returning inline (useful for large backfills that would otherwise time out).
  • Self-improving: If you discover something not covered here, append it to 
    references/learnings.md
    with today's date.
原因：OAuth应用无法在
GET /meetings
请求中使用
include_transcript=true
参数 — 该字段会默认返回null 解决方案：列出会议后，通过
GET /recordings/{recording_id}/transcript
按录音单独获取记录。摘要同理 — 使用
GET /recordings/{recording_id}/summary
。两个端点均支持通过
destination_url
查询参数启用异步模式，该模式会将结果POST至你的URL而非直接返回（适用于可能超时的大规模回填任务）。
  • 自我优化：如果发现此处未覆盖的问题，请将其添加至
    references/learnings.md
    并标注今日日期。