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

# 建立通話

> 建立外撥電話

<Warning>
  **已棄用。** 此端點已棄用，將於 **2026-07-11 下架**。在此之前仍可使用。請改用 V1 路徑--完整的新舊路徑對照見[遷移指南](/zh-Hant/migrations/2026-06-outbound-api-v1)。
</Warning>

建立外撥電話，從已設定的電話號碼向目標號碼發起電話通話。

## 基礎 URL

```
https://api.pathors.com
```

## 端點

```bash theme={null}
POST https://api.pathors.com/project/{projectId}/integration/phone/call/outbound
```

### 路徑參數

<ParamField path="projectId" type="string" required>
  您的專案 ID
</ParamField>

### 請求標頭

<ParamField header="Authorization" type="string" required>
  使用您的 Project API Key（以 `sk_` 開頭）進行 Bearer 令牌認證。格式：`Bearer {your-api-key}`
</ParamField>

### 請求體

<ParamField body="fromNumber" type="string" required>
  撥打電話的來源號碼。此號碼必須在您專案的 SIP 中繼設定中配置，且外呼狀態設為 'active'
</ParamField>

<ParamField body="toNumber" type="string" required>
  要撥打的目標電話號碼。應使用 E.164 格式（例如：`+1234567890`）。台灣電話號碼請使用本地格式，無需 `+886` 國家碼前綴（例如：`0912345678`）。
</ParamField>

<ParamField body="dynamicVariables" type="object">
  可選的動態變數，傳遞給通話流程。這些變數可在您的通話流程配置中使用
</ParamField>

請求範例：

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+1234567890",
    "toNumber": "+0987654321",
    "dynamicVariables": {
      "customerName": "John Doe",
      "orderId": "12345"
    }
  }' \
  https://api.pathors.com/project/proj_abc123/integration/phone/call/outbound
```

### 回應

返回成功回應，表示外呼電話事件已建立。

<ResponseField name="success" type="boolean">
  指示通話事件是否成功建立
</ResponseField>

回應範例：

```json theme={null}
{
  "success": true
}
```

### 錯誤回應

| 狀態碼 | 描述                                      |
| --- | --------------------------------------- |
| 400 | 缺少必要欄位（`fromNumber` 或 `toNumber`）或請求體無效 |
| 401 | 無效的身份驗證（API 金鑰無效或缺失）                    |
| 404 | 指定的電話號碼（`fromNumber`）未配置為外呼電話，或外呼狀態未啟用  |
| 409 | 目標電話號碼（`toNumber`）已在通話佇列中               |
| 500 | 內部伺服器錯誤                                 |

錯誤回應範例：

```json theme={null}
{
  "error": "The given phone number is not configured for outbound"
}
```

## 使用說明

* **電話號碼配置**：`fromNumber` 必須在您專案的 SIP 中繼設定中配置，且需滿足：
  * 外呼 SIP 狀態設為 'active'

* **通話佇列**：每個 `toNumber` 在佇列中一次只能有一個活動通話。如果您嘗試建立一個已存在於佇列中的號碼通話，將收到 409 錯誤。

* **動態變數**：使用 `dynamicVariables` 將自訂資料傳遞給您的通話流程。這些變數在整個通話會話中可用，可用於個人化或通話路由邏輯。