通話錄音 API 怎麼下載？短效網址與全量對帳指南

TL;DR — 通話錄音 API 要分三線：Brightalk 臨用才核發短效網址；續傳先驗證 206；增量不等於完整，仍要全量對帳。

先做一個事件演練：假設資安同事凌晨 2 點停用一把外洩的 API 金鑰，幾分鐘前核發的錄音網址卻仍能下載。

這不一定是撤銷失敗。短效網址本身就是一張臨時通行證；撤銷原金鑰會使該金鑰後續的版本化 API 請求失敗，也會阻止再核發錄音網址，但撤銷動作本身不會撤回已核發網址。真正安全的串接不能只問「網址多久過期」，還要回答斷線後怎麼續傳、遲到的錄音怎麼補，以及誰能把檔案留在自家雲端。

如果你還在規劃通話建立、冪等鍵與 webhook，先讀 AI 電話 API 串接指南。本文只處理二進位音檔；逐字稿與摘要的分頁一致性，另見通話摘要與逐字稿 API 指南。

Brightalk 的解法：通話錄音 API 三條控制線

控制線	核心做法	最容易漏掉的驗收
授權	列表只取中繼資料，播放或下載前才取短效網址	網址不得進日誌或長期資料庫
位元組	Range 回應先落到獨立尾段檔，驗證後才接回	200、206 與非成功回應必須分流
完整性	頻繁增量加週期性全量重跑，全部依 recording_id 去重	一次全量遍歷不是跨頁快照

這三條線要分開告警、分開重跑。把大檔下載塞進 CRM 的主要工作流程，任何一次來源逾時都可能拖住後續任務；需要編排逐字稿或待辦時，可讓工作流程自動化接事件，但音檔搬運仍由獨立下載服務處理。

量化效果也很直接：100 筆列表若預先帶網址，就同時核發 100 張臨時憑證；臨用才取，當下只核發真正需要的那一張。把 TTL 從 3600 秒降到 60 秒，單張網址的最長暴露窗口會縮成六十分之一；這是時間上限的算術，不是事故機率或資安成效保證（下載錄音指南，查核 2026-09-03）。

控制線一：列表不帶通行證，下載才臨時核發

Brightalk 的 GET /recordings 預設只列中繼資料；GET /recordings/{recording_id} 才回傳新的 download_url。兩者都需要獨立的 recordings:read，calls:read 不會順便放行錄音（身分驗證文件，查核 2026-09-03）。

既有金鑰不會自動取得這個權限，而且 scope 不能事後修改。做法是建立含完整權限的新金鑰，短暫並行驗證，切完流量後再撤銷舊金鑰。金鑰只放伺服器端，不能交給瀏覽器、行動 App 或共享試算表。

列表預設每頁 20 筆，上限 100 筆，以 next_cursor 翻頁。同步時至少保存 id、recorded_at、call_id、contact_id、duration_seconds 與 media_type；其中 call_id、contact_id、duration_seconds 都可能是 null。請用 id upsert 中繼資料列，不要拿 call_id 當唯一鍵（錄音資源模型）。

單筆網址預設有效 900 秒，expires_in 可設 60 至 3600 秒。它是 bearer credential，原則是只留完成當次傳輸所需的時間。大量匯出可用 include=download_url 讓一頁每列都帶網址，但前提是批次下載服務會立刻消耗整頁；若等待使用者逐筆點擊，仍應走單筆端點。列表若只送 expires_in、沒有搭配 include=download_url，會收到 400 validation_error（下載錄音指南，查核 2026-09-03）。

⚠️ 短效網址就是憑證。不要把完整網址寫進應用日誌、錯誤追蹤或長期資料庫。

列表出現一筆中繼資料，也不代表音訊此刻一定存在。是否拿得到位元組，要等真正下載時才知道。二進位落地可把 recording_id 當物件鍵，先寫暫存物件，驗證完成後再留下單一完成標記；中繼資料 upsert 本身不會阻止兩個下載程式同時寫檔。

控制線二：Range 先收尾段，絕不直接覆寫半檔

