快速開始

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

請從受信任的伺服器使用正式環境 base URL https://api.brightalk.ai。此流程會建立一通立即執行的非同步 AI 通話，再查詢其通話 API 資源。

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

前往 Brightalk 設定 → 整合 → API，建立同時具備 calls:read 與 calls:write 的 bt_live_ 金鑰。這兩項是建立並查詢通話所需的最小權限。若需要執行步驟 2 的選用聯絡人建立範例，請再選取 contacts:write；如果同一組織已有可用聯絡人，則不需要這項額外權限。金鑰只會顯示一次，請立即複製到伺服器端的金鑰管理工具。將金鑰設為環境變數，且不要提交至版本控制：

export BRIGHTALK_API_KEY="your_private_beta_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 安裝此依賴套件。

curl --request GET 'https://api.brightalk.ai/agents?limit=20' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16"

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

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

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

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

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

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

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

3. 建立通話

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

對可接通的聯絡人送出 POST /calls，可能會撥打一通真實 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())

成功的請求會傳回 202 Accepted。請儲存回應中的 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"
}

4. 查詢傳回的通話 ID

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

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

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，並非系統失敗。所有轉換請參閱通話狀態生命週期。

開始使用

API 基礎

核心概念

操作指南

發布資訊

API 參考

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

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

3. 建立通話

4. 查詢傳回的通話 ID

5. 判讀 `status` 與 `answer_status`

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

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

​3. 建立通話

​4. 查詢傳回的通話 ID

​5. 判讀 status 與 answer_status

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

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

3. 建立通話

4. 查詢傳回的通話 ID

5. 判讀 `status` 與 `answer_status`