# 身分驗證與權限範圍
Source: https://docs.brightalk.ai/zh-Hant/authentication

安全地使用 bearer API 金鑰與最小必要權限範圍。

Brightalk REST API 以 bearer API 金鑰驗證伺服器對伺服器的請求。金鑰會決定請求所屬的組織，以及可執行的操作。

## 傳送 bearer 金鑰

每個請求都必須在 `Authorization` 標頭傳送金鑰。語法必須完全符合：`Bearer`、一個空格，再接金鑰。

```http theme={null}
Authorization: Bearer $BRIGHTALK_API_KEY
```

缺少 bearer 標頭或格式錯誤時會傳回 `401 authentication_required`。語法正確、但找不到或已撤銷的金鑰，則傳回 `401 invalid_api_key`。

## 建立及保存金鑰

請在 [Brightalk API 設定](https://www.brightalk.ai/settings/integrations/api)建立 `bt_live_` 金鑰。完整金鑰只會顯示一次；請直接複製到伺服器端金鑰管理工具，切勿放進版本控制、日誌、瀏覽器儲存空間、行動裝置程式碼或傳送給客戶端的環境變數。

需要時請選擇到期日。超過到期日的金鑰會傳回 `401 api_key_expired`。撤銷會對後續請求生效；若懷疑金鑰外洩或暫時測試已完成，應立即撤銷。

## 選擇最小必要權限範圍

每個操作都會檢查權限範圍，且預設拒絕未授權操作。寫入或執行權限不包含相對應的讀取權限，讀取權限也不包含寫入權限。

| 資源                                                       | 讀取權限範圍                            | 寫入或執行權限範圍         |
| -------------------------------------------------------- | --------------------------------- | ----------------- |
| 代理目錄（`GET /agents`）                                      | `calls:read` **或** `batches:read` | —                 |
| 聯絡人                                                      | `contacts:read`                   | `contacts:write`  |
| 通話                                                       | `calls:read`                      | `calls:write`     |
| 通話逐字稿（`GET /calls/{call_id}/transcript`）                 | `transcripts:read`                | —                 |
| 批次                                                       | `batches:read`                    | `batches:write`   |
| 自動化                                                      | `automations:read`                | `automations:run` |
| 通話錄音（`GET /recordings`、`GET /recordings/{recording_id}`） | `recordings:read`                 | —                 |

`GET /agents` 是目錄的例外：`calls:read` 或 `batches:read` 任一權限即可通過驗證（`anyOf`）。只有在伺服器需要建立或啟動工作，並接著查詢工作時，才選取同一資源的兩項權限。這只是方便整合的建議配對，不表示兩個權限範圍會彼此隱含。

`calls:read` 可讀取通話中繼資料與摘要，但不包含完整逐字稿內容。呼叫 `GET /calls/{call_id}/transcript` 前必須明確授予 `transcripts:read`；既有金鑰不會自動取得這項權限。`recordings:read` 也適用相同規則：它與 `calls:read` 彼此獨立，既有金鑰同樣不會自動取得這項權限。

## 安全地輪替及撤銷

先建立只具最小必要權限範圍的替代金鑰，更新伺服器端金鑰並確認替代金鑰能成功請求，再撤銷舊金鑰。兩把金鑰重疊有效期間都不可暴露。輪替不會改變資源歸屬，也不會繞過既有的冪等性宣告。

這也是既有整合唯一能新增權限範圍的方式。`PATCH` 只會更新金鑰名稱，沒有任何端點可以修改既有金鑰的權限範圍。若要開始使用 `recordings:read`（或任何金鑰上還沒有的權限），請建立一把涵蓋所有所需權限（含新權限）的新金鑰，再依上述步驟輪替過去。

## 謹慎使用互動式 GET 測試工具

<Warning>
  在互動式 GET 測試工具輸入的金鑰會經過 Mintlify 代理伺服器。請使用暫時且僅具最小必要讀取權限的金鑰，不要加入寫入／執行權限，並在測試後立即撤銷。
</Warning>

寫入端點只提供可複製的範例，不提供互動式寫入控制。一般整合應由您的伺服器直接向 `https://api.brightalk.ai` 傳送所有請求。


# 可用性
Source: https://docs.brightalk.ai/zh-Hant/availability

確認公開 API 的可用功能與儀表板相依性。

若要開始使用公開 API，組織管理員必須在 [Brightalk API 設定](https://www.brightalk.ai/settings/integrations/api)建立具權限範圍的 API 金鑰，請求才能通過驗證。有效請求必須使用組織中仍有效的金鑰、文件支援的 API 版本與權限、符合資格的儀表板資源，以及受支援的目的地路由。

## 可用功能

* 在本文件所列欄位範圍內建立、查詢、列出及更新組織聯絡人。
* 列出符合資格的 AI 語音代理，以及儀表板管理的自動化摘要。
* 將立即執行的非同步 AI 通話加入佇列，並查詢、列出或取消。
* 為最多 1,000 位不重複收話人建立批次草稿；啟動或排程、查詢彙總狀態、暫停、繼續或取消。
* 從已啟用的自動化為一位聯絡人建立一次自動化執行；列出、查詢及取消該執行。
* 查詢本文件所列的純量狀態、接聽分類、結果、摘要、通話長度、時間戳記與批次彙總數量。
* 以 `calls:read` 取得具有獨立修訂版本的通話摘要，並以 `transcripts:read` 分頁讀取游標固定的逐字稿修訂版本。
* 以 `recordings:read` 分頁列出通話錄音，並取得短效下載網址。

只有 OpenAPI 契約中的操作與欄位屬於此可用性聲明的範圍。

## 儀表板相依性

* 在 Brightalk 設定中建立、設定到期、輪替及撤銷具權限範圍的 `bt_live_` 金鑰。
* 在儀表板設定及維護 AI 語音代理；API 目錄為唯讀。
* 在儀表板設定及啟用自動化；API 提供摘要與執行，不提供定義編輯。
* 執行前維持已驗證的目的地路由。

## 明確不支援的功能

以下功能目前不受支援：

* Brightalk SDK。
* 客戶 Webhook 傳送或重播。
* 沙箱或 dry-run 環境。
* API 日誌介面。
* 錄音的串流播放端點或永久網址。
* 僅播放預錄內容的通話。
* `/v1` 路徑。

此清單只說明目前邊界，不代表任何發布承諾。

## 定價與業務洽詢

API 使用方式依您的 Brightalk 組織所適用的商業條款為準。方案相關問題請參閱 [Brightalk 定價](https://www.brightalk.ai/pricing)或聯絡 Brightalk。


# 變更記錄
Source: https://docs.brightalk.ai/zh-Hant/changelog

追蹤 Brightalk REST API 契約與開發者文件的日期版本變更。

## 2026-09-01 — 通話錄音

* 新增 `GET /recordings` 與 `GET /recordings/{recording_id}`，涵蓋兩張通話資料表的錄音，不論該通話透過何種方式建立。
* 新增最小權限 `recordings:read` scope 與專用 `recording` 速率限制配額群組。
* 下載錄音採用依請求核發的短效簽名網址；撤銷金鑰、撤銷該權限範圍，或關閉組織對此資源的存取，都不會讓已核發的網址失效。

## 2026-07-28 — 版本化通話結果

* 新增 `GET /calls/{call_id}/summary` 與 `GET /calls/{call_id}/transcript`。
* 新增 `2026-07-28` 通話結果 payload schema，支援獨立修訂版本、處理狀態及游標固定的逐字稿分頁。
* 新增最小權限 `transcripts:read` scope 與專用逐字稿速率限制配額群組。

## 2026-07-22 — 新組織 API 存取

* 新組織預設可使用公開 API。
* 組織管理員在 Brightalk 設定中建立、輪替及撤銷具權限範圍的 API 金鑰；系統不會自動產生憑證。
* 此次推出未變更既有組織原本的 API 存取設定。

## 2026-07-16 — 公開 API 文件

* 發布日期版本的 OpenAPI 3.1 契約，以及結構一致的繁體中文與英文開發者文件。
* 說明伺服器對伺服器身分驗證、版本控制、冪等性、速率限制、穩定錯誤碼、聯絡人、符合資格的代理、立即 AI 通話、批次、儀表板管理的自動化，以及由 API 啟動的自動化執行。


# AI 語音代理
Source: https://docs.brightalk.ai/zh-Hant/concepts/agents

選取可供 REST API 執行 AI 通話的儀表板管理代理。

AI 語音代理定義單次通話與批次使用的對話行為。代理是在 Brightalk 儀表板中設定及管理。

## 符合資格的條件

`GET /agents` 只傳回組織擁有、且目前符合對外 AI 撥號資格的代理。符合資格表示代理已啟用、已設定供對外撥號使用、可開始處理通話，並與組織內已驗證且可用的對外撥號路由關聯。

此端點接受 `calls:read` 或 `batches:read` 任一權限，權限模式為 `anyOf`。單次通話整合通常使用 `calls:read`；僅使用批次撥號的整合則可用 `batches:read` 讀取同一份符合資格的代理目錄。

若清單中沒有某個代理，就不可使用該代理建立通話或批次。請重新列出目錄，不要無限期快取可用性。

## 唯讀目錄

REST API 僅提供精簡的選取資料：`id`、`name`、`description`、`language` 與 `availability`。傳回項目的 `availability` 為 `available`。本 API 無法建立或修改代理定義。

## 選取代理

將傳回的 `id` 作為 `POST /calls` 或 `POST /batches` 的 `agent_id`。請選擇語言與設定行為都適合收話人的代理。自動化會使用自身設定的代理，因此 `POST /automation-runs` 不接受 `agent_id`。


# 自動化
Source: https://docs.brightalk.ai/zh-Hant/concepts/automations

瞭解由儀表板管理的自動化及其 API 執行方式。

自動化由儀表板管理，定義要使用的代理、等待步驟、撥號行為、重試規則、分支流程與後續動作。REST API 只會列出摘要及建立自動化執行，不會在請求中重新定義這些行為。

## 選取已啟用的自動化

`GET /automations?status=active` 會傳回組織可見的摘要，包含 `id`、`name`、`description`、`status` 與 `input_fields`。請將傳回的 `id` 作為 `automation_id`。本 API 只提供唯讀目錄。

## 理解 `input_fields` 宣告

目前版本的宣告為空：

```json theme={null}
{
  "id": "atm_demo_001",
  "name": "Renewal follow-up",
  "description": "Calls one contact and records the outcome.",
  "status": "active",
  "input_fields": []
}
```

`input_fields` 為空時，請在 `POST /automation-runs` 省略 `input`，或只傳送 `{}`。不要傳送未宣告的名稱。

## 啟動執行

`POST /automation-runs` 接受一個對應至已啟用自動化的 `automation_id`，以及一個既有聯絡人或內嵌收話人資料。它不接受代理覆寫、時間覆寫、重試規則或分支選擇。回應是一個非同步的自動化執行 API 資源。

只有後續 API 回應傳回非空的 `input_fields` 宣告時，客戶端才能傳送其中明確列出的欄位。請以 API 傳回的宣告為準。

## 追蹤及取消

請查詢自動化執行，直到 `status` 進入終止狀態。同一個自動化與聯絡人的組合已有另一個仍在進行的自動化執行時，可能傳回 `409 duplicate_active_run`，並在安全的 `details` 中提供既有執行 ID。

取消會阻止排隊中的工作啟動，或在步驟之間將非終止狀態的自動化執行標記為 `cancelled`。取消不會中斷正在執行的步驟，外部效果仍採盡力而為。所有 API 狀態請參閱[狀態生命週期](/zh-Hant/concepts/status-lifecycle)。


# 批次撥號
Source: https://docs.brightalk.ai/zh-Hant/concepts/batches

瞭解草稿、排程與批次撥號控制流程。

批次會將最多 1,000 位不重複的收話人交由一個符合資格的 AI 語音代理處理，並提供整體執行狀態。

## 先建立草稿，再啟動

`POST /batches` 會建立 `status: draft`。只建立草稿不會開始撥號。請只提供一種收話人格式：`contact_ids` 或內嵌 `recipients`。

`POST /batches/{batch_id}/start` 是唯一能啟動或排程草稿的狀態轉換，並以 `202 Accepted` 傳回更新後的批次。

## 收話人識別與限制

批次必須包含 1–1,000 筆不重複的標準聯絡人紀錄。重複的聯絡人 ID 會遭拒絕。內嵌 `recipients` 會先依聯絡人採用規則解析；若兩筆內嵌識別資料解析至同一筆聯絡人紀錄，也視為重複。

## 排程與撥號時段

選用的 `schedule.start_at` 可設定工作最早符合執行資格的 RFC 3339 時間點。選用的 `schedule.calling_window` 則以 `time_zone`、不重複的 `weekdays`、`start_time` 與必須較晚的 `end_time`，定義一段連續的每日撥號時段。

批次啟動後，只有在 `start_at` 之後且位於該時段內，工作才符合執行資格。批次契約不提供多段每日時段或分支流程；需要這類行為時，請使用儀表板管理的自動化。

## 彙總資料與控制

批次資源會回報 `total_recipients`、`pending_recipients`、`queued_recipients`、`in_progress_recipients`、`completed_recipients`、`failed_recipients`、`cancelled_recipients`、`answered_recipients`、`no_answer_recipients` 與 `busy_recipients` 等彙總數量。請使用 `GET /batches/{batch_id}` 監看這些數量。

暫停會停止後續收話人派送，但不保證停止已進行的通話。繼續會將符合資格的剩餘收話人重新加入佇列。取消會停止剩餘工作，並以盡力而為方式要求取消進行中的子通話。有效狀態請參閱[狀態生命週期](/zh-Hant/concepts/status-lifecycle)。


# 通話
Source: https://docs.brightalk.ai/zh-Hant/concepts/calls

瞭解非同步 AI 通話資源及其結果。

一筆通話代表針對單一聯絡人立即執行的非同步 AI 語音工作。`POST /calls` 在工作持久加入佇列後傳回 `202 Accepted`，不會等待開始撥號或完成。

## 立即非同步執行

請求會選取一個符合資格的 `agent_id`，以及一個既有聯絡人或內嵌收話人資料。請求無法選擇排程時間；如需排程開始時間或撥號時段，請使用批次撥號；如需更複雜的時間控制，請使用由儀表板管理的自動化。

容量限制可能讓已接受的通話保持 `queued`。請使用 API 資源的 `id` 查詢通話，直到 `status` 進入終止狀態。

## 生命週期與接聽分類

`status` 說明執行為排隊中、進行中、已結束、失敗或取消。`answer_status` 則獨立將目的端分類為 `answered`、`no_answer`、`busy`、`voicemail` 或 `unknown`。

因此，正常的 `no_answer`、`busy` 或 `voicemail` 結果仍可搭配 `status: completed`。`failed` 僅用於服務無法安全執行的情況。完整模型請參閱[狀態生命週期](/zh-Hant/concepts/status-lifecycle)。

## API 純量結果

通話 API 資源只包含文件列出的純量欄位：

| 類別      | 欄位                                                                |
| ------- | ----------------------------------------------------------------- |
| 識別與來源關聯 | `id`、`contact_id`、`agent_id`、選用 `batch_id`、選用 `automation_run_id` |
| 狀態      | `status`、`answer_status`                                          |
| 基本結果    | 選用 `outcome`、`outcome_reason`、`summary`、`duration_seconds`        |
| 時間      | `queued_at`、`created_at`、`updated_at`，以及適用的撥號、接通、結束或取消時間戳記        |

請將 ID 視為不透明值；結果欄位在適用前可能不會出現。

如需具有修訂版本的通話後內容，請分別輪詢摘要與逐字稿。終止狀態及游標固定分頁方式請參閱[取得通話結果](/zh-Hant/guides/retrieve-call-results)。

## 取消

`POST /calls/{call_id}/cancel` 採盡力而為且具冪等性。若取消及早勝出，會阻止後續派送；若工作已啟動，則要求終止。完成競態仍可能讓最終 `status` 成為 `completed`；重複取消會傳回目前的通話資源，不會建立另一個動作。


# 聯絡人
Source: https://docs.brightalk.ai/zh-Hant/concepts/contacts

瞭解 REST API 中的聯絡人、API 資源識別碼與外部識別。

聯絡人是組織範圍內的標準聯絡人紀錄，供通話、批次與自動化執行共同使用。資源 ID 為不透明字串；請保存傳回的 `id`，不要從格式推論意義。

## 聯絡人參照

執行請求可接受既有的 `contact_id`，或以 `recipient` 提供內嵌收話人資料。內嵌收話人資料包含 `external_id`、`name` 與 `phone_number`，也可包含其他支援的聯絡人欄位。Brightalk 會將資料對應至一筆標準聯絡人紀錄，並在執行資源中傳回該 `contact_id`。

`external_id` 是呼叫端在 `source` 命名空間中管理的外部識別碼。請使用您系統內穩定的值，不要使用顯示名稱或會變更的電話標籤。

## 採用與衝突規則

建立或解析內嵌收話人資料時，Brightalk 會以原子方式套用以下規則：

1. 相符的外部識別會對應至既有的標準聯絡人紀錄。
2. 正規化後相符的電話號碼，只有在既有聯絡人沒有外部識別時，才能採用請求指定的外部識別。
3. 若該電話已屬於另一個非空的外部識別，請求會傳回 `409 contact_identity_conflict`，且不覆寫任一識別。
4. 其餘情況會以支援的欄位建立新聯絡人。

`POST /contacts` 建立新聯絡人時傳回 `201`；若傳回既有聯絡人或完成外部識別採用，則傳回 `200`。未知欄位會遭拒絕。

## 電話格式與組織隔離

`phone_number` 必須採用嚴格 E.164 格式：以 `+` 開頭、國碼不得為零，且總長度為 8–15 位數字。語法正確不保證組織已啟用該目的地；執行仍可能安全地失敗並傳回 `unsupported_destination`。

識別查詢、電話衝突與資源存取都依組織隔離。請求無法跨組織合併聯絡人，也無法透過請求欄位選擇組織。


# 通話錄音
Source: https://docs.brightalk.ai/zh-Hant/concepts/recordings

了解錄音資源、其可為 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)。


# 狀態生命週期
Source: https://docs.brightalk.ai/zh-Hant/concepts/status-lifecycle

區分通話、批次與自動化執行的 API 狀態。

只有 API 資源的 `status` 為非終止狀態時才需要查詢。終止狀態的資源仍可查詢，且不會再轉回進行中的工作。

## 通話 `status`

```mermaid theme={null}
flowchart LR
  queued --> dialing
  queued --> in_progress
  queued --> completed
  dialing --> in_progress
  dialing --> completed
  in_progress --> completed
  queued --> failed
  dialing --> failed
  in_progress --> failed
  queued --> cancelled
  dialing --> cancelled
  in_progress --> cancelled
```

| 狀態            | 是否終止 | 意義              |
| ------------- | ---- | --------------- |
| `queued`      | 否    | 已接受，正在等待派送或可用容量 |
| `dialing`     | 否    | 已開始撥號           |
| `in_progress` | 否    | 通話已接通且進行中       |
| `completed`   | 是    | 執行已結束，包含一般接聽結果  |
| `failed`      | 是    | 服務無法安全執行        |
| `cancelled`   | 是    | 取消在完成前勝出        |

圖中列出 API 可見狀態允許的轉換，不代表每筆資源都必須走過單一路徑。較晚抵達的回呼、背景工作程序更新或狀態校正作業，可能跳過中間的可觀測狀態，使 `queued` 或 `dialing` 直接進入 `in_progress` 或 `completed`。客戶端必須接受圖中任一轉換。`queued`、`dialing` 與 `in_progress` 都支援取消。

## 批次 `status`

```mermaid theme={null}
flowchart LR
  draft --> scheduled
  draft --> queued
  scheduled --> queued
  scheduled --> in_progress
  scheduled --> completed
  scheduled --> failed
  scheduled --> paused
  queued --> in_progress
  queued --> completed
  queued --> paused
  in_progress --> paused
  paused --> scheduled
  paused --> queued
  in_progress --> completed
  queued --> failed
  in_progress --> failed
  draft --> cancelled
  scheduled --> cancelled
  queued --> cancelled
  in_progress --> cancelled
  paused --> cancelled
```

| 狀態            | 是否終止 | 意義              |
| ------------- | ---- | --------------- |
| `draft`       | 否    | 已設定但尚未啟動        |
| `scheduled`   | 否    | 已啟動，正在等待符合排程條件  |
| `queued`      | 否    | 收話人已符合資格並排隊等待派送 |
| `in_progress` | 否    | 至少有部分收話人工作正在進行  |
| `paused`      | 否    | 後續派送已暫停         |
| `completed`   | 是    | 所有收話人工作都已取得終止結果 |
| `failed`      | 是    | 批次無法安全繼續        |
| `cancelled`   | 是    | 剩餘工作已取消         |

控制操作與圖示一致：啟動會將 `draft` 轉為 `scheduled` 或 `queued`；`scheduled`、`queued` 與 `in_progress` 都可暫停；繼續會依排程資格將 `paused` 轉回 `scheduled` 或 `queued`；所有非終止批次狀態都可取消。

這些轉換不代表單一路徑。較晚抵達的回呼、背景工作程序更新或狀態校正作業，可能跳過中間的可觀測狀態，依圖中連線將 `scheduled` 或 `queued` 直接推進至 `in_progress`、`completed` 或 `failed`。客戶端必須接受圖中每一種轉換，並只在進入終止狀態後停止查詢。

## 自動化執行 `status`

```mermaid theme={null}
flowchart LR
  queued --> running
  running --> waiting
  waiting --> running
  running --> completed
  waiting --> completed
  queued --> failed
  running --> failed
  waiting --> failed
  queued --> cancelled
  running --> cancelled
  waiting --> cancelled
```

| 狀態          | 是否終止 | 意義             |
| ----------- | ---- | -------------- |
| `queued`    | 否    | 已接受並等待開始       |
| `running`   | 否    | 自動化步驟正在執行或已可執行 |
| `waiting`   | 否    | 自動化正依其定義等待     |
| `completed` | 是    | 自動化執行正常結束      |
| `failed`    | 是    | 自動化執行無法安全繼續    |
| `cancelled` | 是    | 自動化執行在正常完成前遭取消 |

## `answer_status` 為獨立資訊

`answer_status` 屬於通話資源，並非生命週期狀態。其值可為 `answered`、`no_answer`、`busy`、`voicemail` 或 `unknown`。

| 通話結果        | 組合範例                                          |
| ----------- | --------------------------------------------- |
| 已接聽且正常結束    | `status: completed`、`answer_status: answered` |
| 未接聽、忙線或語音信箱 | `status: completed` 搭配相應的 `answer_status`     |
| 沒有接通證據的執行失敗 | `status: failed`、`answer_status: unknown`     |
| 接通後遭取消      | `status: cancelled`、`answer_status: answered` |

請一律先依 `status` 判斷是否停止查詢，再依 `answer_status` 解讀目的端行為。


# 錯誤
Source: https://docs.brightalk.ai/zh-Hant/errors

解析一致的 REST API 錯誤回應格式與請求識別碼。

每個非 2xx 回應都使用一致的 JSON 格式。請依穩定的 `error.code` 分類錯誤，不要依賴供人閱讀的 `message`。

## 錯誤回應格式

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The request could not be validated.",
    "request_id": "req_demo_001",
    "details": {
      "fields": [
        { "path": "recipient.phone_number", "code": "invalid_e164" }
      ]
    }
  }
}
```

`details` 為非必填且可供機器讀取的內容。客戶端應忽略 `details` 中的未知欄位。

## 請求關聯

每個回應都包含 `X-Request-Id` 標頭，錯誤內容也會在 `error.request_id` 重複同一值。請將該識別碼與失敗操作一起記錄，並在聯絡 Brightalk 支援時提供。不要記錄 API 金鑰或完整聯絡人資料。

您可以傳送 `X-Request-Id`，使用 1–64 個 `A-Z`、`a-z`、`0-9`、`.`、`_`、`:` 或 `-` 字元。若省略或傳送不合格式的值，Brightalk 會改用產生的識別碼。

## 身分驗證錯誤的差異

| 情況                                  | HTTP 狀態與錯誤碼                   |
| ----------------------------------- | ----------------------------- |
| 缺少 `Authorization`，或不符合精確 bearer 語法 | `401 authentication_required` |
| Bearer 語法正確，但金鑰不存在或已撤銷              | `401 invalid_api_key`         |
| 金鑰已過期                               | `401 api_key_expired`         |

這些回應只描述憑證是否可用，不會洩漏其他組織的資源。

## 狀態與錯誤目錄

| HTTP 狀態 | 穩定錯誤碼                                                                                                                         |
| ------: | ----------------------------------------------------------------------------------------------------------------------------- |
|   `400` | `unsupported_version`、`validation_error`、`invalid_json`、`unsupported_destination`、`idempotency_key_required`                  |
|   `401` | `authentication_required`、`invalid_api_key`、`api_key_expired`                                                                 |
|   `403` | `organization_not_enabled`、`insufficient_scope`、`recipient_blocked_by_policy`                                                 |
|   `404` | `resource_not_found`                                                                                                          |
|   `405` | `method_not_allowed`                                                                                                          |
|   `409` | `resource_state_conflict`、`contact_identity_conflict`、`idempotency_conflict`、`idempotency_in_progress`、`duplicate_active_run` |
|   `413` | `request_too_large`                                                                                                           |
|   `429` | `rate_limit_exceeded`                                                                                                         |
|   `500` | `internal_error`                                                                                                              |

對已知路徑使用不支援的方法時，回應也包含 `Allow`。適合等待後重試的情況會包含 `Retry-After`。錯誤回應絕不揭露實作名稱、內部資料內容、查詢細節或堆疊追蹤。

## 下載錄音的錯誤格式較單純，且與上述格式不同

`download_url` 回傳的簽名網址並不屬於上面這套有版本號的 JSON API——它由另一個不需要 API 金鑰的主機提供服務，請求失敗時回傳 `{"error": "<code>"}`，是一個純字串錯誤碼，沒有 `message`、`request_id`，也沒有 `details`。其中兩個錯誤碼帶有必須分開處理的意義：

| HTTP 狀態 | 錯誤碼                    | 意義                              | 應對方式            |
| ------: | ---------------------- | ------------------------------- | --------------- |
|   `503` | `source_access_denied` | 來源儲存空間拒絕存取，通常是我們這端暫時性、可復原的狀況。   | 退避後重試，不要放棄這筆錄音。 |
|   `410` | `media_unavailable`    | 來源儲存空間已確認該物件不存在，只有在確認之後才會回傳這個碼。 | 停止重試，此狀態為永久性。   |

請把這兩者視為相反的訊號，而不是同一種失敗的不同程度：`503` 代表稍後再試，`410` 代表位元組已永久消失。若同步程式把兩者都當成「放棄」處理，就會悄悄丟掉稍後其實抓得到的錄音。此網址的其他錯誤碼（`403 invalid_link`、`404 not_found`、`502 upstream_unavailable`、`503 server_configuration_error`）不帶有這種明確的重試／不重試意義，但 `502` 與 `503 server_configuration_error` 同樣可以退避後重試——兩者都代表問題出在我們這端，而不是對這筆錄音下了永久性的判斷。


# 建立並啟動批次
Source: https://docs.brightalk.ai/zh-Hant/guides/create-start-batch

建立批次草稿、啟動撥號並追蹤批次狀態。

批次撥號分為兩個步驟：建立草稿，再明確啟動。批次可包含 1–1,000 位不重複的收話人，每位收話人都會對應至一筆標準聯絡人紀錄。

## 事前準備

* 一把放在伺服器端，且具備 `batches:write` 與 `batches:read` 的 `bt_live_` 金鑰。
* 符合資格的 `agent_id`，以及相同組織內不重複的 `contact_ids` 或內嵌收話人資料。
* 建立及啟動批次各自使用的非機密冪等性金鑰。
* 若要排程，請使用契約支援的 RFC 3339 `start_at` 和／或一段連續的每日 `calling_window`。

請將 JavaScript 範例儲存為 `.mjs`，或在 ESM 專案中執行。範例最外層的 `await` 必須使用 ESM，且需使用 Node 18 以上版本提供的內建 `fetch`。

## 建立草稿

標準範例使用兩位既有聯絡人。建立後會傳回 `status: draft`，且不會開始撥號。

<Warning>
  啟動此批次可能對每位收話人撥打真實 PSTN 電話。啟動前，請確認完整收話人名單、代理、排程、撥號時段與時間。
</Warning>

<CodeGroup>
  ```curl theme={null}
  curl --request POST 'https://api.brightalk.ai/batches' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: createBatch-example-001" \
    --data '{"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]}'
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/batches", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createBatch-example-001",
    },
    body: JSON.stringify({"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]}),
  });
  console.log(response.status, await response.json());
  ```

  ```python theme={null}
  import os
  import requests

  response = requests.request(
      "POST",
      "https://api.brightalk.ai/batches",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createBatch-example-001",
      },
      json={"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]},
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

## 預期草稿

API 會以 `201 Created` 傳回彙總數量。請保存批次的 `id`。

```json theme={null}
{
  "id": "bat_demo_001",
  "name": "Renewal reminders",
  "agent_id": "agt_demo_001",
  "total_recipients": 2,
  "pending_recipients": 2,
  "queued_recipients": 0,
  "in_progress_recipients": 0,
  "completed_recipients": 0,
  "failed_recipients": 0,
  "cancelled_recipients": 0,
  "answered_recipients": 0,
  "no_answer_recipients": 0,
  "busy_recipients": 0,
  "created_at": "2026-07-20T01:00:00Z",
  "updated_at": "2026-07-20T01:00:00Z",
  "status": "draft"
}
```

繼續前，請檢查傳回的資源識別資料與數量。不要略過明確的啟動狀態轉換。

## 啟動批次

將 `bat_demo_001` 替換為傳回的 `id`。立即啟動時會傳回 `status: queued`；若已設定未來的符合資格時間，則可能傳回 `status: scheduled`。

<CodeGroup>
  ```curl theme={null}
  curl --request POST 'https://api.brightalk.ai/batches/bat_demo_001/start' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: startBatch-example-001" \
    --data '{}'
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/batches/bat_demo_001/start", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "startBatch-example-001",
    },
    body: JSON.stringify({}),
  });
  console.log(response.status, await response.json());
  ```

  ```python theme={null}
  import os
  import requests

  response = requests.request(
      "POST",
      "https://api.brightalk.ai/batches/bat_demo_001/start",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "startBatch-example-001",
      },
      json={},
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

啟動操作會傳回 `202 Accepted`。容量限制可能讓符合資格的收話人留在佇列；請監控彙總數量，不要將排隊視為錯誤。

## 查詢及控制

請沿用同一個批次 `id`，並保留必要的權限配對。

| 動作 | 端點                                | 下一個動作                                         |
| -- | --------------------------------- | --------------------------------------------- |
| 查詢 | `GET /batches/{batch_id}`         | 採退避方式查詢，直到 `completed`、`failed` 或 `cancelled` |
| 暫停 | `POST /batches/{batch_id}/pause`  | 停止後續派送；進行中的通話可能繼續                             |
| 繼續 | `POST /batches/{batch_id}/resume` | 將符合資格的剩餘收話人重新加入佇列                             |
| 取消 | `POST /batches/{batch_id}/cancel` | 停止剩餘工作，並以盡力而為方式要求取消進行中的工作                     |

暫停、繼續與取消可選用 `Idempotency-Key`。動作可能重試時，請使用此標頭。

## 常見錯誤

| 錯誤                        | 檢查項目                                                                    |
| ------------------------- | ----------------------------------------------------------------------- |
| `validation_error`        | 共有 1–1,000 位不重複的收話人、只使用一種收話人格式，且排程／撥號時段有效                               |
| `insufficient_scope`      | 金鑰具備控制所需的 `batches:write`，以及查詢所需的 `batches:read`                        |
| `resource_state_conflict` | 只啟動 `draft`、只暫停 `scheduled`、`queued` 或 `in_progress` 的工作，且請求的狀態轉換符合目前狀態 |
| `unsupported_destination` | 派送前已確認每個目的地都已啟用                                                         |
| `idempotency_conflict`    | 建立與啟動分別使用自己的穩定金鑰，且語意相同的請求內容未改變                                          |
| `rate_limit_exceeded`     | 等待數字 `Retry-After`；重試相同動作時保留相同金鑰                                        |


# 下載通話錄音
Source: https://docs.brightalk.ai/zh-Hant/guides/download-call-recordings

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

## 開始之前

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


# 撥打一通 AI 通話
Source: https://docs.brightalk.ai/zh-Hant/guides/place-one-call

建立一通非同步 AI 通話並查詢其結果。

此流程會將一通立即執行的非同步 AI 通話加入佇列。`POST /calls` 不會排程未來時間，也不會等待撥號完成。

## 事前準備

* 一把放在伺服器端，且具備 `calls:write` 與 `calls:read` 的 `bt_live_` 金鑰。
* 由 `GET /agents` 傳回的 `agent_id`，以及相同組織內既有的 `contact_id`。
* 此邏輯通話專用且不重複、非機密的 `Idempotency-Key`。

只有想透過聯絡人採用規則解析並保存標準聯絡人紀錄時，才以內嵌 `recipient` 取代 `contact_id`。

請將 JavaScript 範例儲存為 `.mjs`，或在 ESM 專案中執行。範例最外層的 `await` 必須使用 ESM，且需使用 Node 18 以上版本提供的內建 `fetch`。

## 建立通話

<Warning>
  此寫入操作可能撥打一通真實 PSTN 電話。送出前，請確認所選聯絡人、目的地、代理與時間。
</Warning>

<CodeGroup>
  ```curl theme={null}
  curl --request POST 'https://api.brightalk.ai/calls' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: createCall-example-001" \
    --data '{"agent_id":"agt_demo_001","contact_id":"con_demo_001"}'
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/calls", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createCall-example-001",
    },
    body: JSON.stringify({"agent_id":"agt_demo_001","contact_id":"con_demo_001"}),
  });
  console.log(response.status, await response.json());
  ```

  ```python theme={null}
  import os
  import requests

  response = requests.request(
      "POST",
      "https://api.brightalk.ai/calls",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createCall-example-001",
      },
      json={"agent_id":"agt_demo_001","contact_id":"con_demo_001"},
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

