下載通話錄音

開始之前

請使用具備 recordings:read 的伺服器端 API 金鑰。這個權限範圍與 calls:read 彼此獨立，且只有在組織管理員為您的組織開通錄音功能後，建立金鑰的表單上才會出現這個選項；如何為新金鑰加上這個權限，請參閱身分驗證與權限範圍。

列出錄音

呼叫 GET /recordings。回應涵蓋組織在兩張通話資料表中的所有錄音，依錄音時間由新到舊排序。

curl --request GET 'https://api.brightalk.ai/recordings?limit=20' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16"

const response = await fetch("https://api.brightalk.ai/recordings?limit=20", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
    "Brightalk-Version": "2026-07-16",
  },
});
console.log(response.status, await response.json());

import os
import requests

response = requests.request(
    "GET",
    "https://api.brightalk.ai/recordings?limit=20",
    headers={
    "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
    "Brightalk-Version": "2026-07-16",
    },
)
print(response.status_code, response.json())

加上 include=download_url，即可在同一個回應中為每一列核發簽名網址—— 當您準備大量抓取多筆錄音、想省下每一列額外一次請求時，這是正確的做法。省略此參數則只取得較輕量的中繼資料頁面。在這個操作中，expires_in 只有搭配 include=download_url 才有意義；若只傳入 expires_in 卻沒有 include，會直接收到 400 validation_error，而不是被靜默忽略——因為一個看似生效、實際上沒有作用的設定，比明確報錯還糟糕。

完整同步錄音

recorded_at 是通話發生的時間，不是該列的 download_url 變得可查詢的時間。若某筆錄音的網址是在通話結束很久之後才寫入——例如錄音補件、重跑，或人工修復——寫入時間可能已經晚於您同步游標經過的位置，增量同步就再也看不到它了。這是實際量測出來的限制，不是假設性的風險，因此契約分成兩層。

增量同步——best-effort

記錄您上次同步成功的時間。下次執行時，呼叫 GET /recordings?created_after=<上次同步時間 − 24 小時>，並依 id 去除您已經有的資料。這 24 小時的重疊窗口涵蓋了絕大多數情況——依 production 實測，通話結束超過六小時才寫入錄音網址的情形極為罕見—— 但涵蓋不到很久以後才修復的錄音。這個做法很便宜，可以想跑多頻繁就跑多頻繁。

全量對帳——唯一保證完整的做法

定期不帶 created_after、走完整個游標，並依 id 與既有資料去重。這是唯一能保證拿齊所有錄音的方式，而且成本很低。這是 2026-09-01 針對我們整個平台量測的結果：約 32,261 筆錄音除以每頁 100 筆，大約是 323 次請求，在每分鐘 60 次請求的額度下遠遠少於六分鐘，而且每一次請求都只拉中繼資料，不會下載任何音訊位元組。這個總數是我們平台橫跨所有組織的加總，不是您組織自己的數字——真正能套用到您組織的是這個比例（每 100 筆錄音約一次請求），以及不論規模大小、全量走訪都只拉中繼資料這個事實。依錄音缺漏對您造成的成本，選擇每天或每週跑一次；不要只靠增量同步就宣稱資料已經完整。

只在真正要使用時才索取網址

curl --request GET 'https://api.brightalk.ai/recordings/22222222-2222-5222-9222-222222222222' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16"

const response = await fetch("https://api.brightalk.ai/recordings/22222222-2222-5222-9222-222222222222", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
    "Brightalk-Version": "2026-07-16",
  },
});
console.log(response.status, await response.json());

import os
import requests

response = requests.request(
    "GET",
    "https://api.brightalk.ai/recordings/22222222-2222-5222-9222-222222222222",
    headers={
    "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
    "Brightalk-Version": "2026-07-16",
    },
)
print(response.status_code, response.json())

GET /recordings/{recording_id} 一律會附上 download_url，不需要 include 參數。若您是在自家產品中內嵌播放器，請在使用者按下播放鍵的那一刻才索取這個網址，而不是在錄音列表頁面載入時就先取得。網址預設存活 900 秒（可用 expires_in 覆寫為 60 至 3600 秒之間的數值）；頁面若開啟得比這更久，原本拿到的網址就會在使用者還沒按下播放前悄悄失效。

撤銷存取權不會讓已核發的網址失效

動作	對 `GET /recordings` 的影響	對已核發 `download_url` 的影響
從金鑰移除 `recordings:read`	立即回傳 `403`	不受影響，會持續有效直到到期
刪除或停用該把 API 金鑰	立即回傳 `401`	不受影響，會持續有效直到到期
關閉組織的錄音存取功能	立即回傳 `403`	不受影響，會持續有效直到到期

這是簽名網址這套機制本身的性質，不是疏漏：網址本身就是憑證，一旦核發出去，就不會再回頭檢查原本核發它的金鑰是否仍然有效。殘留的有效期正好等於核發當下的 expires_in——最長一小時，預設 15 分鐘。若客戶誤以為撤銷會讓已核發的連結立刻失效，就會做出錯誤的安全性判斷；請以到期時間規劃，而不是以撤銷動作規劃。

開始使用

API 基礎

核心概念

操作指南

發布資訊

API 參考

開始之前

列出錄音

完整同步錄音

增量同步——best-effort

全量對帳——唯一保證完整的做法

只在真正要使用時才索取網址

撤銷存取權不會讓已核發的網址失效

​開始之前

​列出錄音

​完整同步錄音

​增量同步——best-effort

​全量對帳——唯一保證完整的做法

​只在真正要使用時才索取網址

​撤銷存取權不會讓已核發的網址失效

開始之前

列出錄音

完整同步錄音

增量同步——best-effort

全量對帳——唯一保證完整的做法

只在真正要使用時才索取網址

撤銷存取權不會讓已核發的網址失效