# Brightalk Developer Documentation > Connect server-side systems to Brightalk AI calling with the REST API. ## Docs - [身分驗證與權限範圍](https://docs.brightalk.ai/zh-Hant/authentication.md): 安全地使用 bearer API 金鑰與最小必要權限範圍。 - [可用性](https://docs.brightalk.ai/zh-Hant/availability.md): 確認公開 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 通話的儀表板管理代理。 - [自動化](https://docs.brightalk.ai/zh-Hant/concepts/automations.md): 瞭解由儀表板管理的自動化及其 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): 區分通話、批次與自動化執行的 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 通話並查詢其結果。 - [取得通話結果](https://docs.brightalk.ai/zh-Hant/guides/retrieve-call-results.md): 分別輪詢摘要與逐字稿，並在同一個不可變逐字稿修訂版本中分頁。 - [建立自動化執行](https://docs.brightalk.ai/zh-Hant/guides/run-automation.md): 為單一聯絡人建立並追蹤一次自動化執行。 - [冪等性](https://docs.brightalk.ai/zh-Hant/idempotency.md): 以 Idempotency-Key 安全地重試支援的寫入操作。 - [Brightalk API 簡介](https://docs.brightalk.ai/zh-Hant/introduction.md): 使用伺服器對伺服器的公開 API，把公司系統連接到 Brightalk AI 通話。 - [快速開始](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 可見的通話](https://docs.brightalk.ai/zh-hant/api-reference/calls/列出-api-可見的通話.md): 傳回直接通話，以及由公開 API 建立的批次或自動化執行所產生的子通話。生命週期狀態與接聽分類彼此獨立。結果採用由新到舊的游標分頁。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [取得通話](https://docs.brightalk.ai/zh-hant/api-reference/calls/取得通話.md): 傳回一個 API 可見的通話資源及其純量結果欄位。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [取得通話摘要](https://docs.brightalk.ai/zh-hant/api-reference/calls/取得通話摘要.md): 傳回一筆 API 可見通話中具有獨立修訂版本的摘要結果。處理中、無法提供，以及處理已耗盡，都是正常的 HTTP 200 結果狀態。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [取得通話逐字稿](https://docs.brightalk.ai/zh-hant/api-reference/calls/取得通話逐字稿.md): 傳回一頁具有獨立修訂版本且由游標固定的清理後對話輪次。逐字稿是否就緒與摘要是否就緒彼此獨立。每個回應都包含 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；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [列出批次](https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/列出批次.md): 使用由新到舊的游標分頁，傳回由 API 建立的批次與彙總收話人數量。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [取得批次](https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/取得批次.md): 傳回一個由 API 建立的批次，以及彙總收話人數量與時間資訊。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [取消剩餘的批次工作](https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/取消剩餘的批次工作.md): 取消剩餘派送，並要求盡力取消仍在進行中的子通話。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [啟動或排程批次草稿](https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/啟動或排程批次草稿.md): 將草稿轉換為已排程或已加入佇列的批次。必須提供 Idempotency-Key，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [建立批次草稿](https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/建立批次草稿.md): 建立包含 1 至 1,000 位不重複的既有聯絡人或內嵌收話人的草稿。只能提供其中一種收話人格式。必須提供 Idempotency-Key，且原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [暫停後續批次派送](https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/暫停後續批次派送.md): 暫停後續收話人派送，但不保證停止已在進行中的工作。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [繼續批次派送](https://docs.brightalk.ai/zh-hant/api-reference/批次撥號/繼續批次派送.md): 將符合資格的剩餘收話人重新加入佇列。容量限制可能使其繼續留在佇列中。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [列出自動化](https://docs.brightalk.ai/zh-hant/api-reference/自動化/列出自動化.md): 傳回組織可見且由儀表板管理的自動化摘要。使用 status 縮小結果範圍，並使用 cursor 進行穩定且由新到舊的分頁。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [列出由 API 啟動的自動化執行](https://docs.brightalk.ai/zh-hant/api-reference/自動化執行/列出由-api-啟動的自動化執行.md): 使用由新到舊的游標分頁，傳回透過此 API 啟動的自動化執行。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [取得自動化執行](https://docs.brightalk.ai/zh-hant/api-reference/自動化執行/取得自動化執行.md): 依不透明識別碼傳回一個由 API 啟動的自動化執行。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [取消自動化執行](https://docs.brightalk.ai/zh-hant/api-reference/自動化執行/取消自動化執行.md): 防止已加入佇列的工作開始，或在步驟之間將尚未終止的執行標記為 `cancelled`。選用的 Idempotency-Key 可讓結果重播；原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 - [建立自動化執行](https://docs.brightalk.ai/zh-hant/api-reference/自動化執行/建立自動化執行.md): 從儀表板管理且已啟用的自動化，為一位聯絡人建立一次自動化執行並加入佇列。自動化定義指定要使用的代理、等待步驟、重試規則與分支。必須提供 Idempotency-Key；經清理的原始 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)