> ## 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.

# 通話錄音

> 了解錄音資源、其可為 null 的欄位，以及簽名下載網址。

一筆錄音會將某通電話的音訊中繼資料，搭配一個短效的簽名下載網址一起提供。`GET /recordings` 與 `GET /recordings/{recording_id}` 涵蓋組織曾經撥打過、且留有錄音的每一通電話——包括從儀表板撥出、由非 API 觸發的自動化撥出，或屬於批次的通話——不只限於透過公開 API 建立的通話。

## 資源模型

| 類別 | 欄位                                               |
| -- | ------------------------------------------------ |
| 識別 | `id`、`call_id`（可為 null）、`contact_id`（可為 null）    |
| 時間 | `recorded_at`                                    |
| 音訊 | `duration_seconds`（可為 null）、`media_type`         |
| 下載 | `download_url`（選用）、`download_url_expires_at`（選用） |

`id` 是由底層通話資料列推導而來，且保持穩定：同一筆錄音無論查詢幾次，`id` 永遠相同。請將此資源上的所有識別碼都視為不透明值。

## 為什麼 `call_id` 可能是 null

只有在該通電話是透過公開 API 建立時，`call_id` 才會有值；此時它就是[通話](/zh-Hant/concepts/calls)中所述的同一個通話 `id`，可用來查詢該通電話自己的摘要與逐字稿。若該通話從來不是由公開 API 建立——例如來自儀表板撥號、非 API 觸發的自動化，或早於此資源存在的批次——則 `call_id` 為 `null`。`call_id` 為 `null` 是正常狀況，不是錯誤；對於已經營運一段時間的組織，多數錄音其實都沒有 `call_id`。

`contact_id` 也是基於相同原則：只要該筆錄音沒有連結任何聯絡人（例如來自未知號碼的進線、人工撥號，或聯絡人在通話後才被刪除），就會是 `null`。少數錄音的 `duration_seconds` 也會是 `null`。請將這三個欄位都當作可為 null 來解析，不要假設它們一定存在。

## 沒有 status 欄位

錄音資源沒有 `status` 或 `reason` 欄位。`GET /recordings` 傳回的每一列，依定義本來就查詢得到中繼資料；至於音訊位元組現在是否真的抓得到，只有實際執行下載那一步才知道答案，並不是靠列表或單筆回應上的某個旗標。

## 簽名下載網址

`download_url` 會在傳回它的那次請求當下才核發，伺服器端不會儲存，也不會有兩次核發出現相同的值。預設存活 900 秒，可用 `expires_in` 覆寫為 60 至 3600 秒之間的任一數值。請將這個值視為不透明：直接用一般的 HTTP 用戶端抓取即可，不要嘗試解析、重組或快取其結構。

如何完整同步錄音、什麼時候該索取網址，以及撤銷存取權後既有核發的網址會發生什麼事，請參閱[下載通話錄音](/zh-Hant/guides/download-call-recordings)。