Brightalk 會把客戶端的 HTTP Range 請求轉送到錄音來源，但最終是否支援仍由來源決定；不能保證每次都回 206。先把 recording.part 已確認落地的實際大小記成 N，再送 Range: bytes=N-；以下用 N＝5242880 示範，回應標頭與尾段另存兩個檔案：

curl --silent --show-error --location \
  --header 'Range: bytes=5242880-' \
  --dump-header recording.tail.headers \
  --output recording.tail \
  "$DOWNLOAD_URL"

這條指令還沒有完成續傳。解析器必須先檢查：

• 206：Content-Range 起點必須正好是 5242880，才把 recording.tail 接到原半檔。
• 200：來源忽略 Range；把尾段檔視為完整回應，從零取代原半檔，不能 append。
• 非 2xx：保留錯誤本文供程式判讀，絕不接進 MP3。現行公開路由會把無效範圍等其他上游失敗統一映射為 502 upstream_unavailable，不會把來源的 416 原樣交給客戶端。

Accept-Ranges: bytes 只是能力提示，不是下一次一定回 206 的保證（RFC 9110 第 14 節）。完成後至少核對長度、內容型別與 recording_id；高風險保存流程再計算自己的雜湊。

控制線三：增量抓速度，全量重跑抓漏檔

recorded_at 代表通話發生時間，不是音訊來源何時補齊。昨天的通話可能今天才補上錄音，只查「上次之後」就會越過它。

頻繁增量： 以 created_after=上次成功時間−24 小時 重疊掃描，依 recording_id 去重。24 小時只是官方建議的 best-effort 起點，不是保存期限，也不是完整性承諾。

週期全量： 不帶 created_after，從第一頁走到 next_cursor=null，再把 ID 與你方的中繼資料、下載狀態及刪除紀錄比對。Brightalk 的公開指南把這種全量重跑列為發現任意晚到錄音的必要基準（完整同步契約，查核 2026-09-03）。

✅ 24 小時重疊是速度策略，不是完整性證明；完整性要靠週期重跑、ID 去重與差異追查。

仍要注意：游標遍歷沒有跨頁快照隔離。掃描期間若新增資料，同一輪不能宣稱「保證完整」；要週期性重跑、以 recording_id 去重，並追查每輪差異。客服抽查可以每天增量、每週全量；金融或醫療等受管制情境，交由法遵按漏檔成本與契約縮短週期。

錯誤與撤銷：先判斷能不能重試

HTTP 與錯誤	判斷	動作
403 invalid_link	網址無效或過期	重新驗證操作者，再核發新網址
404 not_found	此組織查不到錄音	停止本次請求，查 ID 與權限脈絡
410 media_unavailable	來源確認音訊不存在	停止自動重試，建立缺檔事件
502 upstream_unavailable	上游失敗的統一結果，也可能是無效 Range	有限次退避；仍失敗就核發新網址並改做完整下載
503 來源或服務設定錯誤	多半可修復	保留工作、退避重試並告警

每次重試都綁回同一個 recording_id，並重新核發網址。版本化中繼資料 API 可記回應的 request_id；簽名下載回應沒有平台 request_id，請由你方建立 correlation ID。日誌只記 ID、HTTP 狀態、錯誤代碼與嘗試次數，不要記完整 URL（錯誤碼文件）。

撤銷時，請先換發一把權限較窄的新金鑰、切換整合服務，再撤銷舊金鑰。這些動作本身不會撤回已核發網址；其殘留窗口最長可到當次 expires_in，上限 3600 秒。不過來源檔、簽章祕密或上游服務若另有變化，網址也可能提早失敗，因此不能反向承諾它一定活到到期。事件期間先停止新核發、暫停批次下載，並把最近一個最長窗口內的網址視為可能暴露。

台灣團隊怎麼定保存與調閱責任？

「能不能錄音」與「錄完怎麼利用、保管」不是同一題。前者涉及通訊保障及監察法等情境判斷；本文不代替法務下結論。後者可先由工程、資安、法遵與客戶資料責任人填完這張矩陣：

「應於蒐集之特定目的必要範圍內為之。」——個人資料保護法第 20 條