## 預期回應

API 會以 `202 Accepted` 傳回通話 API 資源。請保存其 `id` 供後續查詢。

```json theme={null}
{
  "id": "11111111-1111-4111-8111-111111111111",
  "contact_id": "con_demo_001",
  "agent_id": "agt_demo_001",
  "queued_at": "2026-07-20T01:00:00Z",
  "created_at": "2026-07-20T01:00:00Z",
  "updated_at": "2026-07-20T01:00:00Z",
  "status": "queued",
  "answer_status": "unknown"
}
```

容量不足時，已接受的通話可能保持 `queued`。接受請求不代表已撥號或目的端已接聽。

## 查詢通話

請以傳回的 `id` 取代範例 ID。`status` 為 `queued`、`dialing` 或 `in_progress` 時，採退避方式查詢。

<CodeGroup>
  ```curl theme={null}
  curl --request GET 'https://api.brightalk.ai/calls/11111111-1111-4111-8111-111111111111' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16"
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/calls/11111111-1111-4111-8111-111111111111", {
    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/calls/11111111-1111-4111-8111-111111111111",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      },
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

在 `completed`、`failed` 或 `cancelled` 時停止查詢。接著獨立判讀 `answer_status`，並讀取任何可用的 `outcome`、`outcome_reason`、`summary` 與 `duration_seconds`。

## 常見錯誤

| 錯誤                         | 檢查項目                                           |
| -------------------------- | ---------------------------------------------- |
| `insufficient_scope`       | 金鑰同時具備建立所需的 `calls:write`，以及查詢所需的 `calls:read` |
| `resource_not_found`       | 代理與聯絡人存在且對此組織可見，且傳回的通話資源 ID 未遭修改               |
| `unsupported_destination`  | 目的地採用有效 E.164，且組織已啟用該目的地                       |
| `idempotency_key_required` | 建立請求包含非空的 `Idempotency-Key`                    |
| `idempotency_conflict`     | 重複使用的金鑰具有語意相同的請求內容；若是新通話，請改用新金鑰                |
| `rate_limit_exceeded`      | 等待數字 `Retry-After` 後，以相同冪等性金鑰重試                |


# 取得通話結果
Source: https://docs.brightalk.ai/zh-Hant/guides/retrieve-call-results

分別輪詢摘要與逐字稿，並在同一個不可變逐字稿修訂版本中分頁。

## 開始之前

伺服器端 API 金鑰以 `calls:read` 取得摘要，以 `transcripts:read`
取得逐字稿。只有在整合需要兩種資源時才授予兩個 scope。既有金鑰不會
自動取得逐字稿權限。

## 輪詢摘要

呼叫 `GET /calls/{call_id}/summary`。尚未完成是正常狀態：HTTP 200、
`status: "processing"`、`poll_after_seconds: 5`。狀態成為 `ready`、
`unavailable` 或 `failed` 後停止輪詢。

<CodeGroup>
  ```curl theme={null}
  curl --request GET 'https://api.brightalk.ai/calls/11111111-1111-4111-8111-111111111111/summary' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16"
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/calls/11111111-1111-4111-8111-111111111111/summary", {
    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/calls/11111111-1111-4111-8111-111111111111/summary",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      },
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

