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

# 建立外撥電話

> 從已設定的號碼池號碼向目標號碼發起外撥電話

建立外撥電話請求。電話會進入佇列並由外撥排程器派送；此端點在請求被接受時即回傳，而非在電話接通時。

用於通話的 Agent 會自動從專案解析得出 — 沒有 Agent 選擇器。每個專案對應一個 Agent。

## 請求

```bash theme={null}
POST https://api.pathors.com/v1/calls/outbound
```

### 標頭

<ParamField header="Authorization" type="string" required>
  使用您的 Developer Key（`dk_...`）進行 Bearer 令牌認證。
</ParamField>

### 請求主體

<ParamField body="projectId" type="string" required>
  將擁有此通話的專案。已認證的使用者必須是此專案的成員。
</ParamField>

<ParamField body="fromNumber" type="string" required>
  來源電話號碼。必須在已認證使用者所屬的號碼池中處於 `active` 狀態，且必須已設定外撥中繼線（trunk）。
</ParamField>

<ParamField body="toNumber" type="string" required>
  目的地電話號碼，採用 E.164 格式（例如 `+886912345678`）。
</ParamField>

<ParamField body="dynamicVariables" type="object">
  選填的鍵值對應，會作為執行時變數注入 Agent 會話。這些值可從您的路徑與提示中引用。
</ParamField>

### 範例

```bash theme={null}
curl -X POST https://api.pathors.com/v1/calls/outbound \
  -H "Authorization: Bearer dk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "fromNumber": "+886912345678",
    "toNumber": "+886987654321",
    "dynamicVariables": {
      "customerName": "Jane Doe",
      "orderId": "12345"
    }
  }'
```

## 回應

當通話請求被接受進入派送佇列後，回傳 `200 OK`。

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

## 錯誤

| 狀態碼 | 時機                                              |
| --- | ----------------------------------------------- |
| 400 | 驗證錯誤，或 `fromNumber` 存在但並非 `active`              |
| 401 | 缺少或無效的 Developer Key                            |
| 402 | 專案點數不足以發起外撥電話                                   |
| 403 | 使用者無權存取 `projectId`，或 `fromNumber` 不屬於使用者所屬的號碼池 |
| 404 | 找不到 `fromNumber`，或未設定外撥中繼線                      |
| 409 | 已有一通撥往此 `toNumber` 的外撥電話正在進行中                   |
| 500 | 內部伺服器錯誤                                         |

## 說明

* **Agent**：Agent 會自動從 `projectId` 解析得出。該專案所設定的 Agent 會負責處理此通話。
* **來源號碼的擁有權**：呼叫者（Developer Key 使用者）必須是擁有 `fromNumber` 的號碼池成員。`projectId` 的專案成員資格則會分開檢查。
* **變數**：`dynamicVariables` 會被字串化後寫入 LiveKit 房間的 metadata，並在整個會話期間提供給 Agent 使用。
* **並行**：同一個 `toNumber` 在同一時間內無法有超過一通進行中的外撥電話。請等待前一通通話完成後再重試。