> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/serve/call-center-outbound-api.md).

# 通話中心外撥 API

從外部系統透過通話中心外撥 API，讓號碼綁定的 Agent 撥出電話，並以通話紀錄 API 查詢處理狀態。

外部系統可以透過 API 發起外撥，由指定 SIP 號碼綁定的 Agent 與對方通話。例如，客服系統在取得客戶同意後，提交回電需求，再保存回傳的通話紀錄 ID，供後續查詢是否接通及何時結束。

SIP 中繼、號碼與 Agent 的後台設定，請先依使用者手冊的 [電話客服（通話中心）](https://docs.maiagent.ai/build/choose-channel/call-center) 完成。本頁說明 API 串接，不重複後台操作步驟。

## 呼叫前的條件 <a href="#prerequisites" id="prerequisites"></a>

* 組織已開通通話中心；呼叫者是組織擁有者，或具備通話中心權限的成員。
* 使用目前組織的 SIP 號碼 ID。號碼所屬中繼已啟用外撥、建立外撥線路，且同步狀態為已同步。
* 號碼已綁定有效、可使用語音功能的 Agent，且該 Agent 有 API 對話平台。

認證、API 網址及 JSON 欄位格式遵循 [API 共通規範](https://docs.maiagent.ai/tech/api-integration/api-conventions.md)。以下路徑使用 `/api/v1/`，JSON 使用 camelCase。

## 發起外撥 <a href="#start-outbound-call" id="start-outbound-call"></a>

```http
POST /api/v1/sip-numbers/{sipNumberId}/outbound-call/
```

`{sipNumberId}` 是用來撥出的 SIP 號碼 ID，並非目的電話號碼。請求內容只有目的號碼：

| 欄位         | 必填 | 說明                                                                             |
| ---------- | -- | ------------------------------------------------------------------------------ |
| `toNumber` | 是  | 目的號碼，支援 E.164 格式或 SIP user part；長度為 1～32 字元，允許數字、英文字母及 `+`、`*`、`#`、`.`、`_`、`-` |

Agent 由 SIP 號碼的既有綁定決定，不在此請求另外選擇。系統會建立對話與外撥通話紀錄，再發起撥號。

成功回傳 `201 Created`，內容是通話紀錄物件。先保存其 `id`；初始狀態為 `initiated`，方向為 `outbound`。

{% hint style="warning" %}
`201 Created` 表示外撥已發起，不代表對方已接聽或通話已完成。整合程式應繼續查詢通話紀錄，不要把成功回應直接當成已聯絡到客戶。
{% endhint %}

## 查詢通話結果 <a href="#query-call-result" id="query-call-result"></a>

使用回傳的通話紀錄 `id` 查詢：

```http
GET /api/v1/calls/{callId}/
```

這個查詢同樣要求通話中心權限，且只會取得目前組織、未刪除 Agent 的通話紀錄。可依下列欄位追蹤處理結果：

| 欄位                                | 用途                   |
| --------------------------------- | -------------------- |
| `id`                              | 保存為外部系統的通話追蹤識別碼      |
| `status`                          | 通話目前狀態，見下表           |
| `direction`                       | 本流程建立的通話為 `outbound` |
| `chatbot`、`conversation`          | 此通電話使用的 Agent 與對話識別碼 |
| `fromNumber`、`toNumber`           | 撥出及目的號碼              |
| `answeredAt`、`endedAt`、`duration` | 接聽時間、結束時間與通話秒數       |
| `disconnectReason`                | 系統記錄的斷線原因            |

| 狀態            | 意義   |
| ------------- | ---- |
| `initiated`   | 已發起  |
| `ringing`     | 響鈴中  |
| `in-progress` | 通話中  |
| `completed`   | 已完成  |
| `failed`      | 失敗   |
| `busy`        | 忙線   |
| `no-answer`   | 無人接聽 |
| `canceled`    | 已取消  |

`initiated`、`ringing`、`in-progress` 仍屬進行中；其餘為結束狀態。外部系統可在取得結束狀態後停止追蹤這通電話。

## 發起失敗時如何處理 <a href="#handle-start-failure" id="handle-start-failure"></a>

外撥未啟用、中繼尚未同步、沒有有效的 Agent 或缺少 API 對話平台，都會在發起前被拒絕。請先修正設定再重試；驗證錯誤的共通格式見 [API 共通規範：錯誤回應](https://docs.maiagent.ai/tech/api-integration/api-conventions.md#errors)。

若撥號派送失敗，外撥端點回傳 `400`。每次呼叫發起端點都可能建立新的通話，重試前應先核對既有通話紀錄，避免重複回電。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/serve/call-center-outbound-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