## 輪詢逐字稿

呼叫 `GET /calls/{call_id}/transcript?limit=100`。摘要與逐字稿各自判定
是否就緒，不能用其中一個推論另一個。

<CodeGroup>
  ```curl theme={null}
  curl --request GET 'https://api.brightalk.ai/calls/11111111-1111-4111-8111-111111111111/transcript?limit=100' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16"
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/calls/11111111-1111-4111-8111-111111111111/transcript?limit=100", {
    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/calls/11111111-1111-4111-8111-111111111111/transcript?limit=100",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      },
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

## 沿用游標

`next_cursor` 非 null 時，下一個請求必須原樣送回。游標會固定逐字稿
修訂版本；較晚完成的對帳可以發布新修訂版本，不會改變正在讀取的舊頁面。
為了遵守回應大小上限，單頁輪次可能少於 `limit`；只有
`next_cursor` 為 null 才表示分頁完成。

## 偵測內容更新

儲存 `call_id`、端點名稱與 `revision`。較高的 revision 表示清理後的
端點內容已更新；相同內容的重投影不會增加 revision。

## 處理終止狀態

`unavailable` 表示這通電話無法產生該結果，可查看穩定的 reason。
`failed` 與 `processing_failed` 表示安全處理已耗盡。兩者都不是 HTTP
錯誤。


# 建立自動化執行
Source: https://docs.brightalk.ai/zh-Hant/guides/run-automation

為單一聯絡人建立並追蹤一次自動化執行。

此流程會選取由儀表板管理且已啟用的自動化，為一位聯絡人建立一次執行，並追蹤非同步自動化執行的 API 資源。

## 事前準備

* 一把放在伺服器端，且具備 `automations:run` 與 `automations:read` 的 `bt_live_` 金鑰。
* 一個組織可見且已啟用的自動化，以及一個既有聯絡人或內嵌收話人資料。
* 此次邏輯執行專用且不重複、非機密的 `Idempotency-Key`。
* 瞭解代理、等待步驟、重試規則與分支流程都由自動化定義，而不是由 API 請求決定。

## 選取已啟用的自動化

以 `automations:read` 列出摘要，再選擇 `status` 為 `active` 的項目。

請將 JavaScript 範例儲存為 `.mjs`，或在 ESM 專案中執行。範例最外層的 `await` 必須使用 ESM，且需使用 Node 18 以上版本提供的內建 `fetch`。

<CodeGroup>
  ```curl theme={null}
  curl --request GET 'https://api.brightalk.ai/automations?status=active&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/automations?status=active&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/automations?status=active&limit=20",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      },
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

