> ## 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.

# 快速開始

> 使用 Brightalk API 金鑰完成第一個經過身分驗證的 REST API 流程。

請從受信任的伺服器呼叫正式環境基礎 URL `https://api.brightalk.ai`。此流程會建立一通立即執行的非同步 AI 通話，再查詢產生的通話資源。

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

前往 [Brightalk API 設定](https://www.brightalk.ai/settings/integrations/api)，建立同時具備 `calls:read` 與 `calls:write` 的 `bt_live_` 金鑰。這兩項是建立並查詢通話所需的最小權限。若需要執行步驟 2 的選用聯絡人建立範例，請再選取 `contacts:write`；如果同一組織已有可用聯絡人，則不需要這項額外權限。金鑰只會顯示一次，請立即複製到伺服器端的金鑰管理工具。

將金鑰設為環境變數，且不要提交至版本控制：

```bash theme={null}
export BRIGHTALK_API_KEY="your_brightalk_api_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` 安裝此依賴套件。

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

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

  ```python theme={null}
  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())
  ```
</CodeGroup>

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

<CodeGroup>
  ```curl theme={null}
  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"}'
  ```

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

  ```python theme={null}
  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())
  ```
</CodeGroup>

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

## 3. 建立通話

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

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

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

## 4. 查詢傳回的通話 ID

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

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

`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`，並非系統失敗。所有轉換請參閱[通話狀態生命週期](/zh-Hant/concepts/status-lifecycle)。