# Brightalk Developer Documentation

> Server-to-server REST API documentation for Brightalk Private Beta.

## Docs

- [驗證與權限範圍](https://docs.brightalk.ai/zh-Hant/authentication.md): 安全地使用 bearer API 金鑰與最小必要權限範圍。
- [可用性](https://docs.brightalk.ai/zh-Hant/availability.md): 確認私人測試版 REST API 的可用範圍與儀表板相依性。
- [變更記錄](https://docs.brightalk.ai/zh-Hant/changelog.md): 追蹤 Brightalk REST API 契約與開發者文件的日期版本變更。
- [AI 語音代理](https://docs.brightalk.ai/zh-Hant/concepts/agents.md): 選取可供 REST API 執行 AI 通話的儀表板管理代理。
- [Automations](https://docs.brightalk.ai/zh-Hant/concepts/automations.md): 理解由儀表板管理的 Automation 與其 API 執行方式。
- [批次撥號](https://docs.brightalk.ai/zh-Hant/concepts/batches.md): 瞭解草稿、排程與批次撥號控制流程。
- [通話](https://docs.brightalk.ai/zh-Hant/concepts/calls.md): 理解非同步 AI 通話資源及其結果。
- [聯絡人](https://docs.brightalk.ai/zh-Hant/concepts/contacts.md): 瞭解 REST API 中的聯絡人、API 資源識別碼與外部識別。
- [狀態生命週期](https://docs.brightalk.ai/zh-Hant/concepts/status-lifecycle.md): 區分通話、批次與 Automation 執行的 API 狀態。
- [錯誤](https://docs.brightalk.ai/zh-Hant/errors.md): 解析一致的 REST API 錯誤回應格式與請求識別碼。
- [建立並啟動批次](https://docs.brightalk.ai/zh-Hant/guides/create-start-batch.md): 建立批次草稿、啟動撥號並追蹤批次狀態。
- [撥打一通 AI 通話](https://docs.brightalk.ai/zh-Hant/guides/place-one-call.md): 建立一通非同步 AI 通話並查詢其結果。
- [執行 Automation](https://docs.brightalk.ai/zh-Hant/guides/run-automation.md): 為單一聯絡人啟動並追蹤 Automation 執行。
- [冪等性](https://docs.brightalk.ai/zh-Hant/idempotency.md): 以 Idempotency-Key 安全地重試支援的寫入操作。
- [Brightalk API 簡介](https://docs.brightalk.ai/zh-Hant/introduction.md): 瞭解 Brightalk 私人測試版 server-to-server REST API 的支援範圍。
- [快速開始](https://docs.brightalk.ai/zh-Hant/quickstart.md): 以 Brightalk API 金鑰完成第一個經驗證的 REST API 流程。
- [速率限制](https://docs.brightalk.ai/zh-Hant/rate-limits.md): 理解讀取、寫入與執行請求的速率限制回應。
- [版本控制](https://docs.brightalk.ai/zh-Hant/versioning.md): 使用 Brightalk-Version 標頭選擇日期版本的 API 契約。
- [列出可用的 AI 語音代理](https://docs.brightalk.ai/zh-hant/api-reference/agents/列出可用的-ai-語音代理.md): 傳回組織擁有且目前可用於撥出 AI 通話的代理。結果採用由新到舊的不透明游標分頁。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [列出由 API 啟動的 Automation 執行](https://docs.brightalk.ai/zh-hant/api-reference/automation-runs/列出由-api-啟動的-automation-執行.md): 使用由新到舊的游標分頁，傳回透過此 API 啟動的 Automation 執行。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [取得 Automation 執行](https://docs.brightalk.ai/zh-hant/api-reference/automation-runs/取得-automation-執行.md): 依不透明識別碼傳回一個由 API 啟動的 Automation 執行。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [取消 Automation 執行](https://docs.brightalk.ai/zh-hant/api-reference/automation-runs/取消-automation-執行.md): 防止已排入佇列的工作開始，或在步驟邊界之間將尚未終止的執行標記為 cancelled。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [啟動作用中的 Automation](https://docs.brightalk.ai/zh-hant/api-reference/automation-runs/啟動作用中的-automation.md): 將一個由儀表板管理且作用中的 Automation 排入佇列，為一位聯絡人執行。Automation 負責其代理、等待、重試規則與分支。必須提供 Idempotency-Key；經清理的原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [列出 Automation](https://docs.brightalk.ai/zh-hant/api-reference/automations/列出-automation.md): 傳回組織可見且由儀表板管理的 Automation 摘要。使用 status 縮小結果範圍，並使用 cursor 進行穩定且由新到舊的分頁。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [列出批次](https://docs.brightalk.ai/zh-hant/api-reference/batches/列出批次.md): 使用由新到舊的游標分頁，傳回由 API 建立的批次與彙總收件人數量。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [取得批次](https://docs.brightalk.ai/zh-hant/api-reference/batches/取得批次.md): 傳回一個由 API 建立的批次，以及彙總收件人數量與時間資訊。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [取消剩餘的批次工作](https://docs.brightalk.ai/zh-hant/api-reference/batches/取消剩餘的批次工作.md): 取消剩餘派送，並要求盡力取消仍在進行中的子通話。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [啟動或排程批次草稿](https://docs.brightalk.ai/zh-hant/api-reference/batches/啟動或排程批次草稿.md): 將草稿轉換為已排程或已排入佇列的執行。必須提供 Idempotency-Key，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [建立批次草稿](https://docs.brightalk.ai/zh-hant/api-reference/batches/建立批次草稿.md): 建立包含 1 至 1,000 位不重複聯絡人或行內收件人的草稿。只能提供其中一種收件人形式。必須提供 Idempotency-Key，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [暫停後續批次派送](https://docs.brightalk.ai/zh-hant/api-reference/batches/暫停後續批次派送.md): 暫停後續收件人派送，但不保證停止已在進行中的工作。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [繼續批次派送](https://docs.brightalk.ai/zh-hant/api-reference/batches/繼續批次派送.md): 將符合資格的剩餘收件人重新排入佇列。容量限制可能使其繼續留在佇列中。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [列出 API 可見的通話](https://docs.brightalk.ai/zh-hant/api-reference/calls/列出-api-可見的通話.md): 傳回直接通話，以及由公開 API 建立之批次或 Automation 執行的子通話。生命週期狀態與接聽分類彼此獨立。結果採用由新到舊的游標分頁。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [取得通話](https://docs.brightalk.ai/zh-hant/api-reference/calls/取得通話.md): 傳回一個 API 可見的 Call 資源及其純量結果欄位。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [取消通話](https://docs.brightalk.ai/zh-hant/api-reference/calls/取消通話.md): 以冪等方式要求盡力取消。通話完成可能在終止狀態競爭中勝出。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [將一通立即 AI 通話排入佇列](https://docs.brightalk.ai/zh-hant/api-reference/calls/將一通立即-ai-通話排入佇列.md): 以持久方式將一通 AI 通話排入佇列，使其可立即執行。容量限制可能使已接受的通話繼續留在佇列中。必須提供 Idempotency-Key，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [列出聯絡人](https://docs.brightalk.ai/zh-hant/api-reference/contacts/列出聯絡人.md): 使用穩定且由新到舊的不透明游標分頁傳回組織的聯絡人。外部身分與建立時間篩選條件可合併使用。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [取得聯絡人](https://docs.brightalk.ai/zh-hant/api-reference/contacts/取得聯絡人.md): 依不透明識別碼傳回組織的一位聯絡人。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [建立或接管聯絡人](https://docs.brightalk.ai/zh-hant/api-reference/contacts/建立或接管聯絡人.md): 依據提供的外部身分與嚴格 E.164 號碼，建立、更新或接管組織的標準聯絡人。原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。
- [更新聯絡人](https://docs.brightalk.ai/zh-hant/api-reference/contacts/更新聯絡人.md): 僅更新支援的聯絡人欄位。必須至少提供一個欄位，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。

## OpenAPI Specs

- [openapi.zh-Hant](https://docs.brightalk.ai/openapi/openapi.zh-Hant.yaml)
- [openapi](https://docs.brightalk.ai/openapi/openapi.yaml)