必填欄位	決策問題	建議負責人	留下的證據
目的與資料類別	為何保存？包含姓名、電話、健康或財務內容嗎？	客戶資料責任人＋法遵	處理活動紀錄、告知版本
保存期限與依據	目的、契約、產業規範各要求多久？	法遵＋業務負責人	期限表、法規／契約連結
儲存位置與調閱角色	檔案在哪一區域？哪些職務可取用？	資安＋工程	權限清單、存取日誌
刪除與驗證	期限到後如何刪除主檔、暫存與備份？	工程＋資安	刪除工作紀錄、抽驗結果
例外與事故	誰能核准訴訟保全或延長保存？誰值班？	法遵主管＋資安值班	核准單、事件時間軸

沒有一個跨產業通用的錄音保存年限，不能由工程師自行填數字。個資會籌備處也說明，2025 年公布的新修條文在行政院指定施行日前尚未生效，現階段仍依現行有效規定辦理（個資法修法問答集，查核 2026-09-03）。可搭配台灣 AI 電話合規地圖與個資合規功能完成法律盤點。

上線前八項驗收

• 整合工程： 用 recording_id 去重，允許三個可為 null（空值）的欄位；證據是重跑同頁不新增資料列。
• 後端工程： 金鑰只在伺服器端，列表預設不核發網址；證據是瀏覽器與應用日誌都找不到金鑰、完整 URL。
• 下載工程： 以獨立尾段檔驗證 200、206 與非成功回應；證據是中斷測試後雜湊一致。
• 可靠性負責人： 410 結案，502 有限次退避後改做完整下載，可修復的 503 保留工作；證據要寫明重試上限、總時間窗口、超限後告警對象與演練結果。
• 資料工程： 增量有重疊，全量從第一頁週期重跑；證據是刻意漏掉的錄音能在下一輪補回。
• 資安： 已演練換鑰與最長 3600 秒殘留窗口；證據是核發停止時間與調查範圍。
• 法遵： 保存矩陣每欄都有依據、負責人與核准者；證據是可追溯版本。
• 放行人： 確認上述七項全數通過；任何一項失敗就退回對應負責人，不帶例外上線。

常見問題

通話錄音 API 需要哪個權限？

需要 recordings:read，它和 calls:read、transcripts:read 分開。既有金鑰不會自動取得，請建立替代金鑰後輪替。

下載網址可以存進資料庫下次再用嗎？

不建議。網址短效且本身就是憑證；保存 recording_id 與下載狀態，真正使用時再核發。

錄音下載中斷，可以直接接回原檔嗎？

不能先接。尾段要寫到獨立檔，只有 206 且 Content-Range 起點正確時才能 append；200 要從零取代。

每天做增量同步，為什麼仍會漏錄音？

因為通話時間不等於來源補齊時間。增量只能降低風險；週期全量重跑加 ID 去重，才能持續找出晚到資料。

API 金鑰撤銷後，舊網址會立刻失效嗎？

不會因撤銷動作本身立刻失效，須把已核發 TTL 納入事故窗口；但其他來源或服務變化仍可能讓它提早失敗。

錄音存進自家雲端後，要保留多久才合法？

沒有跨產業通用答案。請按利用目的、客戶契約、產業規範、例外保全與刪除驗證逐案定義，再由法遵核准。

結語：不是搬到另一個儲存空間，而是留下三條證據線

Brightalk 已把中繼資料、短效授權、Range 與錯誤狀態拆成可組合的契約。團隊還要把它接成三條可驗證的線：誰取得通行證、哪些位元組完整落地、哪一次全量重跑找回了晚到錄音。

錄音只是 AI 電話營運的一層證據；可回到台灣 AI 智能電話行銷完整指南，把錄音、逐字稿、任務與人工接手放回同一張治理地圖。

最後，把 AI 電話錄音與轉錄品質 RFP 指南帶進供應商評估，也可查看 Brightalk 的 AI 語音客服功能與方案費率。當工程、資安、法遵與客戶資料責任人都能用同一個 recording_id 對話，才算從「有檔案」走到「有控制」。