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

# 狀態生命週期

> 區分通話、批次與 Automation 執行的 API 狀態。

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

只有 API 資源的 `status` 為非終止狀態時才需要查詢。終止狀態的資源仍可查詢，且不會再轉回進行中的工作。

## 通話 `status`

```mermaid theme={null}
flowchart LR
  queued --> dialing
  queued --> in_progress
  queued --> completed
  dialing --> in_progress
  dialing --> completed
  in_progress --> completed
  queued --> failed
  dialing --> failed
  in_progress --> failed
  queued --> cancelled
  dialing --> cancelled
  in_progress --> cancelled
```

| 狀態            | 是否終止 | 意義             |
| ------------- | ---- | -------------- |
| `queued`      | 否    | 已接受，正在等待派送或容量  |
| `dialing`     | 否    | 已開始撥號          |
| `in_progress` | 否    | 通話已接通且進行中      |
| `completed`   | 是    | 執行已結束，包含一般接聽結果 |
| `failed`      | 是    | 服務無法安全執行       |
| `cancelled`   | 是    | 取消在完成前勝出       |

圖中列出 API 可見狀態允許的轉換，不代表每筆資源都必須走過單一路徑。較晚抵達的回呼、背景工作程序更新或狀態校正作業，可能跳過中間的可觀測狀態，使 `queued` 或 `dialing` 直接進入 `in_progress` 或 `completed`。客戶端必須接受圖中任一轉換。`queued`、`dialing` 與 `in_progress` 都支援取消。

## 批次 `status`

```mermaid theme={null}
flowchart LR
  draft --> scheduled
  draft --> queued
  scheduled --> queued
  scheduled --> in_progress
  scheduled --> completed
  scheduled --> failed
  scheduled --> paused
  queued --> in_progress
  queued --> completed
  queued --> paused
  in_progress --> paused
  paused --> scheduled
  paused --> queued
  in_progress --> completed
  queued --> failed
  in_progress --> failed
  draft --> cancelled
  scheduled --> cancelled
  queued --> cancelled
  in_progress --> cancelled
  paused --> cancelled
```

| 狀態            | 是否終止 | 意義                |
| ------------- | ---- | ----------------- |
| `draft`       | 否    | 已設定但尚未啟動          |
| `scheduled`   | 否    | 已啟動，正在等待符合排程資格    |
| `queued`      | 否    | 收話人已符合資格並排隊等待派送   |
| `in_progress` | 否    | 至少有部分收話人工作正在執行或推進 |
| `paused`      | 否    | 後續派送已暫停           |
| `completed`   | 是    | 所有收話人工作都到達終止結果    |
| `failed`      | 是    | 批次無法安全繼續          |
| `cancelled`   | 是    | 剩餘工作已取消           |

控制操作與圖示一致：啟動會將 `draft` 轉為 `scheduled` 或 `queued`；`scheduled`、`queued` 與 `in_progress` 都可暫停；繼續會依排程資格將 `paused` 轉回 `scheduled` 或 `queued`；所有非終止批次狀態都可取消。

這些轉換不代表單一路徑。較晚抵達的回呼、背景工作程序更新或狀態校正作業，可能跳過中間的可觀測狀態，依圖中連線將 `scheduled` 或 `queued` 直接推進至 `in_progress`、`completed` 或 `failed`。客戶端必須接受圖中每一種轉換，並只在進入終止狀態後停止查詢。

## Automation 執行 `status`

```mermaid theme={null}
flowchart LR
  queued --> running
  running --> waiting
  waiting --> running
  running --> completed
  waiting --> completed
  queued --> failed
  running --> failed
  waiting --> failed
  queued --> cancelled
  running --> cancelled
  waiting --> cancelled
```

| 狀態          | 是否終止 | 意義                     |
| ----------- | ---- | ---------------------- |
| `queued`    | 否    | 已接受並等待開始               |
| `running`   | 否    | Automation 步驟正在執行或已可執行 |
| `waiting`   | 否    | Automation 正依其定義等待     |
| `completed` | 是    | Automation 正常結束        |
| `failed`    | 是    | Automation 無法安全繼續      |
| `cancelled` | 是    | Automation 執行在正常完成前遭取消 |

## `answer_status` 為獨立資訊

`answer_status` 屬於通話資源，並非生命週期狀態。其值可為 `answered`、`no_answer`、`busy`、`voicemail` 或 `unknown`。

| 通話結果        | 組合範例                                          |
| ----------- | --------------------------------------------- |
| 已接聽且正常結束    | `status: completed`、`answer_status: answered` |
| 未接聽、忙線或語音信箱 | `status: completed` 搭配相應的 `answer_status`     |
| 沒有接通證據的執行失敗 | `status: failed`、`answer_status: unknown`     |
| 接通後遭取消      | `status: cancelled`、`answer_status: answered` |

請一律先依 `status` 判斷是否停止查詢，再依 `answer_status` 解讀目的端行為。