目前版本的摘要沒有宣告可由 API 傳入的欄位：

```json theme={null}
{
  "data": [
    {
      "id": "atm_demo_001",
      "name": "Renewal follow-up",
      "description": "Calls one contact and records the outcome.",
      "status": "active",
      "input_fields": []
    }
  ],
  "next_cursor": null
}
```

## 啟動自動化執行

因 `input_fields` 為空，請如標準範例一樣省略 `input`，或只傳送 `{}`。

<Warning>
  啟動這次自動化執行可能會依儀表板管理的自動化定義撥打真實 PSTN 電話。送出此寫入操作前，請確認自動化、聯絡人、設定行為與時間。
</Warning>

<CodeGroup>
  ```curl theme={null}
  curl --request POST 'https://api.brightalk.ai/automation-runs' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: createAutomationRun-example-001" \
    --data '{"automation_id":"atm_demo_001","contact_id":"con_demo_001"}'
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/automation-runs", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createAutomationRun-example-001",
    },
    body: JSON.stringify({"automation_id":"atm_demo_001","contact_id":"con_demo_001"}),
  });
  console.log(response.status, await response.json());
  ```

  ```python theme={null}
  import os
  import requests

  response = requests.request(
      "POST",
      "https://api.brightalk.ai/automation-runs",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createAutomationRun-example-001",
      },
      json={"automation_id":"atm_demo_001","contact_id":"con_demo_001"},
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

只有 API 傳回非空的 `input_fields` 宣告時才能提供 `input`，而且只能傳送其中明確列出的欄位。

## 預期回應

API 會傳回 `202 Accepted`。請保存自動化執行 API 資源的 `id`。

```json theme={null}
{
  "id": "run_demo_001",
  "automation_id": "atm_demo_001",
  "contact_id": "con_demo_001",
  "input": {},
  "queued_at": "2026-07-20T01:00:00Z",
  "created_at": "2026-07-20T01:00:00Z",
  "updated_at": "2026-07-20T01:00:00Z",
  "status": "queued"
}
```

## 查詢及取消

| 動作 | 端點                                      | 下一個動作                                                                             |
| -- | --------------------------------------- | --------------------------------------------------------------------------------- |
| 查詢 | `GET /automation-runs/{run_id}`         | 在 `queued`、`running` 或 `waiting` 時採退避方式查詢；於 `completed`、`failed` 或 `cancelled` 停止 |
| 取消 | `POST /automation-runs/{run_id}/cancel` | 阻止排隊中的工作，或要求在執行步驟的邊界之間取消                                                          |

查詢需要 `automations:read`；取消需要 `automations:run`。取消可選用 `Idempotency-Key`，且對正在執行的步驟仍採盡力而為。

## 常見錯誤

| 錯誤                        | 檢查項目                                                         |
| ------------------------- | ------------------------------------------------------------ |
| `insufficient_scope`      | 金鑰具備啟動／取消所需的 `automations:run`，以及列出／查詢所需的 `automations:read` |
| `resource_not_found`      | 自動化與聯絡人屬於此組織且對此組織可見                                          |
| `resource_state_conflict` | 所選自動化為 `active`，且請求的狀態轉換符合目前執行狀態                             |
| `validation_error`        | `input_fields` 為空時，省略 `input` 或只傳送 `{}`                      |
| `duplicate_active_run`    | 使用安全 `details` 中的 `existing_run_id` 查詢既有且仍在進行的自動化執行          |
| `idempotency_conflict`    | 重複使用的金鑰具有相同自動化、聯絡人及語意相同的請求內容                                 |


# 冪等性
Source: https://docs.brightalk.ai/zh-Hant/idempotency

以 Idempotency-Key 安全地重試支援的寫入操作。

即使您的伺服器逾時，請求仍可能已成功。若改用新的冪等性金鑰重試，Brightalk 可能會重複建立同一通電話、同一個批次或同一次自動化執行。沿用相同的 `Idempotency-Key`，Brightalk 就能辨識這是同一個動作，並傳回原本的結果。

## 三個使用原則

1. **一個動作，一把金鑰。** 第一次送出請求前，先產生不重複且非機密的值。
2. **同一個動作，沿用同一把金鑰。** 在 24 小時內，若請求逾時、連線失敗，或回應明確要求重試（例如包含 `Retry-After`），請使用相同的 HTTP 方法、路徑、API 版本、語意相同的請求內容與金鑰重送。
3. **動作或內容改變，就換新金鑰。** 若 API 版本或請求內容不同，或您確實要再建立一通電話、另一個批次或另一次自動化執行，請使用新的金鑰。

以下僅節錄標頭，刻意省略必要的 JSON 請求內容與 `Content-Type` 標頭。

```bash theme={null}
curl --request POST 'https://api.brightalk.ai/calls' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16" \
  --header "Idempotency-Key: order-8f4c2-call-1"
