> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 撥打一通 AI 通話

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

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

此流程會將一通立即執行的非同步 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": "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` 時，採退避方式查詢。

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

  ```javascript theme={null}
  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());
  ```

  ```python theme={null}
  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())
  ```
</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` 後，以相同冪等性金鑰重試                |