> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 下載通話錄音

> 完整同步每一筆錄音、只在真正需要時才索取下載網址，並正確處理撤銷情境。

## 開始之前

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

## 列出錄音

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

<CodeGroup>
  ```curl theme={null}
  curl --request GET 'https://api.brightalk.ai/recordings?limit=20' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16"
  ```

  ```javascript theme={null}
  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());
  ```

  ```python theme={null}
  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())
  ```
</CodeGroup>

加上 `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 筆錄音約一次請求），以及不論規模大小、全量走訪都只拉
中繼資料這個事實。依錄音缺漏對您造成的成本，選擇每天或每週跑一次；
不要只靠增量同步就宣稱資料已經完整。

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

<CodeGroup>
  ```curl theme={null}
  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"
  ```

  ```javascript theme={null}
  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());
  ```

  ```python theme={null}
  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())
  ```
</CodeGroup>

`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 分鐘。若客戶
誤以為撤銷會讓已核發的連結立刻失效，就會做出錯誤的安全性判斷；請以
到期時間規劃，而不是以撤銷動作規劃。