```

請將 `order-8f4c2-call-1` 與這次業務動作一起保存。它不是驗證金鑰，但仍不可包含電話號碼、聯絡人資料或其他機密。

超過 24 小時後，請勿假設舊的冪等性宣告仍能防止重複執行。再次送出前，請先確認原本的動作是否已經執行。

## 哪些操作一定要使用

只有以下四個操作強制要求此標頭：

| 操作      | 路徑                               |
| ------- | -------------------------------- |
| 建立通話    | `POST /calls`                    |
| 建立批次    | `POST /batches`                  |
| 啟動批次    | `POST /batches/{batch_id}/start` |
| 建立自動化執行 | `POST /automation-runs`          |

省略標頭會傳回 `400 idempotency_key_required`。

## 哪些操作可選擇使用

狀態控制操作可選用此標頭；加入標頭後，即可重播已完成的結果：

| 操作      | 路徑                                      |
| ------- | --------------------------------------- |
| 取消通話    | `POST /calls/{call_id}/cancel`          |
| 暫停批次    | `POST /batches/{batch_id}/pause`        |
| 繼續批次    | `POST /batches/{batch_id}/resume`       |
| 取消批次    | `POST /batches/{batch_id}/cancel`       |
| 取消自動化執行 | `POST /automation-runs/{run_id}/cancel` |

## Brightalk 會傳回什麼

| 情況              | 結果                                                                       |
| --------------- | ------------------------------------------------------------------------ |
| 相同金鑰與語意相同的請求內容  | 傳回原始 HTTP 狀態與回應；已完成的結果重播包含 `Idempotency-Replayed: true`                  |
| 相同金鑰與不同請求內容     | `409 idempotency_conflict`                                               |
| 原始請求仍在處理時使用相同金鑰 | `409 idempotency_in_progress`，並包含以差值秒數（delta-seconds）表示的數字 `Retry-After` |

請等待 `Retry-After` 指定的時間後，再重試處理中的請求。驗證失敗不會儲存成已完成的冪等結果。

## 進階細節

冪等性宣告會保留 24 小時，其適用範圍由組織、API 金鑰類別、API 版本、HTTP 方法與正規化路徑共同決定。從一把 `bt_live_` 金鑰輪替到另一把金鑰，不會重設相同金鑰類別的宣告；輪替後重試同一邏輯請求時，請沿用原本的冪等性金鑰。


# Brightalk API 簡介
Source: https://docs.brightalk.ai/zh-Hant/introduction

使用伺服器對伺服器的公開 API，把公司系統連接到 Brightalk AI 通話。

Brightalk 公開 API 能把公司既有的 CRM、表單、ERP 或內部工作流程連接到 AI 通話。您的伺服器可以建立聯絡人、選擇符合資格的 AI 語音代理、撥打一通電話、啟動批次撥號，或從儀表板管理的自動化建立一次自動化執行。

請前往 [Brightalk API 設定](https://www.brightalk.ai/settings/integrations/api)建立具適當權限的 API 金鑰，將金鑰安全地保存在伺服器端，再呼叫 `https://api.brightalk.ai`。每個已接受的通話或工作流程都會傳回可查詢的 API 資源，直到進入終止狀態。

