撥打一通 AI 通話

私人測試版。 新組織預設已啟用。組織管理員仍須在 Brightalk 設定中建立具權限範圍的 API 金鑰，請求才能通過驗證。可用範圍與限制以本文件和 OpenAPI 契約為準。

此流程會將一通立即執行的非同步 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。

建立通話

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

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"}'

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());

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())

預期回應

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

{
  "id": "call_demo_001",
  "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 時，採退避方式查詢。

curl --request GET 'https://api.brightalk.ai/calls/call_demo_001' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16"

const response = await fetch("https://api.brightalk.ai/calls/call_demo_001", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
    "Brightalk-Version": "2026-07-16",
  },
});
console.log(response.status, await response.json());

import os
import requests

response = requests.request(
    "GET",
    "https://api.brightalk.ai/calls/call_demo_001",
    headers={
    "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
    "Brightalk-Version": "2026-07-16",
    },
)
print(response.status_code, response.json())

在 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` 後，以相同冪等性金鑰重試

開始使用

API 基礎

核心概念

操作指南

發布資訊

API 參考

事前準備

建立通話

預期回應

查詢通話

常見錯誤

​事前準備

​建立通話

​預期回應

​查詢通話

​常見錯誤

事前準備

建立通話

預期回應

查詢通話

常見錯誤