AI 語音代理與自動化都在 Brightalk 儀表板中設定及管理。透過本 API 建立的通話僅限 AI 模式。

## 選擇執行方式

<CardGroup>
  <Card title="單次 AI 通話" icon="phone" href="/zh-Hant/guides/place-one-call">
    使用符合資格的 AI 語音代理，將一通立即執行的非同步通話加入佇列，再查詢結果。
  </Card>

  <Card title="批次撥號" icon="list" href="/zh-Hant/guides/create-start-batch">
    為最多 1,000 位不重複的收話人建立草稿，再啟動、排程及控制批次。
  </Card>

  <Card title="自動化執行" icon="diagram-project" href="/zh-Hant/guides/run-automation">
    從儀表板管理且已啟用的自動化，為一位聯絡人建立一次執行並追蹤狀態。
  </Card>
</CardGroup>

## API 涵蓋範圍

API 提供組織範圍內的聯絡人、符合資格的代理目錄、單次通話、批次、自動化摘要及自動化執行。已接受的執行工作皆為非同步：成功回應會建立或傳回一個 API 資源，您的伺服器需持續查詢，直到資源進入終止狀態。

契約未載明的功能目前不受支援。請參閱[可用性](/zh-Hant/availability)，瞭解明確邊界與儀表板相依性。

## 下一步

依照[快速開始](/zh-Hant/quickstart)建立具適當權限範圍的金鑰、將一通電話加入佇列，並判讀結果。


# 快速開始
Source: https://docs.brightalk.ai/zh-Hant/quickstart

使用 Brightalk API 金鑰完成第一個經過身分驗證的 REST API 流程。

請從受信任的伺服器呼叫正式環境基礎 URL `https://api.brightalk.ai`。此流程會建立一通立即執行的非同步 AI 通話，再查詢產生的通話資源。

## 1. 建立具適當權限範圍的金鑰

前往 [Brightalk API 設定](https://www.brightalk.ai/settings/integrations/api)，建立同時具備 `calls:read` 與 `calls:write` 的 `bt_live_` 金鑰。這兩項是建立並查詢通話所需的最小權限。若需要執行步驟 2 的選用聯絡人建立範例，請再選取 `contacts:write`；如果同一組織已有可用聯絡人，則不需要這項額外權限。金鑰只會顯示一次，請立即複製到伺服器端的金鑰管理工具。

將金鑰設為環境變數，且不要提交至版本控制：

```bash theme={null}
export BRIGHTALK_API_KEY="your_brightalk_api_key"
```

## 2. 取得代理與聯絡人參照

使用 `calls:read` 列出符合資格的代理。（`GET /agents` 也接受 `batches:read`，但這個單次通話流程不需要該權限。）將其中一筆回應的 `id` 保存為步驟 3 使用的 `agent_id`。

請將每個 JavaScript 範例儲存為 `.mjs`，或在 ESM 專案中執行。最外層的 `await` 必須使用 ESM，且需使用 Node 18 以上版本提供的內建 `fetch`。Python 範例使用 `requests`；在全新環境中，可執行 `python -m pip install requests` 安裝此依賴套件。

<CodeGroup>
  ```curl theme={null}
  curl --request GET 'https://api.brightalk.ai/agents?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/agents?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/agents?limit=20",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      },
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

接著，使用同一組織內既有聯絡人的不透明 `id`。若尚無聯絡人，可用以下需要 `contacts:write` 的請求建立或採用聯絡人。範例採用保留的 E.164 示意號碼 `+12025550123`；請將範例識別資料替換為組織可控的測試資料。

<CodeGroup>
  ```curl theme={null}
  curl --request POST 'https://api.brightalk.ai/contacts' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16" \
    --header "Content-Type: application/json" \
    --data '{"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"}'
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/contacts", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"}),
  });
  console.log(response.status, await response.json());
  ```

  ```python theme={null}
  import os
  import requests

  response = requests.request(
      "POST",
      "https://api.brightalk.ai/contacts",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      },
      json={"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"},
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

建立新聯絡人時會傳回 `201`；找到既有聯絡人或完成採用時則傳回 `200`。請將回應的 `id` 保存為 `contact_id`。在步驟 3 中，以前述回應的代理與聯絡人 ID 取代 `agt_demo_001` 與 `con_demo_001`。

## 3. 建立通話

請求需要 `calls:write`、`Brightalk-Version` 與非機密的 `Idempotency-Key`。

<Warning>
  對可接通的聯絡人送出 `POST /calls`，可能會撥打一通真實 PSTN 電話。執行修改後的範例前，請確認收話人與撥號時間。
</Warning>

<CodeGroup>
  ```curl theme={null}
  curl --request POST 'https://api.brightalk.ai/calls' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: createCall-example-001" \
    --data '{"agent_id":"agt_demo_001","contact_id":"con_demo_001"}'
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/calls", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createCall-example-001",
    },
    body: JSON.stringify({"agent_id":"agt_demo_001","contact_id":"con_demo_001"}),
  });
  console.log(response.status, await response.json());
  ```

  ```python theme={null}
  import os
  import requests

  response = requests.request(
      "POST",
      "https://api.brightalk.ai/calls",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createCall-example-001",
      },
      json={"agent_id":"agt_demo_001","contact_id":"con_demo_001"},
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

成功的請求會傳回 `202 Accepted`。請儲存回應中的 `id`：

```json theme={null}
{
  "id": "11111111-1111-4111-8111-111111111111",
  "contact_id": "con_demo_001",
  "agent_id": "agt_demo_001",
  "queued_at": "2026-07-20T01:00:00Z",
  "created_at": "2026-07-20T01:00:00Z",
  "updated_at": "2026-07-20T01:00:00Z",
  "status": "queued",
  "answer_status": "unknown"
}
```

## 4. 查詢傳回的通話 ID

將 `11111111-1111-4111-8111-111111111111` 替換為步驟 3 取得的 `id`。請使用 `calls:read` 查詢；每次請求之間採取退避，並遵守速率限制標頭。

<CodeGroup>
  ```curl theme={null}
  curl --request GET 'https://api.brightalk.ai/calls/11111111-1111-4111-8111-111111111111' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16"
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/calls/11111111-1111-4111-8111-111111111111", {
    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/calls/11111111-1111-4111-8111-111111111111",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      },
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

`status` 為 `queued`、`dialing` 或 `in_progress` 時，請持續查詢。

## 5. 判讀 `status` 與 `answer_status`

`status` 說明執行生命週期；當狀態為 `completed`、`failed` 或 `cancelled` 時停止查詢。`answer_status` 則獨立分類目的端的接聽情況。

| 欄位              | 回答的問題                | 範例值                                                 |
| --------------- | -------------------- | --------------------------------------------------- |
| `status`        | 通話執行是正常結束、失敗，還是遭取消？  | `completed`、`failed`、`cancelled`                    |
| `answer_status` | 目的端為已接聽、未接聽、忙線或語音信箱？ | `answered`、`no_answer`、`busy`、`voicemail`、`unknown` |

正常未接聽的結果是 `status: completed` 搭配 `answer_status: no_answer`，並非系統失敗。所有轉換請參閱[通話狀態生命週期](/zh-Hant/concepts/status-lifecycle)。


# 速率限制
Source: https://docs.brightalk.ai/zh-Hant/rate-limits

瞭解讀取、寫入、執行、逐字稿與錄音請求的速率限制回應。

如果 Brightalk 傳回 `429 rate_limit_exceeded`，表示整合程式對這類操作送出的請求，已超過目前可用配額。回應會直接告訴您需要等待多久。

## 等待後再安全重試

1. 從每一次 `429` 回應讀取最新的 `Retry-After`。
2. 至少等待該段時間，再加上一小段隨機延遲。後續若再次收到 `429`，請依最新的 `Retry-After` 等待，並逐步增加隨機退避時間，但不得超過呼叫端自訂的上限，避免重試間隔過短或無限重試。
3. 只有在操作可安全重試，且未超過呼叫端自訂的最大嘗試次數、總經過時間或截止期限，才重新送出。一旦達到次數上限或時間期限，請停止重試並回報錯誤。同一個邏輯寫入動作若仍在[冪等性文件所述的適用界線](/zh-Hant/idempotency)內，必須沿用相同的 HTTP 方法、路徑、API 版本、語意相同的請求內容，以及原本的 `Idempotency-Key`。

共用同一個組織配額的工作程序應彼此協調，不要各自獨立重試。

請勿在程式中寫死一個全域請求上限。Brightalk 會依組織限制請求，也可能對個別金鑰套用較低限制；目前請求一律以回應標頭為準。

## 五個獨立計數器

每個操作會使用五個獨立配額群組的其中一個：

| 配額群組         | 操作範例                            |
| ------------ | ------------------------------- |
| `read`       | 列出及查詢資源                         |
| `write`      | 寫入聯絡人；建立批次；取消通話；暫停或取消批次；取消自動化執行 |
| `execution`  | 建立通話；啟動或繼續批次；建立自動化執行            |
| `transcript` | 取得通話逐字稿；每個組織預設每分鐘 60 次請求        |
| `recording`  | 列出及取得通話錄音；每個組織預設每分鐘 60 次請求      |

取消及暫停操作使用 `write`，不是 `execution`。輪詢逐字稿與輪詢錄音各自使用專用配額群組，都不會占用一般讀取配額。已接受的執行請求所啟動的電話工作，不會再使用另一筆 HTTP 請求配額。

## 下載錄音不受速率限制——受限的是核發網址那一步

`GET /recordings` 與 `GET /recordings/{recording_id}` 和其他請求一樣會計入 `recording` 配額群組，但實際去抓取回應中 `download_url` 指向的內容並不會。那個網址位於另一個主機，不需要 API 金鑰，也沒有配額群組可以計費。節流發生在核發網址的那一步，不是使用網址的那一步：同時間內存在多少張有效的下載網址，取決於您每分鐘可核發幾次 `recording` 配額群組的請求，乘上核發時設定的存活秒數，而不是另外設有下載本身的限制。

## 讀取回應標頭

| 標頭                    | 意義                                                     |
| --------------------- | ------------------------------------------------------ |
| `RateLimit-Limit`     | 所選配額群組的有效配額                                            |
| `RateLimit-Remaining` | 該配額群組剩餘的非負請求次數                                         |
| `RateLimit-Reset`     | 從產生回應到重設配額的非負整數差值秒數（delta-seconds）；絕不是 Unix epoch 時間戳記 |
| `Retry-After`         | 重試遭拒請求前應等待的非負整數差值秒數（delta-seconds）                     |

請使用這些值，不要假設每個組織或金鑰都採用相同配額。

## 排隊不等於受到速率限制

通話並行容量是另一種控制。容量暫時已滿時，已接受的工作會保持 `queued`；不會變成 `429`，也不會遭丟棄。請查詢 API 資源，並將排隊視為生命週期狀態，而非請求節流訊號。


# 版本控制
Source: https://docs.brightalk.ai/zh-Hant/versioning

使用 Brightalk-Version 標頭選擇日期版本的 API 契約。

Brightalk 使用日期版本的契約，讓伺服器能選擇整合所依循的 API 行為。

## 使用不含版本的 URL

所有請求都使用正式環境基礎 URL `https://api.brightalk.ai`。版本號不屬於路徑的一部分；例如，使用 `POST /calls` 建立通話。

## 傳送 Brightalk-Version

客戶端應在每個請求明確傳送支援的日期版本：

```http theme={null}
Brightalk-Version: 2026-07-16
```

每個回應都會在 `Brightalk-Version` 標頭回傳實際套用的版本。請將標頭值放在設定中，讓契約升級都能先完成審查與測試。

## 理解省略標頭與預設值

每個組織都有固定的預設 API 版本。若請求省略 `Brightalk-Version`，Brightalk 會使用該固定預設值，並仍在回應標頭傳回實際版本。省略標頭不代表任意選用最新版本。

## 處理不支援的版本

未知或已停用的值會傳回 `400 unsupported_version`。若回應包含可供機器讀取的 `details`，其中會列出支援版本：

```json theme={null}
{
  "error": {
    "code": "unsupported_version",
    "message": "The requested API version is not supported.",
    "request_id": "req_demo_001",
    "details": {
      "supported_versions": ["2026-07-16"]
    }
  }
}
```

會破壞相容性的回應或行為變更必須使用另一個日期版本。同一版本內可能新增回應欄位，因此客戶端應忽略未知的回應欄位。


# 列出符合資格的 AI 語音代理
Source: https://docs.brightalk.ai/zh-hant/api-reference/agents/列出符合資格的-ai-語音代理

/openapi/openapi.zh-Hant.yaml get /agents
傳回組織擁有且目前符合對外 AI 撥號資格的代理。結果採用由新到舊的不透明游標分頁。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 列出 API 可見的通話
Source: https://docs.brightalk.ai/zh-hant/api-reference/calls/列出-api-可見的通話

/openapi/openapi.zh-Hant.yaml get /calls
傳回直接通話，以及由公開 API 建立的批次或自動化執行所產生的子通話。生命週期狀態與接聽分類彼此獨立。結果採用由新到舊的游標分頁。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取得通話
Source: https://docs.brightalk.ai/zh-hant/api-reference/calls/取得通話

/openapi/openapi.zh-Hant.yaml get /calls/{call_id}
傳回一個 API 可見的通話資源及其純量結果欄位。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取得通話摘要
Source: https://docs.brightalk.ai/zh-hant/api-reference/calls/取得通話摘要

/openapi/openapi.zh-Hant.yaml get /calls/{call_id}/summary
傳回一筆 API 可見通話中具有獨立修訂版本的摘要結果。處理中、無法提供，以及處理已耗盡，都是正常的 HTTP 200 結果狀態。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取得通話逐字稿
Source: https://docs.brightalk.ai/zh-hant/api-reference/calls/取得通話逐字稿

/openapi/openapi.zh-Hant.yaml get /calls/{call_id}/transcript
傳回一頁具有獨立修訂版本且由游標固定的清理後對話輪次。逐字稿是否就緒與摘要是否就緒彼此獨立。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取消通話
Source: https://docs.brightalk.ai/zh-hant/api-reference/calls/取消通話

/openapi/openapi.zh-Hant.yaml post /calls/{call_id}/cancel
以冪等方式要求盡力取消。通話完成可能在終止狀態競爭中勝出。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 將一通立即執行的 AI 通話加入佇列
Source: https://docs.brightalk.ai/zh-hant/api-reference/calls/將一通立即執行的-ai-通話加入佇列

/openapi/openapi.zh-Hant.yaml post /calls
以持久方式將一通 AI 通話排入佇列，使其可立即執行。容量限制可能使已接受的通話繼續留在佇列中。必須提供 Idempotency-Key，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 列出聯絡人
Source: https://docs.brightalk.ai/zh-hant/api-reference/contacts/列出聯絡人

/openapi/openapi.zh-Hant.yaml get /contacts
使用穩定且由新到舊的不透明游標分頁傳回組織的聯絡人。外部識別與建立時間篩選條件可合併使用。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取得聯絡人
Source: https://docs.brightalk.ai/zh-hant/api-reference/contacts/取得聯絡人

/openapi/openapi.zh-Hant.yaml get /contacts/{contact_id}
依不透明識別碼傳回組織的一位聯絡人。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 建立或採用聯絡人
Source: https://docs.brightalk.ai/zh-hant/api-reference/contacts/建立或採用聯絡人

/openapi/openapi.zh-Hant.yaml post /contacts
依據提供的外部識別與嚴格 E.164 號碼，建立、更新或採用組織內的標準聯絡人紀錄。原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 更新聯絡人
Source: https://docs.brightalk.ai/zh-hant/api-reference/contacts/更新聯絡人

/openapi/openapi.zh-Hant.yaml patch /contacts/{contact_id}
僅更新支援的聯絡人欄位。必須至少提供一個欄位，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 列出通話錄音
Source: https://docs.brightalk.ai/zh-hant/api-reference/recordings/列出通話錄音

/openapi/openapi.zh-Hant.yaml get /recordings
傳回組織在兩張通話資料表中的所有錄音，不論該通話透過何種方式建立。結果採用依錄音時間、再依錄音識別碼由新到舊排序的游標分頁。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取得通話錄音
Source: https://docs.brightalk.ai/zh-hant/api-reference/recordings/取得通話錄音

/openapi/openapi.zh-Hant.yaml get /recordings/{recording_id}
傳回一筆錄音的中繼資料，以及一個新核發的簽名下載網址。下載網址為短效，請在需要時重新索取，不要快取留待稍後使用。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 列出批次
Source: https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/列出批次

/openapi/openapi.zh-Hant.yaml get /batches
使用由新到舊的游標分頁，傳回由 API 建立的批次與彙總收話人數量。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取得批次
Source: https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/取得批次

/openapi/openapi.zh-Hant.yaml get /batches/{batch_id}
傳回一個由 API 建立的批次，以及彙總收話人數量與時間資訊。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取消剩餘的批次工作
Source: https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/取消剩餘的批次工作

/openapi/openapi.zh-Hant.yaml post /batches/{batch_id}/cancel
取消剩餘派送，並要求盡力取消仍在進行中的子通話。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 啟動或排程批次草稿
Source: https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/啟動或排程批次草稿

/openapi/openapi.zh-Hant.yaml post /batches/{batch_id}/start
將草稿轉換為已排程或已加入佇列的批次。必須提供 Idempotency-Key，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 建立批次草稿
Source: https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/建立批次草稿

/openapi/openapi.zh-Hant.yaml post /batches
建立包含 1 至 1,000 位不重複的既有聯絡人或內嵌收話人的草稿。只能提供其中一種收話人格式。必須提供 Idempotency-Key，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 暫停後續批次派送
Source: https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/暫停後續批次派送

/openapi/openapi.zh-Hant.yaml post /batches/{batch_id}/pause
暫停後續收話人派送，但不保證停止已在進行中的工作。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 繼續批次派送
Source: https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/繼續批次派送

/openapi/openapi.zh-Hant.yaml post /batches/{batch_id}/resume
將符合資格的剩餘收話人重新加入佇列。容量限制可能使其繼續留在佇列中。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 列出自動化
Source: https://docs.brightalk.ai/zh-hant/api-reference/自動化/列出自動化

/openapi/openapi.zh-Hant.yaml get /automations
傳回組織可見且由儀表板管理的自動化摘要。使用 status 縮小結果範圍，並使用 cursor 進行穩定且由新到舊的分頁。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 列出由 API 啟動的自動化執行
Source: https://docs.brightalk.ai/zh-hant/api-reference/自動化執行/列出由-api-啟動的自動化執行

/openapi/openapi.zh-Hant.yaml get /automation-runs
使用由新到舊的游標分頁，傳回透過此 API 啟動的自動化執行。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取得自動化執行
Source: https://docs.brightalk.ai/zh-hant/api-reference/自動化執行/取得自動化執行

/openapi/openapi.zh-Hant.yaml get /automation-runs/{run_id}
依不透明識別碼傳回一個由 API 啟動的自動化執行。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 取消自動化執行
Source: https://docs.brightalk.ai/zh-hant/api-reference/自動化執行/取消自動化執行

/openapi/openapi.zh-Hant.yaml post /automation-runs/{run_id}/cancel
防止已加入佇列的工作開始，或在步驟之間將尚未終止的執行標記為 `cancelled`。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。



# 建立自動化執行
Source: https://docs.brightalk.ai/zh-hant/api-reference/自動化執行/建立自動化執行

/openapi/openapi.zh-Hant.yaml post /automation-runs
從儀表板管理且已啟用的自動化，為一位聯絡人建立一次自動化執行並加入佇列。自動化定義指定要使用的代理、等待步驟、重試規則與分支。必須提供 Idempotency-Key；經清理的原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。