# Zorio Developer Portal

> Tài liệu chính thức tích hợp REST API + Webphone SDK của hệ thống Zorio Contact Center.

Generated for AI agents. Source: https://docs.zorio.vn


---

# Campaigns

<!-- source: https://docs.zorio.vn/api/autocall/campaigns.md -->

# Campaigns

Quản lý chiến dịch AutoCall — CRUD + lifecycle controls (launch / pause / resume / archive / unarchive) + thống kê.

## Tạo chiến dịch

```http
POST /api/autocall/campaigns
```

**Body**:
```json
{
  "name": "Chăm sóc khách hàng Q3-2026",
  "description": "Chăm sóc khách hàng kích hoạt lại sau 30-60 ngày",
  "script_id": 12,
  "caller_id_group_id": 3,
  "max_retries": 3,
  "retry_interval_minutes": 60,
  "retry_only_when": "no_answer",
  "max_concurrent": 10,
  "originate_timeout": 40,
  "write_to_main_cdr": false,
  "start_at": "2026-06-25T08:00:00Z",
  "end_at": "2026-06-30T17:30:00Z"
}
```

**Fields**:

| Field | Required | Type | Mô tả |
|---|---|---|---|
| `name` | Có | string, max:255 | Tên chiến dịch |
| `description` | Không | string, max:2000 | Mô tả |
| `script_id` | Có | integer | ID script TTS (xem [Scripts](/api/autocall/scripts)). PHẢI tồn tại **VÀ** `status='active'`. Truyền script đang `draft`/`archived` -> **422**. |
| `caller_id_group_id` | Không | integer | ID pool đầu số. Bỏ trống -> engine fallback default trunk của khách hàng. PHẢI tồn tại + `status='active'`. |
| `max_retries` | Không | integer (0-10, default 3) | Số lần thử lại tối đa nếu attempt fail |
| `retry_interval_minutes` | Không | integer (1-43200, default 60) | Khoảng cách giữa các attempt (phút) |
| `retry_only_when` | Không | enum (`no_answer`/`busy`/`failed`/`any`, default `no_answer`) | Chỉ retry khi attempt result match |
| `max_concurrent` | Không | integer (1-200, default 10) | Số cuộc đồng thời tối đa |
| `originate_timeout` | Không | integer (10-180, default 40) | Timeout chờ B-leg nhận máy (giây) |
| `write_to_main_cdr` | Không | boolean (default false) | Có ghi vào CDR chung hệ thống không. False = chỉ ghi log nội bộ AutoCall. |
| `start_at` | Không | datetime UTC | Thời điểm bắt đầu được dial. Bỏ trống = launch ngay |
| `end_at` | Không | datetime UTC | Thời điểm dừng (phải > start_at) |

**Response 201** (response trả đầy đủ các field):
```json
{
  "data": {
    "id": 19,
    "tenant_id": 1,
    "name": "Chăm sóc khách hàng Q3-2026",
    "description": "Chăm sóc khách hàng kích hoạt lại sau 30-60 ngày",
    "script_id": 12,
    "status": "draft",
    "gateway_name": null,
    "caller_id": null,
    "caller_id_group_id": 8,
    "max_retries": 3,
    "retry_interval_minutes": 60,
    "retry_only_when": "no_answer",
    "write_to_main_cdr": false,
    "max_concurrent": 10,
    "originate_timeout": 40,
    "start_at": "2026-06-25T08:00:00.000000Z",
    "end_at": "2026-06-30T17:30:00.000000Z",
    "total_leads": 0,
    "total_calls": 0,
    "total_connected": 0,
    "total_failed": 0,
    "created_by": 3,
    "created_at": "2026-06-25T09:53:47.000000Z",
    "updated_at": "2026-06-25T09:53:47.000000Z",
    "deleted_at": null
  }
}
```

::: tip Ghi chú
Response trả tất cả field cấu hình của campaign. Stats fields (`total_*`) = 0 lúc tạo (chưa có lead/call activity). Field `gateway_name`, `caller_id` (single override) null nếu dùng pool theo `caller_id_group_id`. Field `deleted_at` null nếu chưa archive (soft delete).
:::

**Response 422** (validation):
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "script_id": ["The selected script id is invalid."],
    "retry_only_when": ["The selected retry only when is invalid."]
  }
}
```

## Lifecycle controls

| Endpoint | Action | Từ -> Sang |
|---|---|---|
| `POST /api/autocall/campaigns/{id}/launch` | Kích hoạt | `draft`/`paused` -> `active` |
| `POST /api/autocall/campaigns/{id}/pause` | Tạm dừng | `active` -> `paused` |
| `POST /api/autocall/campaigns/{id}/resume` | Tiếp tục | `paused` -> `active` (alias của launch) |
| `POST /api/autocall/campaigns/{id}/archive` | Lưu trữ | `draft`/`paused`/`done` -> `archived` (yêu cầu KHÔNG đang active) |
| `POST /api/autocall/campaigns/{id}/unarchive` | Khôi phục | `archived` -> `paused` |
| `PUT /api/autocall/campaigns/{id}` | Cập nhật metadata | giữ status |
| `DELETE /api/autocall/campaigns/{id}` | Xoá VĨNH VIỄN | yêu cầu `archived` trước (hard delete cascade: campaign + leads + attempts + dtmf_events) |

::: warning Quy tắc bắt buộc
- Phải `pause` trước khi `archive` (campaign đang chạy không thể archive).
- Phải `archive` trước khi `delete` (xoá vĩnh viễn -> mất data báo cáo).
:::

**Response 200** (áp dụng cho mọi action launch/pause/resume/archive/unarchive):
```json
{
  "data": {
    "id": 21,
    "tenant_id": 1,
    "name": "Chăm sóc Q3-2026 2",
    "description": "Chăm sóc khách hàng kích hoạt lại sau 30-60 ngày",
    "script_id": 12,
    "status": "active",
    "gateway_name": null,
    "caller_id": null,
    "caller_id_group_id": 8,
    "max_retries": 3,
    "retry_interval_minutes": 60,
    "retry_only_when": "no_answer",
    "write_to_main_cdr": false,
    "max_concurrent": 10,
    "originate_timeout": 40,
    "start_at": "2026-06-25T08:00:00.000000Z",
    "end_at": "2026-06-30T17:30:00.000000Z",
    "total_leads": 0,
    "total_calls": 0,
    "total_connected": 0,
    "total_failed": 0,
    "created_by": 3,
    "created_at": "2026-06-25T14:26:16.000000Z",
    "updated_at": "2026-06-25T14:27:41.000000Z",
    "deleted_at": null
  }
}
```

**Field bổ sung** (không có ở body POST):

| Field | Type | Mô tả |
|---|---|---|
| `gateway_name` | string \| null | Override gateway dial cụ thể (mặc định null = dùng default routing) |
| `caller_id` | string \| null | Override caller ID đơn (mặc định null = dùng pool theo `caller_id_group_id`) |
| `total_leads` | integer | Tổng lead đã import vào campaign |
| `total_calls` | integer | Tổng cuộc gọi đã dial |
| `total_connected` | integer | Tổng cuộc connect thành công |
| `total_failed` | integer | Tổng cuộc fail |
| `deleted_at` | timestamp \| null | Soft delete timestamp (null nếu chưa archive) |

::: tip Timestamps format
ISO 8601 với **microseconds** `.000000Z`. Khách hàng parse phải hỗ trợ format này (vd `new Date("2026-06-25T14:26:16.000000Z")` trong JS hoạt động đúng).
:::

**Response 422** (state machine fail):
```json
{ "message": "Chỉ campaign draft/paused mới launch được" }
{ "message": "Chỉ campaign active mới pause được" }
{ "message": "Phải tạm dừng chiến dịch trước khi lưu trữ" }
{ "message": "Chỉ chiến dịch đã lưu trữ mới có thể khôi phục" }
{ "message": "Phải lưu trữ chiến dịch trước khi xoá vĩnh viễn (Lưu trữ -> Xoá)" }
```

**Response 200** (`PUT /api/autocall/campaigns/{id}` — cập nhật metadata): trả campaign object đã update, shape giống Response 201.

**Response 200** (`DELETE /api/autocall/campaigns/{id}`):
```json
{ "data": { "deleted": true } }
```

## List / show details / stats

### `GET /api/autocall/campaigns?status=active`

**Query params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `status` | string | Không | Lọc theo trạng thái chiến dịch | `draft` / `active` / `paused` / `done` / `archived` |
| `archived` | integer | Không | Lấy danh sách chiến dịch đã lưu trữ. Mặc định ẨN archived | `1` = chỉ archived; bỏ trống = không archived |
| `q` | string | Không | Tìm kiếm gần đúng theo tên chiến dịch (LIKE `%keyword%`) | Chuỗi text bất kỳ |

**Response 200**:
```json
{
  "data": [
    {
      "id": 36,
      "name": "Chăm sóc khách hàng Q3-2026",
      "status": "active",
      "script": { "id": 12, "name": "Chăm sóc chuẩn", "voice_id": "evln-vi-nature" },
      "total_leads": 487,
      "total_calls": 312,
      "total_connected": 198,
      "total_failed": 89,
      "created_at": "2026-06-24T07:30:00Z"
    }
  ]
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data[].id` | integer | ID chiến dịch | Số nguyên dương |
| `data[].name` | string | Tên chiến dịch | Tối đa 255 ký tự |
| `data[].status` | string | Trạng thái lifecycle hiện tại | `draft` / `active` / `paused` / `done` / `archived` |
| `data[].script` | object | Script TTS đính kèm (eager-load) | Object con với `id`, `name`, `voice_id` |
| `data[].script.id` | integer | ID script | Số nguyên dương |
| `data[].script.name` | string | Tên script | — |
| `data[].script.voice_id` | string | ID giọng đọc TTS được script dùng | — |
| `data[].total_leads` | integer | Tổng lead đã import vào chiến dịch | >= 0 |
| `data[].total_calls` | integer | Tổng cuộc gọi đã dial | >= 0 |
| `data[].total_connected` | integer | Tổng cuộc gọi connect thành công (B-leg answer) | >= 0 |
| `data[].total_failed` | integer | Tổng cuộc gọi thất bại | >= 0 |
| `data[].created_at` | datetime ISO 8601 | Thời điểm tạo chiến dịch (UTC) | — |

### `GET /api/autocall/campaigns/{id}`

Trả về chi tiết đầy đủ kèm `script.dtmfActions` và `agents`.

**Path params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `id` | integer | Có | ID chiến dịch | Số nguyên dương tồn tại trong tài khoản |

**Response 200**:
```json
{
  "data": {
    "id": 36,
    "name": "Chăm sóc khách hàng Q3-2026",
    "description": "Chăm sóc khách hàng kích hoạt lại sau 30-60 ngày",
    "status": "active",
    "script_id": 12,
    "caller_id_group_id": 3,
    "max_retries": 3,
    "retry_interval_minutes": 60,
    "retry_only_when": "no_answer",
    "max_concurrent": 10,
    "originate_timeout": 40,
    "write_to_main_cdr": false,
    "start_at": "2026-06-25T08:00:00Z",
    "end_at": "2026-06-30T17:30:00Z",
    "total_leads": 487,
    "total_calls": 312,
    "total_connected": 198,
    "total_failed": 89,
    "tenant_id": 1,
    "created_by": 7,
    "created_at": "2026-06-24T07:30:00Z",
    "updated_at": "2026-06-25T02:34:00Z",
    "script": {
      "id": 12,
      "name": "Chăm sóc chuẩn",
      "voice_id": "evln-vi-nature",
      "dtmf_actions": [
        { "id": 45, "digit": "1", "label": "Xác nhận", "action_type": "playback_then_hangup", "target_audio_url": "/media/thanks.wav" },
        { "id": 46, "digit": "2", "label": "Chuyển NV", "action_type": "queue", "target_queue_name": "support_queue" }
      ]
    },
    "agents": []
  }
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data.id` | integer | ID chiến dịch | Số nguyên dương |
| `data.name` | string | Tên chiến dịch | — |
| `data.description` | string \| null | Mô tả | — |
| `data.status` | string | Trạng thái lifecycle | `draft` / `active` / `paused` / `done` / `archived` |
| `data.script_id` | integer | ID script TTS đang dùng | — |
| `data.caller_id_group_id` | integer \| null | ID pool đầu số rotation | — |
| `data.max_retries` | integer | Số lần thử lại tối đa nếu attempt fail | 0-10 |
| `data.retry_interval_minutes` | integer | Khoảng cách giữa các attempt (phút) | 1-43200 |
| `data.retry_only_when` | string | Điều kiện chỉ retry khi result match | `no_answer` / `busy` / `failed` / `any` |
| `data.max_concurrent` | integer | Số cuộc đồng thời tối đa | 1-200 |
| `data.originate_timeout` | integer | Timeout chờ B-leg nhận máy (giây) | 10-180 |
| `data.write_to_main_cdr` | boolean | Có ghi CDR chung hệ thống không | `true` / `false` |
| `data.start_at` | datetime ISO 8601 \| null | Thời điểm bắt đầu được dial (UTC) | — |
| `data.end_at` | datetime ISO 8601 \| null | Thời điểm dừng dial (UTC) | — |
| `data.total_leads` | integer | Tổng lead đã import | >= 0 |
| `data.total_calls` | integer | Tổng cuộc đã dial | >= 0 |
| `data.total_connected` | integer | Tổng cuộc connect thành công | >= 0 |
| `data.total_failed` | integer | Tổng cuộc fail | >= 0 |
| `data.tenant_id` | integer | ID khách hàng sở hữu | — |
| `data.created_by` | integer | User ID người tạo | — |
| `data.created_at` | datetime ISO 8601 | Thời điểm tạo (UTC) | — |
| `data.updated_at` | datetime ISO 8601 | Thời điểm cập nhật gần nhất (UTC) | — |
| `data.script` | object | Script TTS đính kèm + danh sách phím DTMF | — |
| `data.script.dtmf_actions[]` | array | Cấu hình các phím bấm DTMF của script (xem [Scripts](/api/autocall/scripts)) | — |
| `data.agents[]` | array | Danh sách agent gán riêng vào chiến dịch (rỗng nếu không gán) | — |

**Response 404** (campaign không tồn tại hoặc thuộc khách hàng khác):
```json
{ "message": "Campaign không tồn tại" }
```

### `GET /api/autocall/campaigns/{id}/stats`

**Path params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `id` | integer | Có | ID chiến dịch | Số nguyên dương |

**Response 200**:
```json
{
  "data": {
    "total_leads": 487,
    "total_calls": 312,
    "total_connected": 198,
    "total_failed": 89,
    "total_no_answer": 65,
    "total_busy": 18,
    "connection_rate": 63.5
  }
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data.total_leads` | integer | Tổng lead đã import vào chiến dịch | >= 0 |
| `data.total_calls` | integer | Tổng cuộc đã dial | >= 0 |
| `data.total_connected` | integer | Tổng cuộc connect thành công (B-leg answer) | >= 0 |
| `data.total_failed` | integer | Tổng cuộc fail (đếm gộp `failed` + `no_answer` + `busy`) | >= 0 |
| `data.total_no_answer` | integer | Tổng cuộc không bắt máy | >= 0 |
| `data.total_busy` | integer | Tổng cuộc máy bận | >= 0 |
| `data.connection_rate` | number | Tỷ lệ kết nối thành công (`total_connected / total_calls * 100`) | 0-100, làm tròn 1 chữ số thập phân |

### `GET /api/autocall/campaigns/{id}/attempts?per_page=50`

Danh sách cuộc gọi của campaign (phân trang chuẩn `page`/`per_page`, default 50, max 200).

**Path params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `id` | integer | Có | ID chiến dịch | Số nguyên dương |

**Query params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `page` | integer | Không | Trang phân trang (1-indexed) | >= 1, default `1` |
| `per_page` | integer | Không | Số attempt mỗi trang | 1-200, default `50` |

**Response 200**:
```json
{
  "data": [
    {
      "id": 8721,
      "uuid": "093e1024-1234-5678-9abc-def012345678",
      "campaign_id": 36,
      "lead_id": 78912,
      "lead_phone_number": "0912345678",
      "attempt_number": 1,
      "started_at": "2026-06-24T08:32:00Z",
      "answered_at": "2026-06-24T08:32:05Z",
      "ended_at": "2026-06-24T08:32:47Z",
      "duration_sec": 42,
      "result": "connected",
      "hangup_cause": "NORMAL_CLEARING",
      "dtmf_pressed": "2",
      "final_action": "queue:support_queue"
    }
  ],
  "current_page": 1,
  "last_page": 7,
  "per_page": 50,
  "total": 312
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data[].id` | integer | ID attempt | Số nguyên dương |
| `data[].uuid` | string | UUID cuộc gọi (dùng để hangup hoặc tra cứu) | UUID v4 |
| `data[].campaign_id` | integer | ID chiến dịch | — |
| `data[].lead_id` | integer | ID lead | — |
| `data[].lead_phone_number` | string | Số điện thoại lead (format E.164 `84xxx`) | — |
| `data[].attempt_number` | integer | Lần thử thứ mấy | 1-N |
| `data[].started_at` | datetime ISO 8601 | Thời điểm bắt đầu originate (UTC) | — |
| `data[].answered_at` | datetime ISO 8601 \| null | Thời điểm B-leg answer (UTC) | null nếu không answer |
| `data[].ended_at` | datetime ISO 8601 | Thời điểm cuộc gọi kết thúc (UTC) | — |
| `data[].duration_sec` | integer | Tổng thời lượng cuộc gọi (giây) | >= 0 |
| `data[].result` | string | Kết quả cuộc gọi | `connected` / `no_answer` / `busy` / `failed` / `abandoned` |
| `data[].hangup_cause` | string | Mã hangup từ Zorio PBX | `NORMAL_CLEARING` / `NO_ANSWER` / `USER_BUSY` / ... |
| `data[].dtmf_pressed` | string \| null | Phím DTMF khách hàng bấm (nếu có) | `0`-`9`, `*`, `#`, null |
| `data[].final_action` | string \| null | Action cuối cùng đã thực thi | `queue:<name>` / `playback:<url>` / `hangup` / `switch:<id>` |
| `current_page` | integer | Trang hiện tại | >= 1 |
| `last_page` | integer | Số trang cuối | >= 1 |
| `per_page` | integer | Số item mỗi trang | 1-200 |
| `total` | integer | Tổng số attempt khớp filter | >= 0 |

## Caller-ID Groups (read-only picker)

### `GET /api/autocall/caller-id-pools`

Lấy danh sách pool đầu số để dùng làm `caller_id_group_id` khi tạo campaign.

**Response 200**:
```json
{
  "data": [
    {
      "id": 3,
      "name": "Pool VNPT 028",
      "label": "Pool VNPT 028",
      "description": "5 số 028xxxx, rotation Round Robin"
    }
  ]
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data[].id` | integer | ID pool — dùng làm `caller_id_group_id` khi `POST /api/autocall/campaigns` | Số nguyên dương |
| `data[].name` | string | Tên pool (định danh kỹ thuật) | Tối đa 255 ký tự |
| `data[].label` | string | Tên hiển thị friendly cho UI | Tối đa 255 ký tự |
| `data[].description` | string \| null | Mô tả ngắn về pool (cách rotation, danh sách số...) | — |

## Hangup cuộc gọi đang chạy

Hangup cuộc gọi đang chạy cho campaign AutoCall — AutoCall và Telesales chia sẻ endpoint hangup chung.

```http
POST /api/telesales/calls/{uuid}/hangup
```

**Path params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `uuid` | string | Có | UUID cuộc gọi (lấy từ webhook `call.answered` event hoặc field `uuid` trong attempt) | UUID v4 thuộc tài khoản hiện tại |

**Request mẫu**:
```bash
curl -X POST https://app.zorio.vn/api/telesales/calls/abc-def-123/hangup \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

**Response 200**:
```json
{ "success": true }
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `success` | boolean | Đã gửi lệnh hangup tới Zorio PBX thành công | `true` |

**Error 404** (uuid không tồn tại hoặc không thuộc tài khoản):
```json
{ "error": "Cuộc gọi không tồn tại" }
```

::: warning Permission
Cần `manage_telesales_campaigns` hoặc role `admin`. Cuộc gọi sẽ kết thúc với hangup cause `NORMAL_CLEARING`.
:::


---

# AutoCall TTS API — Tổng quan

<!-- source: https://docs.zorio.vn/api/autocall/index.md -->

# AutoCall TTS API — Tổng quan

> Public REST API cho Module AutoCall TTS — tự động hoá outbound với giọng đọc tự nhiên + DTMF actions + voices library.
>
> **Xác thực**: Bearer Token (phiên user). **Base URL**: `https://app.zorio.vn/api/autocall/` (cấp riêng theo khách hàng).

## Phạm vi

AutoCall API gồm các nhóm chính:

- Quản lý chiến dịch (Campaigns).
- Script + DTMF actions (playback / playback_then_hangup / switch_script / queue / repeat_script / hangup).
- Leads + Variables (placeholder `{{xxx}}` trong template).
- Voices + Media files (tier A premium realtime, tier B local pre-rendered).
- Reports — KPIs / Trend / Comparison / Hangup / Heatmap / DTMF / Funnel / Export.
- Webhook events.

## Tier A/B

- **Tier A**: premium realtime — TTS qua provider (nhà cung cấp TTS cao cấp) tính phí theo ký tự, khách hàng cấp key.
- **Tier B**: local unlimited — dùng audio library vi-VN-female-01 pre-rendered, không phí. Khuyến nghị default cho volume lớn.

## Glossary

| Thuật ngữ | Giải thích |
|---|---|
| Campaign | Chiến dịch outbound TTS gắn 1 script + danh sách lead + cấu hình caller-ID + tốc độ dial |
| Script | Kịch bản TTS gồm `template_text` chứa biến `{{placeholder}}` + cây DTMF action |
| DTMF | Mã phím khách bấm sau khi nghe TTS (0-9, *, #) — Zorio capture để branching |
| DTMF action | Hành động khi khách bấm phím — `playback` / `playback_then_hangup` / `switch_script` / `queue` / `repeat_script` / `hangup` |
| Lead | 1 số điện thoại cần gọi + payload biến TTS tương ứng |
| Variable | Biến do khách hàng định nghĩa, đại diện cho data động trong script (vd `customer_name`, `appointment_date`, `callback_date`) |
| Voice | Giọng đọc cụ thể (vd "vi-VN-female-01" Tier B, "Roger" Tier A nhà cung cấp TTS cao cấp) |
| Media file | File audio upload sẵn để playback (không qua TTS) — dùng cho intro fixed, music on hold, IVR fallback |
| Tier A | TTS realtime qua provider — chất lượng cao, tính phí theo char |
| Tier B | Audio library pre-rendered — không phí, throughput cao, voice fix |
| Attempt | 1 lần dial 1 lead — có thể retry nếu busy / no_answer |
| Hangup cause | Mã chuẩn Q.850 chỉ lý do cuộc gọi kết thúc — xem [Hangup codes](/tham-chieu/hangup-codes) |

## End-to-end workflow

```
1. Login                  POST /api/auth/login        → Bearer token
2. Tạo script             POST /api/autocall/scripts  → ID + template_text + dtmf_actions
3. Tạo campaign           POST /api/autocall/campaigns → bind script_id + caller_id_group_id
4. Import lead            POST /api/autocall/campaigns/{id}/leads
5. Khởi chạy              POST /api/autocall/campaigns/{id}/start
6. Theo dõi realtime      Webhook autocall.lead.* gửi tới URL của bạn
7. Xem báo cáo            GET  /api/autocall/campaigns/{id}/reports/...
8. Pause / Resume / Stop  POST /api/autocall/campaigns/{id}/pause | resume | stop
```

## Xác thực

Dùng Bearer Token (phiên user) — xem chi tiết [Xác thực](/auth/sanctum-bearer).

```
Authorization: Bearer <token>
Accept: application/json
```

Permission yêu cầu: `autocall_api_access` (admin role có sẵn). Một số endpoint nhạy cảm (vd start campaign) cần thêm `autocall_manage_campaign`.

## Các nhóm endpoint

| Nhóm | Tài liệu |
|---|---|
| Campaigns | [Tới trang](/api/autocall/campaigns) |
| Scripts + DTMF actions | [Tới trang](/api/autocall/scripts) |
| Leads + Variables | [Tới trang](/api/autocall/leads) |
| Voices + Media files | [Tới trang](/api/autocall/voices) |
| Reports | [Tới trang](/api/autocall/reports) |
| Webhook events AutoCall | [Tới trang](/api/autocall/webhooks) |

## Quy ước chung

### Pagination

Mọi list endpoint dùng `?page=1&per_page=50` (tối đa 200). Response paginated chuẩn — xem [Quy ước chung](/bat-dau/quy-uoc).

### Response shape

```json
{ "data": {} }                              // single resource
{ "current_page": 1, "data": [], ... }      // list paginated
{ "message": "...", "errors": {} }          // 422 validation
```

### Timezone

ISO 8601 với offset (`2026-06-30T07:30:45+00:00`). Backend hệ thống trả với microseconds (`.000000Z`) — request chấp nhận cả hai format.

### Số điện thoại

- Lưu DB ở format E.164 không dấu `+` (vd `84987654321`).
- Request body chấp nhận `0xxx` hoặc `84xxx` — backend tự normalize.
- Response trả format gốc client gửi lên (preserve).

## Rate limit

| Endpoint group | Limit |
|---|---|
| `/api/autocall/*` | 120 req/phút/token |
| `/api/autocall/campaigns/{id}/leads` (import bulk) | 30 req/phút/token |
| `/api/autocall/campaigns/{id}/start` | 5 req/phút/token |

Xem chi tiết [Rate limit + Idempotency](/auth/rate-limit).

## HTTP Status Codes

| HTTP | Khi nào |
|---|---|
| 200 | OK |
| 201 | Created (campaign / script / lead mới) |
| 202 | Accepted (campaign start enqueued, audio render đang chạy) |
| 401 | Token thiếu / sai / expired |
| 403 | Thiếu permission `autocall_api_access` hoặc `autocall_manage_campaign` |
| 404 | Resource không tồn tại trong tài khoản |
| 409 | State machine vi phạm (vd start campaign đã running) |
| 422 | Validation lỗi — `errors[]` chi tiết field |
| 429 | Rate limit hit |
| 500 | Server error |

## Base URL

| | URL |
|---|---|
| Production | `https://app.zorio.vn/api/autocall/` (cấp riêng theo khách hàng) |

## FAQ

**Q1: Voice tiếng Việt nào tốt nhất?**

A: Tier B đã có **vi-VN-female-01** pre-rendered — chất lượng cao, không phí, throughput cao. Tier A có nhiều voice hơn qua provider — list qua `GET /api/autocall/voices`.

**Q2: Bao nhiêu lead 1 campaign tối đa?**

A: Không giới hạn cứng. Recommend ≤ **100.000 lead** per campaign để engine xử lý mượt.

**Q3: Khách bấm DTMF, tôi nhận data ở đâu?**

A: Subscribe webhook `autocall.lead.dtmf_pressed` — fire mỗi lần bấm phím. Payload có `digit` + `lead_id` + `script_id`.

**Q4: Audio render lỗi — khắc phục thế nào?**

A: Check theo thứ tự:
1. `voice_id` còn `status=active` trong `/api/autocall/voices`?
2. Provider Tier A có key valid + còn quota?
3. Tier B: `voice_id` có pre-render trong audio library?
4. Template có biến `{{xxx}}` chưa định nghĩa trong Variables?

**Q5: Có thể chuyển sang agent thật khi khách bấm DTMF không?**

A: Có — dùng `action_type=queue` trong DTMF action, set `target_queue_name`. Khách sẽ được transfer vào hàng đợi, agent sẽ nhận.


---

# Leads + Variables

<!-- source: https://docs.zorio.vn/api/autocall/leads.md -->

# Leads + Variables

Quản lý lead (import bulk, list, blacklist/DNC) và biến TTS do khách hàng tự định nghĩa dùng trong template `template_text`.

## Push lead vào chiến dịch (bulk)

```http
POST /api/autocall/campaigns/{id}/leads/import
```

**Path params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `id` | integer | Có | ID chiến dịch nhận lead | Số nguyên dương tồn tại trong tài khoản |

**Body**:
```json
{
  "leads": [
    {
      "phone": "0912345678",
      "payload": {
        "name": "Nguyễn Văn An",
        "amount": "500000",
        "callback_date": "2026-06-30",
        "loan_id": "LN-12345"
      }
    },
    {
      "phone": "0987654321",
      "payload": {
        "name": "Trần Thị Bích",
        "amount": "1200000",
        "callback_date": "2026-07-05"
      }
    }
  ]
}
```

**Body fields**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `leads` | array | Có | Mảng lead cần push vào chiến dịch | Tối đa 5000 item/request |
| `leads[].phone` | string | Có | Số điện thoại lead, format Việt Nam | `0xxx` / `84xxx` / `+84xxx` (auto-normalize). Legacy alias `phone_number` được chấp nhận |
| `leads[].payload` | object | Có (nếu template có biến) | JSON object chứa biến TTS theo `variable_code`. Legacy alias `variables` được chấp nhận | Key snake_case khớp `variable_code` đã định nghĩa |

**Field `phone`**: bắt buộc, format Việt Nam. **DB nội bộ lưu format E.164 `84xxx`** (cho dedup + DNC matching) nhưng **API GET trả về format gốc `0xxx`** để khớp với input client. *Legacy alias `phone_number` vẫn được chấp nhận trong body request cho backward compat — KHUYẾN NGHỊ dùng `phone` cho integration mới.*

::: tip Ví dụ
Client gửi `"phone": "0987654321"` -> response `GET` trả `"phone_number": "0987654321"`. Hệ thống lưu format E.164 `84987654321` để dedup với DNC. Search `?phone=0987` được hệ thống tự normalize.
:::

**Field `payload`**: JSON object chứa biến TTS theo `variable_code` đã định nghĩa trong pool (xem [Variables](#variables-bien-tts)). Key phải match `variable_code` (lowercase, snake_case). *Legacy alias `variables` được chấp nhận.*

**Behaviour**:
- Lead trùng phone trong cùng campaign -> skip -> đếm vào `skipped_duplicate`
- Lead nằm trong DNC -> skip -> đếm vào `skipped_dnc`
- Phone format không hợp lệ -> skip -> đếm vào `skipped_invalid`, lý do `invalid_phone_format`
- **Payload thiếu biến required** trong `script.template_text` placeholder `{{xxx}}` -> skip -> đếm vào `skipped_invalid`, lý do `missing_variables`
- Lead inserted với `status=pending`, audio render job dispatch async
- Nếu campaign đang `active` -> engine pick lead ngay khi audio sẵn sàng

::: warning Validate variables vs template_text
Hệ thống extract placeholder `{{xxx}}` từ `script.template_text` của campaign -> mọi key này PHẢI có trong `payload` của lead. Thiếu key nào -> reject lead, log vào `errors[]` (max 20 sample). Đảm bảo audio render thành công cho mọi lead.
:::

**Response 200** (case có lead thiếu biến):
```json
{
  "data": {
    "inserted": 1,
    "skipped_invalid": 2,
    "skipped_duplicate": 0,
    "skipped_dnc": 0,
    "errors": [
      {
        "index": 0,
        "phone": "0912345678",
        "reason": "missing_variables",
        "missing": ["tong_can_thanh_toan", "ngay_den_han"],
        "hint": "Script template_text yêu cầu các biến: {{tong_can_thanh_toan}}, {{ngay_den_han}} — payload đang thiếu các biến này."
      },
      { "index": 487, "phone": "0912abc", "reason": "invalid_phone_format" }
    ]
  }
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data.inserted` | integer | Số lead insert thành công | >= 0 |
| `data.skipped_invalid` | integer | Số lead bị skip do invalid (sai phone format / thiếu biến) | >= 0 |
| `data.skipped_duplicate` | integer | Số lead bị skip do trùng phone trong cùng chiến dịch | >= 0 |
| `data.skipped_dnc` | integer | Số lead bị skip do nằm trong DNC | >= 0 |
| `data.errors[]` | array | Danh sách lỗi mẫu (tối đa 20 item) | — |
| `data.errors[].index` | integer | Vị trí lead trong array `leads` của request | 0-indexed |
| `data.errors[].phone` | string | Số điện thoại lead lỗi | — |
| `data.errors[].reason` | string | Lý do skip | `missing_variables` / `invalid_phone_format` / `duplicate` / `dnc_blocked` |
| `data.errors[].missing` | string[] | Danh sách biến thiếu (chỉ với `reason=missing_variables`) | — |
| `data.errors[].hint` | string | Gợi ý fix lỗi | — |

::: tip Bulk limit
Lead push bulk tối đa **5000 lead/request** (chunk client-side nếu nhiều hơn). Rate limit lead import: **5 batch/phút/token**.
:::

## List leads

### `GET /api/autocall/campaigns/{id}/leads?status=pending&page=1`

**Path params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `id` | integer | Có | ID chiến dịch | Số nguyên dương |

**Query params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `status` | string \| string[] | Không | Lọc theo trạng thái lead (single hoặc dùng `status[]=a&status[]=b`) | `pending` / `dialing` / `connected` / `completed` / `failed` / `abandoned` / `blacklisted` |
| `phone` | string | Không | Tìm gần đúng theo số điện thoại (auto-normalize 84xxx) | Chuỗi số |
| `page` | integer | Không | Trang phân trang | >= 1, default `1` |
| `per_page` | integer | Không | Số lead mỗi trang | 1-200, default `50` |

**Response 200**:
```json
{
  "data": [
    {
      "id": 78912,
      "campaign_id": 36,
      "phone_number": "84912345678",
      "payload": {"name": "Nguyễn Văn An", "amount": "500000"},
      "status": "completed",
      "attempt_count": 1,
      "last_attempt_at": "2026-06-24T08:32:00Z",
      "last_hangup_cause": "NORMAL_CLEARING",
      "next_retry_at": null,
      "final_audio_path": "/audio/render/lead_78912.wav",
      "created_at": "2026-06-24T07:35:00Z"
    }
  ],
  "current_page": 1,
  "last_page": 10,
  "per_page": 50,
  "total": 487
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data[].id` | integer | ID lead | Số nguyên dương |
| `data[].campaign_id` | integer | ID chiến dịch | — |
| `data[].phone_number` | string | Số điện thoại format E.164 (`84xxx`) | — |
| `data[].payload` | object | Biến TTS đã nhận khi import | Key snake_case |
| `data[].status` | string | Trạng thái lifecycle của lead | `pending` / `dialing` / `connected` / `completed` / `failed` / `abandoned` / `blacklisted` |
| `data[].attempt_count` | integer | Số lần đã gọi | >= 0 |
| `data[].last_attempt_at` | datetime ISO 8601 \| null | Thời điểm attempt gần nhất (UTC) | — |
| `data[].last_hangup_cause` | string \| null | Hangup cause của attempt cuối | `NORMAL_CLEARING` / `NO_ANSWER` / ... |
| `data[].next_retry_at` | datetime ISO 8601 \| null | Thời điểm lên lịch retry tiếp theo (UTC) | null nếu không retry tiếp |
| `data[].final_audio_path` | string \| null | Đường dẫn file wav render xong (server local) | — |
| `data[].created_at` | datetime ISO 8601 | Thời điểm import lead (UTC) | — |
| `current_page` | integer | Trang hiện tại | >= 1 |
| `last_page` | integer | Số trang cuối | >= 1 |
| `per_page` | integer | Số item mỗi trang | 1-200 |
| `total` | integer | Tổng số lead khớp filter | >= 0 |

### `GET /api/autocall/leads?campaign_id=36&phone=0912&status[]=completed&status[]=failed`

Liệt kê lead cross-campaign. Response shape giống endpoint trên (`data[]` + pagination).

**Query params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `campaign_id` | integer | Không | Lọc theo chiến dịch | ID chiến dịch tồn tại |
| `phone` | string | Không | Tìm gần đúng theo số điện thoại | — |
| `status[]` | string[] | Không | Lọc nhiều trạng thái | `pending` / `dialing` / `connected` / `completed` / `failed` / `abandoned` / `blacklisted` |
| `from` | datetime ISO 8601 | Không | Lọc theo `created_at >= from` | `YYYY-MM-DD` hoặc ISO 8601 |
| `to` | datetime ISO 8601 | Không | Lọc theo `created_at <= to` | `YYYY-MM-DD` hoặc ISO 8601 |
| `per_page` | integer | Không | Số lead mỗi trang | 1-200, default `50` |

## Bulk action

### Blacklist

```http
POST /api/autocall/leads/blacklist
```

**Body**:
```json
{
  "phones": ["0912345678", "0987654321"],
  "lead_ids": [78912, 78913],
  "reason": "Khách hàng yêu cầu không gọi",
  "source": "customer_request"
}
```

**Body fields**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `phones` | string[] | Không (1 trong 2) | Danh sách số điện thoại cần blacklist | Format Việt Nam (`0xxx` / `84xxx`) |
| `lead_ids` | integer[] | Không (1 trong 2) | Danh sách lead ID — phone tương ứng được auto-resolve và merge vào `phones` | ID lead tồn tại |
| `reason` | string | Không | Lý do blacklist (lưu vào DNC log) | Tối đa 500 ký tự |
| `source` | string | Không | Nguồn gốc blacklist | `manual` / `customer_request` / `duplicate` / `complaint` / `other` (default `manual`) |

**Response 200**:
```json
{ "data": { "blacklisted": 2 } }
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data.blacklisted` | integer | Số phone đã insert vào DNC (đã dedup) | >= 0 |

### Unblacklist

```http
POST /api/autocall/leads/unblacklist
{ "phones": ["0912345678"] }
```

**Body fields**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `phones` | string[] | Có | Danh sách phone cần xoá khỏi DNC | Format Việt Nam |

**Response 200**: `{"data": {"unblacklisted": 1}}`

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data.unblacklisted` | integer | Số phone đã xoá khỏi DNC | >= 0 |

### Bulk re-render audio

```http
POST /api/autocall/leads/bulk-rerender
{ "lead_ids": [78912, 78913] }
```

Dispatch lại job render audio cho các lead (vd khi script đổi -> cần render lại).

**Body fields**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `lead_ids` | integer[] | Có | Danh sách lead ID cần render lại audio | ID lead tồn tại trong tài khoản |

**Response 200**: `{"data": {"dispatched": 2}}`

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data.dispatched` | integer | Số job render đã dispatch vào queue | >= 0 |

## Do-Not-Call list

### `GET /api/autocall/dnc?phone=0912&source=manual`

**Query params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `phone` | string | Không | Tìm gần đúng theo số điện thoại | — |
| `source` | string | Không | Lọc theo nguồn blacklist | `manual` / `customer_request` / `duplicate` / `complaint` / `other` |
| `page` | integer | Không | Trang phân trang | >= 1, default `1` |
| `per_page` | integer | Không | Số item mỗi trang | 1-200, default `50` |

**Response 200**:
```json
{
  "data": [
    {
      "id": 543,
      "phone_number": "84912345678",
      "source": "customer_request",
      "reason": "Khách yêu cầu",
      "blocked_by": 7,
      "created_at": "2026-06-24T07:40:00Z"
    }
  ],
  "current_page": 1,
  "last_page": 12,
  "per_page": 50,
  "total": 567
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data[].id` | integer | ID record DNC | Số nguyên dương |
| `data[].phone_number` | string | Số điện thoại format E.164 (`84xxx`) | — |
| `data[].source` | string | Nguồn blacklist | `manual` / `customer_request` / `duplicate` / `complaint` / `other` |
| `data[].reason` | string \| null | Lý do blacklist | — |
| `data[].blocked_by` | integer \| null | User ID người thực hiện chặn | — |
| `data[].created_at` | datetime ISO 8601 | Thời điểm blacklist (UTC) | — |
| `current_page` | integer | Trang hiện tại | >= 1 |
| `last_page` | integer | Số trang cuối | >= 1 |
| `per_page` | integer | Số item mỗi trang | 1-200 |
| `total` | integer | Tổng số record khớp filter | >= 0 |

::: tip DNC global per tài khoản
Số trong DNC sẽ bị skip khỏi MỌI campaign của khách hàng đó.
:::

## Variables (biến TTS do khách hàng tự định nghĩa)

Biến do khách hàng định nghĩa dùng trong `template_text`. Khi render, hệ thống resolve `{{variable_code}}` theo `data_type` -> format đúng (số tiền -> đọc thành chữ, ngày -> "ngày 15 tháng 7"...).

### List variables

```http
GET /api/autocall/variables
```

**Response 200**:
```json
{
  "data": [
    {
      "id": 1,
      "code": "name",
      "label": "Tên khách hàng",
      "data_type": "name",
      "description": "Tên gọi của khách hàng"
    },
    {
      "id": 2,
      "code": "salutation_name",
      "label": "Xưng hô + Tên",
      "data_type": "salutation_name",
      "description": "VD: anh An, chị Bích"
    },
    {
      "id": 3,
      "code": "amount",
      "label": "Số tiền",
      "data_type": "money",
      "description": "Số tiền VND, sẽ đọc thành chữ"
    }
  ]
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data[].id` | integer | ID variable | Số nguyên dương |
| `data[].code` | string | Mã biến (dùng làm key trong `payload` khi import lead, dùng làm `{{code}}` trong `template_text`) | snake_case, max 64 ký tự, unique per tài khoản, immutable |
| `data[].label` | string | Tên hiển thị tiếng Việt | Tối đa 255 ký tự |
| `data[].data_type` | string | Loại dữ liệu để TTS đọc đúng format | `name` / `salutation_name` / `salutation_fullname` / `fullname` / `date` / `time` / `number` / `money` |
| `data[].description` | string \| null | Mô tả cho người dùng | Tối đa 2000 ký tự |

**Data types hỗ trợ**:

| `data_type` | Mô tả | Ví dụ input | Output đọc |
|---|---|---|---|
| `name` | Tên rút gọn | "Nam" | "Nam" |
| `salutation_name` | Xưng hô + Tên | "anh Nam" | "anh Nam" |
| `salutation_fullname` | Xưng hô + Họ tên | "anh Nguyễn Văn Nam" | đầy đủ |
| `fullname` | Họ tên | "Nguyễn Văn Nam" | đầy đủ |
| `date` | Ngày Y-m-d | "2026-06-30" | "ngày ba mươi tháng sáu năm hai nghìn không trăm hai mươi sáu" |
| `time` | Giờ H:i | "14:30" | "mười bốn giờ ba mươi phút" |
| `number` | Số nguyên | "1234" | "một nghìn hai trăm ba mươi tư" |
| `money` | Số tiền VND | "500000" | "năm trăm nghìn đồng" |

### CRUD variables (admin only)

```http
POST   /api/autocall/variables       (admin tier)
PUT    /api/autocall/variables/{id}
DELETE /api/autocall/variables/{id}
```

Body create/update:
```json
{
  "code": "loan_id",
  "label": "Mã hợp đồng",
  "data_type": "name",
  "description": "Format LN-xxxxx",
  "example_value": "LN-12345",
  "sort_order": 100,
  "is_active": true
}
```

| Field | Required | Type | Default | Mô tả |
|---|---|---|---|---|
| `code` | Có (create) | string, max 64, snake_case | — | Variable key, unique per tài khoản, **immutable** sau khi tạo |
| `label` | Có | string, max 255 | — | Tên hiển thị |
| `data_type` | Có | enum (8 type, xem bảng phía trên) | — | Loại dữ liệu để TTS đọc đúng format |
| `description` | Không | string, max 2000 | null | Mô tả |
| `example_value` | Không | string | null | Giá trị mẫu dùng cho TTS preview |
| `sort_order` | Không | integer | 999 | Thứ tự hiển thị trong UI picker |
| `is_active` | Không | boolean | true | Tắt variable (KHÔNG xoá) — script vẫn render nhưng UI ẩn |

`is_builtin: true` (read-only) đánh dấu các variable hệ thống cung cấp sẵn — KHÔNG cho phép xoá hoặc đổi `code`.

**`POST /api/autocall/variables` response 201**:
```json
{
  "data": {
    "id": 15,
    "code": "loan_id",
    "label": "Mã hợp đồng",
    "data_type": "name",
    "description": "Format LN-xxxxx",
    "example_value": "LN-12345",
    "sort_order": 100,
    "is_active": true,
    "is_builtin": false,
    "tenant_id": 1,
    "created_at": "2026-06-25T03:00:00Z",
    "updated_at": "2026-06-25T03:00:00Z"
  }
}
```

**`PUT /api/autocall/variables/{id}` response 200**: shape giống POST response (object đã update). Chỉ truyền field cần đổi (partial update). Field `code` immutable — hệ thống bỏ qua nếu gửi.

**`DELETE /api/autocall/variables/{id}` response 200**:
```json
{ "data": { "deleted": true } }
```

**Response 422** (variable hệ thống):
```json
{ "message": "Không thể xoá biến hệ thống (is_builtin=true)" }
```

**Response 422** (validation create — vd `code` trùng):
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "code": ["The code has already been taken."]
  }
}
```


---

# Reports

<!-- source: https://docs.zorio.vn/api/autocall/reports.md -->

# Reports

Các endpoint báo cáo cho campaign AutoCall — KPIs, trend, comparison, hangup analysis, heatmap, DTMF analytics, funnel + export Excel.

::: tip Permission yêu cầu
Mọi endpoint dưới đây cần `autocall_api_access`. Endpoint export cần thêm `autocall_export_report`.
:::

## GET `/api/autocall/campaigns/{id}/reports/kpis` — KPIs tổng quan

### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `from` | datetime | optional | Bắt đầu cửa sổ thống kê | ISO 8601. Default: lúc campaign start |
| `to` | datetime | optional | Kết thúc cửa sổ | ISO 8601. Default: now |
| `timezone` | string | optional | Múi giờ aggregate | Default: `Asia/Ho_Chi_Minh` |

### Response 200

```json
{
  "data": {
    "total_leads": 5000,
    "dialed": 4823,
    "answered": 3120,
    "no_answer": 1234,
    "busy": 287,
    "failed": 182,
    "abandoned": 0,
    "answer_rate_pct": "64.69",
    "avg_call_duration_sec": 42,
    "total_talk_time_sec": 131040,
    "dtmf_distribution": {
      "1": 1840,
      "2": 950,
      "0": 215,
      "no_input": 115
    },
    "transfer_to_queue_count": 1840,
    "transfer_success_rate_pct": "98.21",
    "computed_at": "2026-06-30T08:00:00+00:00"
  }
}
```

### Field giải thích

| Field | Mô tả |
|---|---|
| `total_leads` | Tổng lead trong campaign |
| `dialed` | Số attempt đã thực hiện (1 lead có thể nhiều attempt) |
| `answered` / `no_answer` / `busy` / `failed` | Phân loại theo `result` |
| `answer_rate_pct` | `answered ÷ dialed × 100` — chỉ số chính đo chất lượng pool |
| `avg_call_duration_sec` | Trung bình `billsec` của cuộc answered |
| `dtmf_distribution` | Phân bố phím khách bấm (key = digit, value = count) |
| `transfer_to_queue_count` | Số cuộc đã transfer thành công vào queue agent |

## GET `/api/autocall/campaigns/{id}/reports/trend` — Xu hướng theo ngày

### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `from` | date | optional | Ngày bắt đầu | YYYY-MM-DD |
| `to` | date | optional | Ngày kết thúc | YYYY-MM-DD |
| `granularity` | string | optional | Độ chi tiết | `day` (default), `hour` |

### Response 200

```json
{
  "data": [
    {
      "bucket": "2026-06-28",
      "dialed": 1200,
      "answered": 780,
      "answer_rate_pct": "65.00",
      "avg_duration_sec": 41,
      "transfer_count": 460
    },
    {
      "bucket": "2026-06-29",
      "dialed": 1612,
      "answered": 1098,
      "answer_rate_pct": "68.11",
      "avg_duration_sec": 43,
      "transfer_count": 642
    }
  ]
}
```

Dùng cho biểu đồ line chart theo dõi chiến dịch theo thời gian.

## GET `/api/autocall/campaigns/comparison` — So sánh nhiều campaign

::: tip Endpoint cross-campaign
Khác với các endpoint khác (nested theo campaign), endpoint này nằm trực tiếp dưới `/campaigns/comparison` để so sánh N campaign cùng lúc.
:::

### Query parameters

| Field | Type | Required | Mô tả |
|---|---|---|---|
| `campaign_ids` | string | ✅ | Danh sách ID campaign, comma-separated (vd `5,8,12`) |
| `metric` | string | optional | Metric so sánh: `answer_rate_pct` (default) / `avg_duration_sec` / `transfer_rate_pct` |

### Response 200

```json
{
  "data": [
    { "campaign_id": 5,  "campaign_name": "Renewal Q3",      "metric_value": "62.30" },
    { "campaign_id": 8,  "campaign_name": "Cross-sell Q3",   "metric_value": "55.18" },
    { "campaign_id": 12, "campaign_name": "Win-back churned", "metric_value": "48.92" }
  ]
}
```

## GET `/api/autocall/campaigns/{id}/reports/hangup` — Phân tích lý do cúp

Giúp nhóm vận hành biết campaign fail vì lý do gì để optimize.

### Response 200

```json
{
  "data": {
    "total_calls": 4823,
    "by_hangup_cause": [
      { "hangup_cause": "NORMAL_CLEARING",   "count": 3120, "pct": "64.69" },
      { "hangup_cause": "NO_ANSWER",         "count": 1234, "pct": "25.59" },
      { "hangup_cause": "USER_BUSY",         "count": 287,  "pct": "5.95" },
      { "hangup_cause": "CALL_REJECTED",     "count": 95,   "pct": "1.97" },
      { "hangup_cause": "RECOVERY_ON_TIMER", "count": 87,   "pct": "1.80" }
    ]
  }
}
```

Tham chiếu mã hangup: [Hangup cause codes](/tham-chieu/hangup-codes).

## GET `/api/autocall/campaigns/{id}/reports/heatmap` — Heatmap giờ × thứ

Trực quan thời điểm hot nhất trong tuần để adjust schedule.

### Query parameters

| Field | Type | Required | Mô tả |
|---|---|---|---|
| `metric` | string | optional | `dialed` (default) / `answered` / `answer_rate_pct` |

### Response 200

```json
{
  "data": [
    { "day_of_week": 1, "hour": 9,  "dialed": 156, "answered": 102, "answer_rate_pct": "65.38" },
    { "day_of_week": 1, "hour": 10, "dialed": 178, "answered": 121, "answer_rate_pct": "67.98" },
    { "day_of_week": 2, "hour": 14, "dialed": 201, "answered": 134, "answer_rate_pct": "66.67" }
  ]
}
```

`day_of_week`: `0` = Chủ nhật, `1` = Thứ Hai, ... `6` = Thứ Bảy. Mảng phẳng 168 entries (7 ngày × 24 giờ).

## GET `/api/autocall/campaigns/{id}/reports/dtmf` — Phân tích DTMF chi tiết

### Response 200

```json
{
  "data": {
    "total_answered": 3120,
    "with_dtmf_input": 3005,
    "no_input": 115,
    "no_input_rate_pct": "3.69",
    "by_digit": [
      { "digit": "1", "count": 1840, "pct": "61.23", "label": "Đồng ý chuyển agent" },
      { "digit": "2", "count": 950,  "pct": "31.61", "label": "Không quan tâm" },
      { "digit": "0", "count": 215,  "pct": "7.16",  "label": "Nghe lại" }
    ],
    "by_script_path": [
      { "path": "intro → press_1 → queue_sales", "count": 1840 },
      { "path": "intro → press_2 → playback_polite → hangup", "count": 950 }
    ]
  }
}
```

`label` được lấy từ `dtmf_actions[].label` của script.

## GET `/api/autocall/campaigns/{id}/reports/funnel` — Funnel chuyển đổi

### Response 200

```json
{
  "data": [
    { "stage": "Imported lead",       "count": 5000, "drop_rate_pct": null    },
    { "stage": "Dialed",              "count": 4823, "drop_rate_pct": "3.54"  },
    { "stage": "Answered",            "count": 3120, "drop_rate_pct": "35.31" },
    { "stage": "Pressed valid DTMF",  "count": 3005, "drop_rate_pct": "3.69"  },
    { "stage": "Transferred to agent","count": 1840, "drop_rate_pct": "38.77" },
    { "stage": "Agent disposed",      "count": 1640, "drop_rate_pct": "10.87" }
  ]
}
```

`drop_rate_pct`: tỷ lệ giảm so với stage trước.

## POST `/api/autocall/campaigns/{id}/reports/export` — Xuất Excel

### Request body

| Field | Type | Required | Mô tả | Giá trị |
|---|---|---|---|---|
| `report_type` | string | ✅ | Loại báo cáo | `kpis` / `trend` / `hangup` / `dtmf` / `funnel` / `full` |
| `from` | date | optional | Cửa sổ from | YYYY-MM-DD |
| `to` | date | optional | Cửa sổ to | YYYY-MM-DD |
| `format` | string | optional | Format file | `xlsx` (default) / `csv` |

### Request Body (JSON)

```json
{
  "report_type": "full",
  "from": "2026-06-01",
  "to": "2026-06-30",
  "format": "xlsx"
}
```

### Response 202 (Accepted, async)

```json
{
  "data": {
    "job_id": "export_a7b3c5d2",
    "status": "queued",
    "report_type": "full",
    "estimated_seconds": 30
  }
}
```

### Polling status

```
GET /api/autocall/campaigns/{id}/reports/export/{job_id}
```

```json
{
  "data": {
    "job_id": "export_a7b3c5d2",
    "status": "ready",
    "download_url": "https://app.zorio.vn/api/public/exports/...?signature=...",
    "expires_in_seconds": 3600,
    "file_size": 542600,
    "completed_at": "2026-06-30T08:01:23+00:00"
  }
}
```

`status` enum: `queued` / `running` / `ready` / `failed` / `expired`.

### Download

`download_url` là signed URL TTL **1 giờ** — follow redirect để tải file `.xlsx`.

## Best practice

### Cache report

KPIs / Trend ít đổi (data aggregate mỗi phút). Cache 1-5 phút ở CRM để giảm load.

### Realtime vs Reports

- **Realtime** (lead-level updates): subscribe webhook `autocall.lead.*`.
- **Reports** (aggregate): poll endpoint này định kỳ (mỗi 1-5 phút).

KHÔNG poll Reports mỗi giây — vừa lãng phí rate limit vừa không cần thiết.

### Export với volume lớn

Campaign > 50k lead — export `full` có thể mất 1-2 phút. Tránh blocking UI:

1. Submit job qua POST → nhận `job_id`.
2. Poll status mỗi 5 giây.
3. `ready` → trigger download tự động hoặc hiển thị nút "Tải file".

## Tài liệu liên quan

- [AutoCall — Tổng quan](/api/autocall/)
- [AutoCall — Campaigns](/api/autocall/campaigns)
- [AutoCall — Webhooks](/api/autocall/webhooks)
- [Hangup cause codes](/tham-chieu/hangup-codes)


---

# Scripts + DTMF actions

<!-- source: https://docs.zorio.vn/api/autocall/scripts.md -->

# Scripts + DTMF actions

Quản lý kịch bản TTS (template + voice + DTMF actions) cho AutoCall. Bao gồm CRUD scripts, enum DTMF action types, danh sách queue helper và preview TTS.

## Tạo script

```http
POST /api/autocall/scripts
```

**Body**:
```json
{
  "name": "Chăm sóc chuẩn",
  "description": "Template cho campaign chăm sóc khách hàng kích hoạt lại sau 30-60 ngày",
  "template_text": "Xin chào {{salutation_name}}, chúng tôi xin nhắc bạn về lịch hẹn ngày {{callback_date}}. Vui lòng bấm phím 1 để xác nhận tham gia, phím 2 để chuyển nhân viên hỗ trợ, phím 9 để bỏ qua.",
  "voice_id": "voice_id_premium_02",
  "tts_tier": "B",
  "max_repeat_per_attempt": 1,
  "status": "draft",
  "dtmf_actions": [
    {
      "digit": "1",
      "label": "Xác nhận thanh toán",
      "action_type": "playback_then_hangup",
      "target_audio_url": "/media/thank_you.wav"
    },
    {
      "digit": "2",
      "label": "Chuyển nhân viên",
      "action_type": "queue",
      "target_queue_name": "support@default"
    },
    {
      "digit": "9",
      "label": "Bỏ qua",
      "action_type": "hangup"
    }
  ]
}
```

**Fields**:

| Field | Required | Type | Mô tả |
|---|---|---|---|
| `name` | Có | string, max:255 | Tên script |
| `template_text` | Có | text | Template với placeholder `{{variable_code}}` |
| `voice_id` | Có | string | ID giọng đọc — PHẢI lấy từ `GET /api/autocall/voices` ([Voices](/api/autocall/voices)). Hệ thống tự routing đến provider tương ứng. Truyền `voice_id` không tồn tại trong thư viện voice khả dụng -> **422**. |
| `tts_tier` | Không | enum (`A`/`B`, default `B`) | **A** = premium, render realtime từ nhà cung cấp TTS cao cấp với key của khách hàng, tính theo char usage. **B** = local unlimited, dùng thư viện voice tiếng Việt khả dụng sẵn, không phí, throughput cao. Khuyến nghị default `B` cho khối lượng lớn. |
| `max_repeat_per_attempt` | Không | integer (1-5, default 1) | Số lần phát lại audio nếu user không bấm DTMF |
| `status` | Không | enum (`draft`/`active`/`archived`, default `draft`) | Chỉ script `active` mới được engine sử dụng cho campaign chạy thực tế |
| `dtmf_actions[]` | Không | array max:12 | Cấu hình phím bấm, mỗi item gồm `digit`/`label`/`action_type`/`target_*` |

::: warning Field `voice_provider` KHÔNG có trong request body
Khách hàng KHÔNG truyền. Hệ thống tự routing theo `voice_id` -> tier tương ứng (A premium / B local). Response server vẫn TRẢ field này — read-only, cho biết provider đã được sử dụng.
:::

**Error 422 `voice_id` không tồn tại**:
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "voice_id": [
      "voice_id 'voice_id_premium_01' không tồn tại trong thư viện voice khả dụng. Lấy danh sách voice hợp lệ qua GET /api/autocall/voices."
    ]
  }
}
```

### DTMF action types

| `action_type` | Field bắt buộc kèm theo | Hành vi |
|---|---|---|
| `playback` | `target_audio_url` | Phát file rồi chờ DTMF tiếp |
| `playback_then_hangup` | `target_audio_url` | Phát file rồi ngắt máy |
| `switch_script` | `target_script_id` | Load script khác, replay từ đầu |
| `queue` | `target_queue_name` (= `name` định danh queue) | Chuyển vào queue, agent live tiếp nhận |
| `hangup` | — | Ngắt máy ngay |
| `repeat_script` | — | Replay full audio script hiện tại |

::: tip Lấy enum động qua API
Thay vì hardcode 6 action type ở client, KH có thể fetch enum đầy đủ từ `GET /api/autocall/dtmf-action-types` (xem mục [List action types](#list-action-types-cho-dtmf-enum-label)). Tương tự, danh sách `target_queue_name` lấy từ `GET /api/autocall/queues` (xem [List queue](#list-queue-cho-action-type-queue)).
:::

::: warning Validate ràng buộc tham chiếu (server-side)
- `playback` / `playback_then_hangup` -> `target_audio_url` PHẢI khớp `file_path` của 1 media file thuộc tài khoản (lấy từ `GET /api/media-files`). Truyền URL ngoài -> 422.
- `switch_script` -> `target_script_id` PHẢI là script tồn tại trong tài khoản (lấy từ `GET /api/autocall/scripts`). Truyền ID rác -> 422.
- `queue` -> `target_queue_name` PHẢI khớp `name` của queue active (lấy từ `GET /api/autocall/queues`). Sai -> 422.
:::

**Error 422 sample**:
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "dtmf_actions.0.target_audio_url": [
      "target_audio_url '/data/wrong/path.wav' không tồn tại trong Media Files của khách hàng. Upload file qua POST /api/media-files trước, rồi dùng file_path trả về."
    ]
  }
}
```

## List action types cho DTMF (enum + label)

```http
GET /api/autocall/dtmf-action-types
```

**Mục đích**: trả về enum 6 action type kèm label tiếng Việt + danh sách field bắt buộc kèm theo. KH integration dùng để build dropdown "Hành vi khi bấm phím" trong UI cấu hình DTMF mà không cần hardcode enum.

**Response 200**:
```json
{
  "data": [
    {
      "code": "playback",
      "label": "Phát audio",
      "description": "Phát file âm thanh URL chỉ định, sau đó tiếp tục kịch bản.",
      "required_fields": ["target_audio_url"]
    },
    {
      "code": "playback_then_hangup",
      "label": "Phát audio rồi cúp máy",
      "description": "Phát file âm thanh xong tự động cúp máy.",
      "required_fields": ["target_audio_url"]
    },
    {
      "code": "switch_script",
      "label": "Chuyển sang kịch bản khác",
      "description": "Chuyển cuộc gọi sang kịch bản AutoCall khác (chuỗi IVR).",
      "required_fields": ["target_script_id"]
    },
    {
      "code": "queue",
      "label": "Chuyển vào hàng đợi agent",
      "description": "Chuyển cuộc gọi vào hàng đợi để agent live tiếp nhận.",
      "required_fields": ["target_queue_name"]
    },
    {
      "code": "repeat_script",
      "label": "Lặp lại kịch bản",
      "description": "Phát lại kịch bản hiện tại từ đầu (cho khách nghe lại).",
      "required_fields": []
    },
    {
      "code": "hangup",
      "label": "Cúp máy",
      "description": "Kết thúc cuộc gọi ngay lập tức.",
      "required_fields": []
    }
  ]
}
```

**Field response**:

| Field | Type | Mô tả |
|---|---|---|
| `code` | string | Giá trị enum dùng cho `dtmf_actions[].action_type` khi `POST/PUT /scripts` |
| `label` | string | Nhãn tiếng Việt hiển thị trong dropdown UI |
| `description` | string | Mô tả ngắn để giải thích thêm cho user end |
| `required_fields` | string[] | Danh sách field bắt buộc đi kèm khi pick action này (vd `playback` -> bắt buộc kèm `target_audio_url`) |

## List queue cho action_type=queue

```http
GET /api/autocall/queues
```

**Mục đích**: trả về danh sách queue active để client dùng làm `target_queue_name` khi pick `action_type=queue`. Build dropdown "Chọn hàng đợi" trong UI.

**Response 200**:
```json
{
  "data": [
    {
      "id": 1,
      "name": "support_q1",
      "queue_number": "2001",
      "strategy": "ring_all"
    },
    {
      "id": 2,
      "name": "sales_outbound",
      "queue_number": "2002",
      "strategy": "longest_idle_agent"
    }
  ]
}
```

**Field response**:

| Field | Type | Mô tả |
|---|---|---|
| `id` | integer | ID queue trong DB (tham khảo) |
| `name` | string | Tên kỹ thuật của queue — DÙNG làm `target_queue_name` khi POST/PUT script với DTMF `queue` action |
| `queue_number` | string | Số extension queue (vd `2001`) — dùng hiển thị cho user end |
| `strategy` | string | Chiến lược phân phối: `ring_all` / `longest_idle_agent` / `round_robin` / ... |

::: danger Lưu ý quan trọng
Field `target_queue_name` trong `dtmf_actions[]` PHẢI khớp **`name`** của queue (không phải `queue_number` hay `id`). Nếu sai, dial sẽ fail vì hệ thống không nhận diện được queue.
:::

## Response 201 mẫu sau khi tạo script

```json
{
  "data": {
    "name": "Chăm sóc chuẩn",
    "description": "Template cho campaign chăm sóc khách hàng kích hoạt lại sau 30-60 ngày",
    "template_text": "Xin chào {{tong_can_thanh_toan}}, chúng tôi xin nhắc bạn về lịch hẹn ngày {{ngay_den_han}}. Vui lòng bấm phím 1 để xác nhận tham gia, phím 2 để chuyển nhân viên hỗ trợ, phím 9 để bỏ qua.",
    "voice_provider": "tts_provider_01",
    "voice_id": "evln-vi-nature",
    "tts_tier": "A",
    "max_repeat_per_attempt": 1,
    "status": "draft",
    "created_by": 3,
    "tenant_id": 1,
    "updated_at": "2026-06-25T04:37:49.000000Z",
    "created_at": "2026-06-25T04:37:49.000000Z",
    "id": 4,
    "dtmf_actions": [
      {
        "id": 1,
        "tenant_id": 1,
        "script_id": 4,
        "digit": "1",
        "label": "Xác nhận thanh toán",
        "action_type": "playback_then_hangup",
        "target_audio_url": "/media/thank_you.wav",
        "target_script_id": null,
        "target_queue_name": null,
        "sort_order": 0,
        "created_at": "2026-06-25T04:37:49.000000Z",
        "updated_at": "2026-06-25T04:37:49.000000Z"
      },
      {
        "id": 2,
        "tenant_id": 1,
        "script_id": 4,
        "digit": "2",
        "label": "Chuyển nhân viên",
        "action_type": "queue",
        "target_audio_url": null,
        "target_script_id": null,
        "target_queue_name": "support@default",
        "sort_order": 1,
        "created_at": "2026-06-25T04:37:49.000000Z",
        "updated_at": "2026-06-25T04:37:49.000000Z"
      },
      {
        "id": 3,
        "tenant_id": 1,
        "script_id": 4,
        "digit": "9",
        "label": "Bỏ qua",
        "action_type": "hangup",
        "target_audio_url": null,
        "target_script_id": null,
        "target_queue_name": null,
        "sort_order": 2,
        "created_at": "2026-06-25T04:37:49.000000Z",
        "updated_at": "2026-06-25T04:37:49.000000Z"
      }
    ]
  }
}
```

::: tip Field order + tenant_id
Hệ thống serialize field theo thứ tự **insert/create** + auto-injected (`created_at`/`updated_at`/`id`) ở cuối. Client KHÔNG dựa thứ tự key — parse theo key name. `tenant_id` xuất hiện trong cả script level và mỗi `dtmf_actions[]` item — redundant nhưng đúng vì cả 2 entity đều có `tenant_id`.
:::

## List / show / update / delete

| Endpoint | Mục đích |
|---|---|
| `GET /api/autocall/scripts?status=active` | List scripts (filter optional) |
| `GET /api/autocall/scripts/{id}` | Chi tiết kèm `dtmfActions` |
| `PUT /api/autocall/scripts/{id}` | Cập nhật. Nếu gửi `dtmf_actions` -> replace toàn bộ |
| `DELETE /api/autocall/scripts/{id}` | Soft delete (nếu đang dùng cho campaign -> 422) |

### `GET /api/autocall/scripts` — list

**Query params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `status` | string | Không | Lọc theo trạng thái script | `draft` / `active` / `archived` |

```json
{
  "data": [
    {
      "id": 2,
      "tenant_id": 1,
      "name": "Nhắc lịch hẹn",
      "description": null,
      "template_text": "Công ty ABC trân trọng thông báo lịch hẹn dịch vụ {{ngay_den_han}}  xác nhận tham gia trước 18 giờ {{ngay_den_han}}. Trường hợp đã xác nhận, vui lòng bỏ qua cuộc gọi này. Liên hệ tổng đài ấn phím 3. Xin cảm ơn",
      "voice_provider": "tts_provider_01",
      "voice_id": "voice_id_premium_02",
      "tts_tier": "B",
      "audio_fixed_paths": null,
      "max_repeat_per_attempt": 1,
      "status": "active",
      "created_by": 1,
      "created_at": "2026-06-22T03:34:01.000000Z",
      "updated_at": "2026-06-22T08:11:49.000000Z",
      "deleted_at": null
    }
  ]
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data[].id` | integer | ID script | Số nguyên dương |
| `data[].tenant_id` | integer | ID khách hàng sở hữu script | — |
| `data[].name` | string | Tên script | Tối đa 255 ký tự |
| `data[].description` | string \| null | Mô tả | Tối đa 2000 ký tự |
| `data[].template_text` | text | Template TTS với placeholder `{{variable_code}}` | — |
| `data[].voice_provider` | string | Provider TTS (read-only, derive từ `voice_id`) | `tts_provider_01` / `local` / ... |
| `data[].voice_id` | string | ID giọng đọc TTS | Lấy từ `GET /api/autocall/voices` |
| `data[].tts_tier` | string | Tier TTS | `A` (premium realtime) / `B` (local pre-rendered) |
| `data[].audio_fixed_paths` | object \| null | Cache các đoạn audio cố định (template không-biến) đã render. Không bắt buộc xử lý khi tích hợp | — |
| `data[].max_repeat_per_attempt` | integer | Số lần phát lại audio nếu user không bấm DTMF | 1-5 |
| `data[].status` | string | Trạng thái script | `draft` / `active` / `archived` |
| `data[].created_by` | integer | User ID người tạo | — |
| `data[].created_at` | datetime ISO 8601 | Thời điểm tạo (UTC, microseconds) | — |
| `data[].updated_at` | datetime ISO 8601 | Thời điểm cập nhật gần nhất (UTC, microseconds) | — |
| `data[].deleted_at` | datetime ISO 8601 \| null | Soft delete timestamp | null nếu chưa xoá |

::: tip Format timestamp
API trả ISO 8601 với microseconds `YYYY-MM-DDTHH:mm:ss.uuuuuuZ` (vd `2026-06-22T03:34:01.000000Z`). Client parse theo ISO 8601 chuẩn (microseconds optional).
:::

### `GET /api/autocall/scripts/{id}` — chi tiết

Object đầy đủ kèm `dtmf_actions[]`:
```json
{
  "data": {
    "id": 2,
    "tenant_id": 1,
    "name": "Nhắc lịch hẹn",
    "description": null,
    "template_text": "Công ty ABC trân trọng thông báo lịch hẹn dịch vụ {{ngay_den_han}}, với số tiền là {{tong_can_thanh_toan}}. ... Xin cảm ơn",
    "voice_provider": "tts_provider_01",
    "voice_id": "voice_id_premium_02",
    "tts_tier": "B",
    "audio_fixed_paths": null,
    "max_repeat_per_attempt": 1,
    "status": "active",
    "created_by": 1,
    "created_at": "2026-06-22T03:34:01.000000Z",
    "updated_at": "2026-06-22T08:11:49.000000Z",
    "deleted_at": null,
    "dtmf_actions": [
      {
        "id": 7,
        "script_id": 2,
        "digit": "1",
        "label": "Xác nhận thanh toán",
        "action_type": "playback_then_hangup",
        "target_audio_url": "/media/thank_you.wav",
        "target_script_id": null,
        "target_queue_name": null,
        "sort_order": 0,
        "created_at": "2026-06-22T03:34:01.000000Z",
        "updated_at": "2026-06-22T03:34:01.000000Z"
      },
      {
        "id": 8,
        "script_id": 2,
        "digit": "3",
        "label": "Chuyển tổng đài",
        "action_type": "queue",
        "target_audio_url": null,
        "target_script_id": null,
        "target_queue_name": "support_queue",
        "sort_order": 1,
        "created_at": "2026-06-22T03:34:01.000000Z",
        "updated_at": "2026-06-22T03:34:01.000000Z"
      }
    ]
  }
}
```

### `PUT /api/autocall/scripts/{id}` — cập nhật

**Request**:
```http
PUT /api/autocall/scripts/2
Content-Type: application/json
Authorization: Bearer <token>
```

**Body** (partial update — chỉ gửi field cần đổi; nếu gửi `dtmf_actions` thì hệ thống xoá toàn bộ DTMF cũ + tạo lại theo array mới):
```json
{
  "name": "Nhắc nợ đến hạn — v2",
  "description": "Cập nhật template cho Q3-2026",
  "voice_id": "voice_id_premium_01",
  "max_repeat_per_attempt": 2,
  "dtmf_actions": [
    {
      "digit": "1",
      "label": "Xác nhận thanh toán",
      "action_type": "playback_then_hangup",
      "target_audio_url": "/media/thank_you.wav"
    },
    {
      "digit": "3",
      "label": "Chuyển tổng đài",
      "action_type": "queue",
      "target_queue_name": "support@default"
    }
  ]
}
```

**Response 200** (full script đã update + `dtmf_actions[]` mới):
```json
{
  "data": {
    "id": 2,
    "tenant_id": 1,
    "name": "Nhắc nợ đến hạn — v2",
    "description": "Cập nhật template cho Q3-2026",
    "template_text": "Công ty ABC trân trọng thông báo lịch hẹn dịch vụ {{ngay_den_han}}, với số tiền là {{tong_can_thanh_toan}}. ... Xin cảm ơn",
    "voice_provider": "tts_provider_01",
    "voice_id": "voice_id_premium_01",
    "tts_tier": "B",
    "audio_fixed_paths": null,
    "max_repeat_per_attempt": 2,
    "status": "active",
    "created_by": 1,
    "created_at": "2026-06-22T03:34:01.000000Z",
    "updated_at": "2026-06-25T04:49:00.000000Z",
    "deleted_at": null,
    "dtmf_actions": [
      {
        "id": 9,
        "tenant_id": 1,
        "script_id": 2,
        "digit": "1",
        "label": "Xác nhận thanh toán",
        "action_type": "playback_then_hangup",
        "target_audio_url": "/media/thank_you.wav",
        "target_script_id": null,
        "target_queue_name": null,
        "sort_order": 0,
        "created_at": "2026-06-25T04:49:00.000000Z",
        "updated_at": "2026-06-25T04:49:00.000000Z"
      },
      {
        "id": 10,
        "tenant_id": 1,
        "script_id": 2,
        "digit": "3",
        "label": "Chuyển tổng đài",
        "action_type": "queue",
        "target_audio_url": null,
        "target_script_id": null,
        "target_queue_name": "support@default",
        "sort_order": 1,
        "created_at": "2026-06-25T04:49:00.000000Z",
        "updated_at": "2026-06-25T04:49:00.000000Z"
      }
    ]
  }
}
```

::: warning PUT replace DTMF
Nếu body có gửi `dtmf_actions[]`, hệ thống xoá toàn bộ DTMF cũ của script + tạo lại theo array mới. Nếu KHÔNG gửi `dtmf_actions` -> giữ nguyên DTMF cũ. -> IDs của DTMF mới sẽ KHÁC với IDs cũ (cũ đã bị delete).
:::

### `DELETE /api/autocall/scripts/{id}`

```json
{ "data": { "deleted": true } }
```

**Response 422** (script đang dùng cho campaign active):
```json
{ "message": "Không thể xoá script đang được campaign sử dụng. Hãy archive campaign trước." }
```

## Preview TTS — render demo

```http
POST /api/autocall/scripts/{id}/preview
```

**Path params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `id` | integer | Có | ID script cần preview | Số nguyên dương tồn tại trong tài khoản |

**Body** (optional):
```json
{
  "variables": {
    "salutation_name": "anh An",
    "amount": "500000",
    "callback_date": "2026-06-30"
  }
}
```

**Body fields**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `variables` | object | Không | Map `{variable_code: value}` để substitute placeholder `{{xxx}}` trong template. Bỏ trống -> hệ thống dùng giá trị demo mặc định theo `data_type` của mỗi biến | Key phải khớp `variable_code` đã định nghĩa |

**Response 200**:
```json
{
  "data": {
    "audio_url": "/api/autocall/scripts/12/preview-audio/preview_abc123.wav",
    "duration_sec": 12.4,
    "chars_used": 187
  }
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data.audio_url` | string | Đường dẫn nội bộ để stream file wav preview. GET với `Authorization` header trả binary `audio/wav` | Path relative cho `app.zorio.vn` |
| `data.duration_sec` | number | Thời lượng audio đã render (giây) | > 0, làm tròn 1 chữ số thập phân |
| `data.chars_used` | integer | Số ký tự đã sử dụng (tính phí với Tier A) | >= 0 |

::: tip Rate limit preview
TTS preview giới hạn **10 req/phút/token** (vì charge TTS provider tier A).
:::


---

# Voices + Media files

<!-- source: https://docs.zorio.vn/api/autocall/voices.md -->

# Voices + Media files

Hai nhóm tài nguyên dùng chung trong AutoCall:

- **Voices** — danh sách giọng đọc TTS khả dụng để dùng `voice_id` khi tạo script.
- **Media files** — file âm thanh (.wav/.mp3/...) dùng làm `target_audio_url` cho DTMF action `playback` / `playback_then_hangup`.

## List voices dùng được trong AutoCall (KHUYẾN NGHỊ cho integration)

```http
GET /api/autocall/voices
```

**Mục đích**: trả về danh sách **chỉ voice khả dụng**. Đây là voice **đảm bảo render preview/dial được** — KHÔNG bị lỗi `Voice không khả dụng` như khi pick voice tuỳ ý từ provider.

**Response 200** (chỉ 5 field cần thiết cho client):
```json
{
  "data": [
    {
      "id": "voice_id_premium_02",
      "name": "vi-VN-female-01",
      "preview_url": "https://app.zorio.vn/api/autocall/voices/preview",
      "gender": "female",
      "language": "vi"
    }
  ]
}
```

**Field response**:

| Field | Type | Mô tả |
|---|---|---|
| `id` | string | Voice ID — dùng làm `voice_id` khi `POST /api/autocall/scripts` |
| `name` | string | Tên hiển thị friendly |
| `preview_url` | string \| null | URL mp3 sample để play thử (preview audio) |
| `gender` | string \| null | `male` / `female` |
| `language` | string \| null | `vi` / `en` / ... |

::: tip Fallback khi provider lỗi
Nếu provider integration tạm thời không phản hồi (network/api key), endpoint vẫn trả về voice đó với chỉ field `id` + `name=id` để client KHÔNG bị lỗi — UI có thể fallback hiển thị ID raw.
:::

::: tip Tier A vs Tier B
- **Tier A** = premium nhà cung cấp TTS cao cấp realtime (charge ký tự).
- **Tier B** = local pre-rendered vi-VN-female-01 (không phí, throughput cao). Khuyến nghị default cho khối lượng lớn.

`tts_tier` cấu hình ở level script (xem [Scripts](/api/autocall/scripts)). Hệ thống tự routing theo `voice_id` -> provider tương ứng.
:::

## Media Files (Mẫu ghi âm)

Module Media Files chuẩn của Zorio — dùng để upload file âm thanh (.wav/.mp3/.m4a/...) và auto-convert sang WAV 16-bit PCM 8kHz mono. Trong AutoCall, dùng `file_path` của media file làm `target_audio_url` cho DTMF action `playback` / `playback_then_hangup`.

**Category enum**:
- `announcement` — thông báo cho DTMF action (vd "Cảm ơn anh/chị", "Đang chuyển nhân viên...")
- `ivr` — prompt IVR (chào, menu...)
- `moh` — music on hold
- `library` — tổng quát

::: warning Permission
Cần `manage_recordings` hoặc `admin` để upload/sửa/xoá; viewer có thể list + lấy audio.
:::

### List media files

```http
GET /api/media-files?category=announcement
```

**Query**:

| Param | Type | Mô tả |
|---|---|---|
| `category` | string, optional | Filter theo enum `ivr` / `moh` / `announcement` / `library`. Bỏ qua -> trả tất cả |

**Response 200**:
```json
{
  "data": [
    {
      "id": 20,
      "tenant_id": 1,
      "name": "VNT v2",
      "file_path": "/media/ivr/studio-1776477792_1776477798_d939.wav",
      "file_size": 176718,
      "duration": 11,
      "format": "wav",
      "category": "ivr",
      "tts_text": null,
      "tts_voice": null,
      "tts_provider": null,
      "created_at": "2026-04-18 02:03:19"
    }
  ]
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data[].id` | integer | ID media file | Số nguyên dương |
| `data[].tenant_id` | integer | ID khách hàng sở hữu | — |
| `data[].name` | string | Tên hiển thị | Tối đa 255 ký tự |
| `data[].file_path` | string | Định danh file (dùng làm `target_audio_url`) cho DTMF action `playback` | Định danh nội bộ |
| `data[].file_size` | integer | Kích thước file (byte) | > 0 |
| `data[].duration` | integer | Thời lượng audio (giây) | >= 0 |
| `data[].format` | string | Định dạng audio (luôn là `wav` sau convert) | `wav` |
| `data[].category` | string | Phân loại file | `ivr` / `moh` / `announcement` / `library` |
| `data[].tts_text` | string \| null | Text gốc (chỉ != null nếu file synthesize qua TTS) | — |
| `data[].tts_voice` | string \| null | Voice ID (chỉ với TTS file) | — |
| `data[].tts_provider` | string \| null | Provider TTS đã dùng | `tts_provider_01` / `local` / null |
| `data[].created_at` | datetime | Thời điểm upload (UTC, format `YYYY-MM-DD HH:mm:ss`) | — |

::: tip Field metadata TTS
`tts_text`, `tts_voice`, `tts_provider` chỉ != null nếu file được synthesize qua TTS (không relevant cho file upload thủ công). Thông tin tham khảo, không bắt buộc xử lý.
:::

### Upload media file

```http
POST /api/media-files
Content-Type: multipart/form-data
```

**Body (multipart)**:

| Field | Required | Type | Mô tả |
|---|---|---|---|
| `file` | Có | binary | File audio (.wav, .mp3, .m4a, .ogg, .aac, .flac). Max 50MB |
| `name` | Có | string | Tên hiển thị (vd "Cảm ơn quý khách") |
| `category` | Không | enum | `ivr` / `moh` / `announcement` / `library`. Default `library` |

**Request mẫu (curl)**:
```bash
curl -X POST https://app.zorio.vn/api/media-files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -F "file=@cam-on.mp3" \
  -F "name=Cảm ơn quý khách" \
  -F "category=announcement"
```

**Response 201**:
```json
{
  "data": {
    "tenant_id": 1,
    "name": "Test",
    "file_path": "/media/library/test_1782374777.wav",
    "file_size": 43704,
    "duration": 3,
    "format": "wav",
    "category": "library",
    "id": 21
  },
  "message": "File đã upload và convert thành công."
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data.id` | integer | ID media file vừa tạo | Số nguyên dương |
| `data.tenant_id` | integer | ID khách hàng sở hữu | — |
| `data.name` | string | Tên hiển thị | — |
| `data.file_path` | string | Định danh file sau convert (WAV 16-bit PCM 8kHz mono) | Định danh nội bộ |
| `data.file_size` | integer | Kích thước file đã convert (byte) | > 0 |
| `data.duration` | integer | Thời lượng audio (giây) | >= 0 |
| `data.format` | string | Định dạng sau convert | Luôn `wav` |
| `data.category` | string | Phân loại file | `ivr` / `moh` / `announcement` / `library` |
| `message` | string | Thông điệp xác nhận thành công | — |

**Error 422** (file sai định dạng / quá lớn):
```json
{
  "message": "The file must be a file of type: wav, mp3, m4a, ogg, aac, flac.",
  "errors": { "file": ["The file must be a file of type: wav, mp3, m4a, ogg, aac, flac."] }
}
```

**Error 500** (server thiếu engine chuyển đổi audio):
```json
{ "error": "engine chuyển đổi audio chưa được cài đặt trên server" }
```

### Cập nhật metadata media file

```http
PATCH /api/media-files/{id}
```

Chỉ đổi `name` / `category` — KHÔNG đụng file vật lý.

**Path params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `id` | integer | Có | ID media file cần cập nhật | Số nguyên dương |

**Body**:
```json
{
  "name": "Cảm ơn — phiên bản 2",
  "category": "announcement"
}
```

**Body fields**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `name` | string | Không | Đổi tên hiển thị | Tối đa 255 ký tự |
| `category` | string | Không | Đổi phân loại | `ivr` / `moh` / `announcement` / `library` |

**Response 200**:
```json
{
  "data": {
    "id": 21,
    "tenant_id": 1,
    "name": "Cảm ơn — phiên bản 2",
    "file_path": "/media/library/test_1782374777.wav",
    "file_size": 43704,
    "duration": 3,
    "format": "wav",
    "category": "announcement",
    "tts_text": null,
    "tts_voice": null,
    "tts_provider": null,
    "created_at": "2026-06-25 08:06:17"
  },
  "message": "Đã cập nhật file âm thanh."
}
```

**Field response**: shape giống `GET /api/media-files` item (xem table ở mục [List media files](#list-media-files)) + thêm `message` ngoài `data`.

### Thay thế file vật lý (giữ ID)

```http
POST /api/media-files/{id}/replace
Content-Type: multipart/form-data
```

Backup file cũ thành `<path>.bak-<timestamp>` rồi ghi đè đúng `file_path` — IVR/DTMF action đang dùng `target_audio_url` không cần update vì path không đổi.

**Path params**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `id` | integer | Có | ID media file cần thay | Số nguyên dương |

**Body (multipart)**:

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `file` | binary | Có | File audio mới | `.wav`, `.mp3`, `.m4a`, `.ogg`, `.aac`, `.flac`, max 50MB |

**Response 200**:
```json
{
  "data": {
    "id": 21,
    "tenant_id": 1,
    "name": "Cảm ơn — phiên bản 2",
    "file_path": "/media/library/test_1782374777.wav",
    "file_size": 43704,
    "duration": 3,
    "format": "wav",
    "category": "announcement",
    "tts_text": null,
    "tts_voice": null,
    "tts_provider": null,
    "created_at": "2026-06-25 08:06:17"
  },
  "backup": "test_1782374777.wav.bak-20260625-080956",
  "message": "Đã thay file thành công. File cũ đã backup."
}
```

**Field response**:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `data` | object | Object media file (shape giống `GET /api/media-files` item) | — |
| `backup` | string | Tên file backup của bản cũ. Path full = `dirname(file_path) + '/' + backup` | `<filename>.bak-<timestamp>` |
| `message` | string | Thông điệp xác nhận | — |

::: tip Field `backup` ở top-level
Không nằm trong `data` — chứa tên file backup. Đường dẫn full = `dirname(file_path) + '/' + backup`.
:::

### Xoá media file

```http
DELETE /api/media-files/{id}
```

Xoá record DB + file vật lý.

**Response 200**:
```json
{ "message": "Đã xóa." }
```

::: warning Audit trước khi xoá
Nếu file đang được DTMF action `target_audio_url` reference, dial sẽ fail với "file not found". Nên audit trước khi xoá.
:::

### Stream audio (play preview)

```http
GET /api/media-files/{id}/audio
```

Trả về binary stream WAV với `Content-Type: audio/wav`. Dùng trong `<audio>` tag HTML5 hoặc curl save:

```bash
curl -s https://app.zorio.vn/api/media-files/5/audio \
  -H "Authorization: Bearer $TOKEN" \
  -o cam-on.wav
```


---

# Webhook events AutoCall

<!-- source: https://docs.zorio.vn/api/autocall/webhooks.md -->

# Webhook events AutoCall

Khi cuộc gọi xảy ra -> Zorio POST event tới URL khách hàng đăng ký (HMAC signed).

## Events

| Event | Khi nào fire |
|---|---|
| `autocall.lead.added` | Lead push vào campaign thành công |
| `autocall.lead.audio_ready` | Audio TTS render xong, lead sẵn sàng dial |
| `autocall.call.initiated` | Engine bắt đầu originate |
| `autocall.call.answered` | B-leg answer máy |
| `autocall.dtmf.pressed` | User bấm phím (1 event/lần bấm) |
| `autocall.call.transferred` | DTMF action = queue -> chuyển queue thành công |
| `autocall.call.completed` | Cuộc gọi kết thúc (mọi result) |
| `autocall.lead.completed` | Lead hoàn tất tất cả retry (final status) |
| `autocall.campaign.completed` | Campaign hết lead pending |
| `autocall.tts.render_failed` | TTS provider lỗi, lead bị skip |

## Envelope chung

Mọi event đều có cấu trúc envelope:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `event` | string | Tên event đầy đủ | `autocall.<entity>.<action>` |
| `timestamp` | datetime | Lúc Zorio publish event (ISO 8601 UTC) | |
| `tenant_id` | integer | ID tài khoản nhận webhook | |
| `data` | object | Payload event-specific (xem từng event bên dưới) | |

## `data` fields theo từng event

### `autocall.lead.added` / `autocall.lead.audio_ready` / `autocall.lead.completed`

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `lead_id` | integer | ID lead trong AutoCall | |
| `campaign_id` | integer | ID campaign chứa lead | |
| `phone` | string | Số điện thoại lead | E.164 hoặc nội địa VN |
| `external_ref` | string\|null | Tham chiếu CRM bên ngoài (nếu khách push kèm) | |
| `audio_url` | string\|null | URL audio TTS (chỉ có khi event = `audio_ready`) | |
| `final_status` | string | Trạng thái cuối (chỉ có khi event = `lead.completed`) | `completed` / `failed` / `dnc` / `max_attempts_reached` |
| `total_attempts` | integer | Số lần đã quay số (chỉ có khi `lead.completed`) | ≥ 1 |

### `autocall.call.initiated`

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi | |
| `campaign_id` | integer | ID campaign | |
| `lead_id` | integer | ID lead | |
| `phone` | string | Số bị quay | |
| `attempt_number` | integer | Lần quay thứ mấy | ≥ 1 |
| `caller_id` | string | Caller-ID dùng để gọi ra | |
| `started_at` | datetime | Thời điểm originate (ISO 8601 UTC) | |

### `autocall.call.answered`

Bao gồm các field như `call.initiated` cộng thêm:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `answered_at` | datetime | Lúc B-leg nhấc máy (ISO 8601 UTC) | |

### `autocall.dtmf.pressed`

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi | |
| `campaign_id` | integer | ID campaign | |
| `lead_id` | integer | ID lead | |
| `phone` | string | Số đang gọi | |
| `digit` | string | Phím vừa bấm | `0`-`9`, `*`, `#` |
| `pressed_at` | datetime | Lúc nhận DTMF (ISO 8601 UTC) | |

### `autocall.call.transferred`

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi | |
| `campaign_id` | integer | ID campaign | |
| `lead_id` | integer | ID lead | |
| `transfer_target` | string | Đích chuyển tiếp | `queue:<queue_name>` / `extension:<ext>` |
| `transferred_at` | datetime | Lúc chuyển queue thành công (ISO 8601 UTC) | |

### `autocall.call.completed`

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi | |
| `campaign_id` | integer | ID campaign | |
| `lead_id` | integer | ID lead | |
| `phone` | string | Số đã gọi | |
| `attempt_number` | integer | Lần quay thứ mấy | ≥ 1 |
| `started_at` | datetime | Lúc originate (ISO 8601 UTC) | |
| `answered_at` | datetime\|null | Lúc bắt máy (null nếu không nhấc) | |
| `ended_at` | datetime | Lúc cúp máy (ISO 8601 UTC) | |
| `duration_sec` | integer | Tổng thời lượng cuộc gọi (giây) | ≥ 0 |
| `result` | string | Kết quả phân loại | `connected` / `no_answer` / `busy` / `failed` / `voicemail` / `dnc_blocked` |
| `hangup_cause` | string | Mã hangup chuẩn Q.850 từ Zorio PBX | `NORMAL_CLEARING` / `NO_ANSWER` / `USER_BUSY` / `CALL_REJECTED` / ... |
| `dtmf_pressed` | string\|null | Phím cuối user bấm | |
| `final_action` | string\|null | Hành động cuối (theo DTMF script) | `queue:<name>` / `hangup` / `dnc_added` / null |

### `autocall.campaign.completed`

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `campaign_id` | integer | ID campaign vừa hoàn tất | |
| `campaign_name` | string | Tên campaign | |
| `total_leads` | integer | Tổng số lead trong campaign | ≥ 0 |
| `total_connected` | integer | Số lead bắt máy thành công | ≥ 0 |
| `completed_at` | datetime | Lúc campaign hoàn tất (ISO 8601 UTC) | |

### `autocall.tts.render_failed`

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `lead_id` | integer | ID lead bị skip | |
| `campaign_id` | integer | ID campaign | |
| `provider` | string | Nhà cung cấp TTS gặp lỗi | `tts_provider_01` / `tts_provider_02` / `tts_provider_03` / `local` |
| `error_code` | string | Mã lỗi | `RATE_LIMIT` / `INVALID_VOICE` / `QUOTA_EXCEEDED` / `UNKNOWN` |
| `error_message` | string | Mô tả lỗi | |
| `failed_at` | datetime | Lúc TTS lỗi (ISO 8601 UTC) | |

## Cấu hình Webhook (qua Admin Console, KHÔNG qua Public API)

::: warning Webhook KHÔNG đăng ký qua API
Theo policy bảo mật của Zorio, cấu hình webhook chỉ thực hiện thủ công qua **Admin Console** (`Admin Console`). Public API chỉ phục vụ nghiệp vụ AutoCall (campaign / lead / call lifecycle / reports).
:::

**Lý do**:
- Tránh lạm dụng: nếu cho client tự đăng ký, hacker có thể dùng token để redirect webhook ra URL ngoài tài khoản.
- Đảm bảo audit: mỗi thay đổi webhook config được log ở admin activity.
- Tách bạch nghiệp vụ vs config: public API focused vào dữ liệu cuộc gọi.

**Quy trình bạn tích hợp**:

1. **Liên hệ quản trị hệ thống** (trong tổ chức) hoặc đội ngũ Zorio support.
2. Cung cấp:
   - URL endpoint nhận webhook (HTTPS)
   - Danh sách events cần subscribe (xem mục [Events](#events))
   - Tùy chọn: IP allowlist của hạ tầng bạn
3. Quản trị hệ thống cấu hình trong Admin Console + chọn events -> **lưu**.
4. Hệ thống generate **secret** (32 bytes base64) -> gửi cho bạn qua kênh bảo mật.
5. Anh chị deploy webhook receiver + dùng secret để verify HMAC signature (xem [Headers](#headers)).

**Thay đổi config** (đổi URL, thêm events, rotate secret) — cũng qua Admin Console, không qua API.

## Delivery payload mẫu (event `autocall.call.completed`)

```json
{
  "event": "autocall.call.completed",
  "timestamp": "2026-06-24T08:32:47Z",
  "tenant_id": 1,
  "data": {
    "uuid": "093e1024-...",
    "campaign_id": 36,
    "lead_id": 78912,
    "phone": "84912345678",
    "attempt_number": 1,
    "started_at": "2026-06-24T08:32:00Z",
    "answered_at": "2026-06-24T08:32:05Z",
    "ended_at": "2026-06-24T08:32:47Z",
    "duration_sec": 42,
    "result": "connected",
    "hangup_cause": "NORMAL_CLEARING",
    "dtmf_pressed": "2",
    "final_action": "queue:support_queue"
  }
}
```

## Headers POST từ Zorio tới URL khách

| Header | Type | Mô tả | Giá trị |
|---|---|---|---|
| `X-Zorio-Signature` | string | HMAC-SHA256 raw body với webhook secret | `sha256=<hex>` |
| `X-Zorio-Timestamp` | integer | Epoch giây (UTC) — client reject nếu lệch > 300s | |
| `X-Zorio-Event` | string | Convenience copy của `event` field | `autocall.<entity>.<action>` |
| `X-Zorio-Delivery` | string | Delivery UUID — dùng dedupe khi retry | UUID v4 |
| `Content-Type` | string | Loại nội dung | `application/json; charset=utf-8` |

::: tip Verify HMAC
Pseudo-code:
```
expected = "sha256=" + hex(hmac_sha256(secret, raw_request_body))
if expected != header["X-Zorio-Signature"]: reject
```
KHÔNG verify trên JSON đã parse — phải dùng **raw body bytes**.
:::

## Retry policy

- 3 lần retry: 5s, 30s, 5 phút
- Sau 3 lần fail -> deadletter (admin xem qua Admin Console)
- HTTP 2xx = success. 4xx/5xx = fail.

::: warning Idempotency client-side
Client phải đảm bảo endpoint idempotent (check `X-Zorio-Delivery` UUID) vì webhook có thể được gửi lại nếu HTTP timeout phía Zorio nhưng response đã thực thi xong phía client.
:::


---

# Lịch sử cuộc gọi (CDR)

<!-- source: https://docs.zorio.vn/api/pbx/cdr.md -->

# Lịch sử cuộc gọi (CDR)

Truy vấn CDR theo nhiều điều kiện + tải ghi âm signed URL.

## GET `/api/pbx/cdr` — Liệt kê

### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `from` | date | optional | Ngày bắt đầu (YYYY-MM-DD) | Không truyền → `now() - 30 ngày` |
| `to` | date | optional | Ngày kết thúc (YYYY-MM-DD) | Phải ≥ `from`. Không truyền → `now()` |
| `direction` | string | optional | Hướng cuộc gọi | `inbound`, `outbound`, `internal`, `local` |
| `extension` | string | optional | Lọc theo máy nhánh (match `extension_number` hoặc `agent_extension`) | 3-20 ký tự |
| `phone` | string | optional | Lọc theo số điện thoại (match `caller_number` hoặc `destination_number`) | max 50 ký tự |
| `page` | integer | optional | Số trang | ≥ 1 |
| `per_page` | integer | optional | Số bản ghi/trang | 1-200 (default 50) |

::: warning Giới hạn cửa sổ thời gian
Cửa sổ `from..to` tối đa **30 ngày** (configurable per tài khoản qua `giới hạn cấu hình theo từng khách hàng`). Vượt → HTTP 422.
:::

### Response body fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi (Zorio PBX `call_uuid`) | UUID 36 ký tự |
| `direction` | string | Hướng cuộc gọi | `inbound` / `outbound` / `internal` / `local` |
| `source_type` | string | Nguồn cuộc gọi | `inbound` / `outbound_manual` / `outbound_telesales` / `outbound_callback` / `outbound_webphone` / `internal` |
| `caller_number` | string | Số gọi đi (caller ID) | |
| `destination_number` | string | Số đích | |
| `extension_number` | string\|null | Máy nhánh liên quan (caller hoặc destination) | |
| `agent_extension` | string\|null | Máy nhánh agent đã trả lời (cho queue/IVR) | |
| `start_time` | datetime | Lúc cuộc gọi bắt đầu | ISO 8601 |
| `answer_time` | datetime\|null | Lúc nhấc máy | ISO 8601 (null nếu không nhấc) |
| `end_time` | datetime | Lúc cúp máy | ISO 8601 |
| `duration` | integer | Tổng thời lượng (giây) | ≥ 0 |
| `billsec` | integer | Thời gian tính tiền (sau khi nhấc, giây) | ≥ 0 |
| `queue_name` | string\|null | Tên queue (nếu cuộc đi qua hàng đợi) | |
| `queue_wait_time` | integer\|null | Thời gian chờ trong queue (giây) | |
| `trunk_name` | string\|null | Tên trunk gọi ra (cho outbound) | |
| `transfer_count` | integer | Số lần chuyển máy | ≥ 0 |
| `result` | string | Kết quả cuộc gọi | `answered` / `busy` / `no_answer` / `failed` / `cancelled` / `rejected` / `voicemail` |
| `hangup_cause` | string | Mã hangup từ Zorio PBX | vd `NORMAL_CLEARING`, `NO_ANSWER`, `USER_BUSY`, `CALL_REJECTED`, ... |
| `sip_response_code` | string\|null | Mã SIP cuối (cho outbound) | vd `200`, `486`, `487` |
| `recording_available` | bool | Có file ghi âm không | `true` / `false` |
| `created_at` | datetime | Ngày tạo row CDR | |

### Response Body (JSON) — 200

```json
{
  "current_page": 1,
  "data": [
    {
      "uuid": "65569ce0-0183-4f61-a3b2-0e433cfa4031",
      "direction": "outbound",
      "source_type": "outbound_telesales",
      "caller_number": "0900000021",
      "destination_number": "0987654321",
      "extension_number": "0900000021",
      "agent_extension": null,
      "start_time": "2026-06-27T08:15:42+00:00",
      "answer_time": "2026-06-27T08:15:42+00:00",
      "end_time": "2026-06-27T08:15:56+00:00",
      "duration": 14,
      "billsec": 14,
      "queue_name": null,
      "queue_wait_time": null,
      "trunk_name": null,
      "transfer_count": 0,
      "result": "answered",
      "hangup_cause": "NORMAL_CLEARING",
      "sip_response_code": null,
      "recording_available": true,
      "created_at": "2026-06-27 08:15:56"
    }
  ],
  "last_page": 5,
  "per_page": 20,
  "total": 87
}
```

## GET `/api/pbx/cdr/{uuid}` — Chi tiết + signed recording URL

### Path parameter

`uuid` (string, Zorio PBX `call_uuid`).

Response = 22 field như list + 1 object `recording` (nếu có ghi âm).

### `recording` object fields

| Field | Type | Mô tả |
|---|---|---|
| `duration` | integer | Thời lượng file ghi âm (giây) |
| `file_size` | integer | Kích thước file (byte) |
| `recorded_at` | datetime | Lúc ghi âm bắt đầu (ISO 8601) |
| `url` | string | URL signed HMAC tải file `.wav` — chỉ valid trong `expires_in_seconds` |
| `expires_in_seconds` | integer | TTL của URL (default 1800 = 30 phút) |

### Response Body (JSON) — 200

```json
{
  "data": {
    "uuid": "65569ce0-...",
    "direction": "outbound",
    "recording_available": true,
    "recording": {
      "duration": 14,
      "file_size": 56265,
      "recorded_at": "2026-06-27T08:15:57+00:00",
      "url": "https://app.zorio.vn/api/public/recordings/401/audio?expires=1782706011&signature=de93e86...",
      "expires_in_seconds": 1800
    }
  }
}
```

## GET `/api/pbx/cdr/{uuid}/recording` — 302 redirect tới signed URL

### Path parameter

`uuid` (CDR `Unique-ID`).

### Response

HTTP 302 với header `Location: <signed URL>`. Client follow redirect để tải file `.wav`. TTL signed URL: **30 phút** (HMAC SHA256).


---

# Click-to-Call

<!-- source: https://docs.zorio.vn/api/pbx/click-to-call.md -->

# Click-to-Call

Khởi tạo cuộc gọi 2-leg từ API: A-leg dial agent extension → khi nhấc → B-leg dial số khách → bridge.

## POST `/api/pbx/calls/click-to-call`

### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `from_extension` | string | ✅ | Máy nhánh agent (A-leg) | Phải tồn tại + `status=active`. Regex `^[0-9]{3,10}$` |
| `to_phone` | string | ✅ | Số đích cần gọi (B-leg) | Regex `^[0-9+]+$`, 3-32 ký tự |
| `caller_id` | string | optional | Số hiển thị khi gọi ra | Fallback `extension.outbound_caller_id` hoặc `from_extension`. Tốt nhất chọn từ `/api/pbx/caller-ids` |
| `trunk_id` | integer | optional | ID trunk gọi ra (ưu tiên cao hơn `trunk_name`) | Phải tồn tại + status=active. KHÔNG truyền → fallback dialplan default (dialplan default Zorio PBX tự pick trunk theo LCR/number-pool) |
| `trunk_name` | string | optional | Tên trunk thay thế `trunk_id` | max 100 ký tự |
| `headers` | object | optional | Custom SIP headers — Zorio sẽ prefix `X-` và gắn vào INVITE B-leg | Key regex `[A-Za-z0-9_-]`, value max 200 ký tự |

### Request Body (JSON) — Mode 1: auto routing (không truyền trunk)

```json
{
  "from_extension": "1001",
  "to_phone": "0987654321"
}
```

### Request Body (JSON) — Mode 2: force trunk + caller-id + CRM tracking header

```json
{
  "from_extension": "1001",
  "to_phone": "0987654321",
  "caller_id": "0900000020",
  "trunk_id": 4,
  "headers": { "CRM-Lead-Id": "LEAD-42" }
}
```

### Response body fields — 202 (Accepted, cuộc gọi đã enqueue)

| Field | Type | Mô tả |
|---|---|---|
| `call_uuid` | string | UUID logic của cuộc gọi (CRM dùng để track xuyên suốt webhook events) |
| `a_leg_uuid` | string | UUID A-leg (kênh tới agent ext) |
| `b_leg_uuid` | string | UUID B-leg (kênh tới số khách) |
| `from_extension` | string | Echo từ request |
| `to_phone` | string | Echo từ request |
| `caller_id` | string | Số hiển thị thực tế đã resolve |
| `trunk_id` | integer\|null | ID trunk đã chọn (null nếu dùng dialplan default) |
| `trunk_name` | string\|null | Tên trunk đã chọn (null nếu dùng dialplan default) |
| `routing_mode` | string | `direct_gateway` (có trunk được chọn) hoặc `dialplan_default` (dùng dialplan routing) |
| `status` | string | `queued` (chưa kết nối). Sau đó CRM theo dõi qua webhook `pbx.call.ringing` / `pbx.call.answered` / `pbx.call.hangup` |

### Response Body (JSON) — 202

```json
{
  "data": {
    "call_uuid": "1ac30fff-0968-452f-9a9f-56c21fc8fe3f",
    "a_leg_uuid": "fc22be63-271d-4842-859d-0ebba9f13c8a",
    "b_leg_uuid": "64486cf6-0577-46a4-81e9-23ca31f46249",
    "from_extension": "1001",
    "to_phone": "0987654321",
    "caller_id": "1001",
    "trunk_id": 4,
    "trunk_name": "POC",
    "routing_mode": "direct_gateway",
    "status": "queued"
  }
}
```

::: warning Rate limit
**10 req / phút / token** (riêng group này — chống abuse spam call).
:::

## Pattern hoạt động

A-leg dial agent ext → khi nhấc → B-leg dial số khách → bridge. CRM khách nhận event `pbx.call.answered` cho A-leg trước, sau đó `pbx.call.answered` cho B-leg.

```
1. Client gọi   POST /api/pbx/calls/click-to-call → 202 với call_uuid
2. Zorio        Webhook pbx.call.ringing → A-leg ext đổ chuông
3. Agent nhấc   Webhook pbx.call.answered (A-leg)
4. Zorio        Bridge dial B-leg ra số khách
5. Khách nhấc   Webhook pbx.call.answered (B-leg)
6. Cuộc gọi diễn ra
7. Cúp máy      Webhook pbx.call.hangup + pbx.cdr.created
```


---

# Máy nhánh (Extensions)

<!-- source: https://docs.zorio.vn/api/pbx/extensions.md -->

# Máy nhánh (Extensions)

Quản lý máy nhánh SIP của tổng đài: liệt kê, tạo mới, sửa, xoá, lấy số khả dụng, xoay mật khẩu.

## GET `/api/pbx/extensions` — Liệt kê

### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `search` | string | optional | Tìm theo `extension_number` hoặc `display_name` (LIKE) | |
| `status` | string | optional | Lọc theo trạng thái config | `active`, `disabled` |
| `page` | integer | optional | Số trang | ≥ 1 (default 1) |
| `per_page` | integer | optional | Số bản ghi/trang | 1-200 (default 50) |

### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị |
|---|---|---|---|
| `extension_number` | string | Số máy nhánh — SIP register name | 3-10 chữ số |
| `display_name` | string\|null | Tên hiển thị (caller ID name khi gọi nội bộ) | max 100 ký tự |
| `voicemail_enabled` | bool | Có bật voicemail không | `true` / `false` |
| `outbound_caller_id` | string\|null | Số gọi ra mặc định | Phải tồn tại trong `/caller-ids` |
| `recording_mode` | string | Chế độ ghi âm | `none`, `inbound`, `outbound`, `all` |
| `status` | string | Trạng thái cấu hình admin | `active`, `disabled` |
| `team_id` | integer\|null | ID nhóm | |
| `department_id` | integer\|null | ID phòng ban | |
| `max_concurrent` | integer | Số cuộc gọi đồng thời tối đa | 1-10 |
| `tls_enabled` | bool | Có bật SIPS/TLS không | `true` / `false` |
| `created_at` | datetime | Ngày tạo (ISO 8601 + offset) | |
| `updated_at` | datetime | Ngày cập nhật cuối | |

### Response Body (JSON) — 200

```json
{
  "current_page": 1,
  "data": [
    {
      "extension_number": "1001",
      "display_name": "Mac I5",
      "voicemail_enabled": true,
      "outbound_caller_id": null,
      "recording_mode": "all",
      "status": "active",
      "team_id": 2,
      "department_id": null,
      "max_concurrent": 2,
      "tls_enabled": false,
      "created_at": "2026-04-06T12:19:13+00:00",
      "updated_at": "2026-06-18T11:01:47+00:00"
    }
  ],
  "last_page": 2,
  "per_page": 10,
  "total": 17
}
```

## GET `/api/pbx/extensions/{ext}` — Chi tiết

### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `ext` | string | `extension_number` (KHÔNG phải `id`) |

Response = 12 field như list + 1 field extra `sip_registration` realtime.

### Response Body (JSON) — 200

```json
{
  "data": {
    "extension_number": "1001",
    "display_name": "Mac I5",
    "voicemail_enabled": true,
    "outbound_caller_id": null,
    "recording_mode": "all",
    "status": "active",
    "team_id": 2,
    "department_id": null,
    "max_concurrent": 2,
    "tls_enabled": false,
    "created_at": "2026-04-06T12:19:13+00:00",
    "updated_at": "2026-06-18T11:01:47+00:00",
    "sip_registration": "registered"
  }
}
```

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `status` | string | Cấu hình admin | `active`, `disabled` |
| `sip_registration` | string | Trạng thái SIP register realtime — CRM dùng để biết softphone online hay không | `registered`, `unregistered`, `unknown` |

## POST `/api/pbx/extensions` — Tạo mới

### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `extension_number` | string | ✅ | Số máy nhánh — unique per tài khoản | Regex `^[0-9]{3,10}$` (3-10 chữ số) |
| `display_name` | string | optional | Tên hiển thị | max 100 ký tự |
| `team_id` | integer | optional | ID nhóm | Phải tồn tại trong `teams` |
| `sip_password` | string | optional | Mật khẩu SIP register — KHÔNG truyền → tự sinh 24 ký tự alphanumeric | min 8, max 100 ký tự |
| `voicemail_enabled` | bool | optional | Bật voicemail | `true` / `false` (default `false`) |
| `voicemail_pin` | string | optional | PIN truy cập voicemail | max 20 ký tự |
| `recording_mode` | string | optional | Chế độ ghi âm | `none` / `inbound` / `outbound` / `all` (default `none`) |
| `max_concurrent` | integer | optional | Cuộc gọi đồng thời tối đa | 1-10 (default 2) |
| `outbound_caller_id` | string | optional | Số gọi ra mặc định | Phải tồn tại trong `/api/pbx/caller-ids` (active) |

### Request Body (JSON)

```json
{
  "extension_number": "9001",
  "display_name": "Sales 01",
  "voicemail_enabled": true,
  "recording_mode": "all",
  "max_concurrent": 2,
  "outbound_caller_id": "0900000020"
}
```

### Response body fields (12 field như list + 2 field bổ sung khi tạo)

| Field | Type | Mô tả |
|---|---|---|
| `sip_password` | string | Mật khẩu SIP — **chỉ trả 1 lần**, copy vào softphone ngay |
| `generated_password` | bool | `true` nếu Zorio tự sinh, `false` nếu client truyền |

### Response Body (JSON) — 201

```json
{
  "data": {
    "extension_number": "9001",
    "display_name": "Sales 01",
    "voicemail_enabled": true,
    "recording_mode": "all",
    "status": "active",
    "max_concurrent": 2,
    "outbound_caller_id": "0900000020",
    "team_id": null,
    "department_id": null,
    "tls_enabled": false,
    "created_at": "2026-06-29T04:53:59+00:00",
    "updated_at": "2026-06-29T04:53:59+00:00",
    "sip_password": "<sip_password_chỉ_hiển_thị_1_lần>",
    "generated_password": true
  }
}
```

## PUT `/api/pbx/extensions/{ext}` — Cập nhật

### Request body fields (mọi field optional — chỉ truyền field cần đổi)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `display_name` | string\|null | Tên hiển thị | max 100 ký tự |
| `team_id` | integer\|null | ID nhóm | |
| `voicemail_enabled` | bool | Bật voicemail | `true` / `false` |
| `voicemail_pin` | string\|null | PIN voicemail | max 20 |
| `recording_mode` | string | Chế độ ghi âm | `none` / `inbound` / `outbound` / `all` |
| `max_concurrent` | integer | Cuộc đồng thời tối đa | 1-10 |
| `outbound_caller_id` | string\|null | Số gọi ra | Phải có trong `/api/pbx/caller-ids` (active) |
| `status` | string | Trạng thái cấu hình | `active` / `disabled` |

::: tip Lưu ý
`extension_number` và `sip_password` KHÔNG đổi qua PUT. Đổi `sip_password` → dùng endpoint `/change-password`.
:::

### Request Body (JSON)

```json
{
  "display_name": "Sales 01 (renamed)",
  "voicemail_enabled": false,
  "max_concurrent": 4,
  "recording_mode": "all",
  "outbound_caller_id": "0900000020"
}
```

### Response Body (JSON) — 200

```json
{
  "data": {
    "extension_number": "1001",
    "display_name": "Sales 01 (renamed)",
    "voicemail_enabled": false,
    "outbound_caller_id": "0900000020",
    "recording_mode": "all",
    "status": "active",
    "team_id": null,
    "department_id": null,
    "max_concurrent": 4,
    "tls_enabled": false,
    "created_at": "2026-04-06T12:19:13+00:00",
    "updated_at": "2026-06-29T07:55:12+00:00"
  }
}
```

## DELETE `/api/pbx/extensions/{ext}` — Xoá

Không có Request Body.

### Response Body (JSON) — 200

```json
{
  "data": { "deleted": true }
}
```

Soft delete + flush FS directory cache.

## GET `/api/pbx/caller-ids` — Liệt kê số khả dụng

Trả các outbound caller ID `status=active` của khách hàng — dùng khi pick `outbound_caller_id` cho ext hoặc `caller_id` cho click-to-call.

### Query parameters

| Field | Type | Mô tả | Giá trị |
|---|---|---|---|
| `search` | string | Match `number` hoặc `display_name` | |
| `page` | integer | Số trang | ≥ 1 |
| `per_page` | integer | Số bản ghi/trang | 1-200 (default 50) |

### Response body fields

| Field | Type | Mô tả | Giá trị |
|---|---|---|---|
| `number` | string | Số gọi ra (E.164 hoặc nội địa VN) | 8-15 chữ số |
| `display_name` | string\|null | Tên hiển thị nội bộ | |
| `carrier` | string | Nhà mạng | `viettel` / `mobifone` / `vinaphone` / `vietnamobile` / `landline` / `other` |
| `cli_type` | string | Loại số | `mobile` / `fixed_02x` / `hotline_1900` / `hotline_1800` / `brandname` |
| `status` | string | Trạng thái | `active` (luôn vì query lọc) |

### Response Body (JSON) — 200

```json
{
  "current_page": 1,
  "data": [
    { "number": "0900000020", "display_name": "POC", "carrier": "landline", "cli_type": "mobile", "status": "active" },
    { "number": "0900000021", "display_name": "POC", "carrier": "landline", "cli_type": "mobile", "status": "active" }
  ],
  "last_page": 1, "per_page": 50, "total": 7
}
```

Khi POST/PUT extension với `outbound_caller_id` không có trong list → **HTTP 422**:

```json
{ "errors": { "outbound_caller_id": ["Giá trị đã chọn cho outbound caller id không hợp lệ."] } }
```

## POST `/api/pbx/extensions/{ext}/change-password` — Xoay mật khẩu SIP

### Request body fields

| Field | Type | Required | Mô tả | Giá trị |
|---|---|---|---|---|
| `new_password` | string | optional | Mật khẩu SIP mới — không truyền → tự sinh 24 ký tự alphanumeric | min 8, max 100 |

### Request Body (JSON) — tự sinh password (body rỗng)

```json
{}
```

### Request Body (JSON) — đặt password thủ công

```json
{
  "new_password": "MyNewStrongPwd123"
}
```

### Response body fields

| Field | Type | Mô tả |
|---|---|---|
| `extension_number` | string | Số máy nhánh đã đổi |
| `sip_password` | string | Mật khẩu mới — chỉ trả 1 lần |
| `generated_password` | bool | `true` nếu Zorio tự sinh, `false` nếu client truyền |

### Response Body (JSON) — 200

```json
{
  "data": {
    "extension_number": "1001",
    "sip_password": "AbC123...",
    "generated_password": true
  }
}
```


---

# PBX API — Tổng quan

<!-- source: https://docs.zorio.vn/api/pbx/index.md -->

# PBX API — Tổng quan

> Public REST API cho Module PBX (Extensions / CDR / Click-to-Call / Queue / Webhooks).
> **Xác thực**: Bearer Token (phiên user). **Base URL**: cấp riêng theo khách hàng — xem mục [Base URL](#base-url).

## Phạm vi

PBX API cho phép CRM khách hàng:

- Quản lý máy nhánh (Extensions): CRUD + đổi mật khẩu SIP.
- Truy vấn lịch sử cuộc gọi (CDR) + tải ghi âm.
- Khởi tạo Click-to-Call 2-leg (agent → khách).
- Quản lý hàng đợi (Queue) + tier agent.
- Đăng ký webhook nhận sự kiện realtime (`pbx.call.ringing` / `answered` / `hangup` / `cdr.created`).

## Glossary

| Thuật ngữ | Giải thích |
|---|---|
| Extension | Máy nhánh SIP — đăng ký lên Zorio PBX bằng `extension_number` + `sip_password` |
| Tài khoản | Mỗi khách hàng có dữ liệu hoàn toàn độc lập |
| CDR | Call Detail Record — bản ghi 1 cuộc gọi (in/out/internal/local) |
| Click-to-Call | Originate cuộc gọi 2-leg từ API: A-leg dial ext agent, B-leg dial số khách |
| Queue | Hàng đợi — agents (Tier) trả lời theo strategy (round-robin, longest-idle, ...) |
| Tier | Cấp ưu tiên trong queue (`tier_level` 1-9), `tier_position` xếp thứ tự trong cùng level |
| Webhook | URL HTTPS Zorio POST event tới CRM khách (`pbx.call.ringing` / `pbx.call.answered` / `pbx.call.hangup` / `pbx.cdr.created`) |
| HMAC | Header `X-Zorio-Signature: sha256=hex(hmac_sha256(secret, body))` để xác thực |
| Idempotency | Header `X-Zorio-Delivery: <UUID>` — client dedupe khi retry |

## End-to-end workflow

```
1. Login                  POST /api/auth/login       → Bearer token
2. Tạo extension          POST /api/pbx/extensions   → trả sip_password 1 lần
3. Đăng ký webhook        UI Admin Admin Console (KHÔNG API)
4. Click-to-call          POST /api/pbx/calls/click-to-call → 202 call_uuid
5. Nhận event             Zorio POST → URL khách: pbx.call.ringing → pbx.call.answered → pbx.call.hangup
6. Query CDR              GET  /api/pbx/cdr?from=&to=&extension=
7. Tải ghi âm             GET  /api/pbx/cdr/{uuid}/recording → 302 signed URL TTL 30 phút
```

## Xác thực

### Login

**Endpoint**: `POST /api/auth/login`

**Request Body** (JSON)

```json
{
  "username": "admin",
  "password": "<password>"
}
```

**Response Body** (JSON) — 200

```json
{
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "role": "admin",
      "tenant_id": 1
    }
  },
  "token": "1|abcdefghijklmnopqrstuvwxyz0123456789"
}
```

### Mọi request dùng header

```
Authorization: Bearer <token>
Accept: application/json
```

### Permission yêu cầu

User phải có permission `pbx_api_access` (admin role có sẵn).

## Các nhóm endpoint

| Nhóm | Tài liệu | Mô tả |
|---|---|---|
| Máy nhánh (Extensions) | [Tới trang](/api/pbx/extensions) | CRUD + đổi mật khẩu SIP + lấy danh sách số khả dụng |
| Lịch sử cuộc gọi (CDR) | [Tới trang](/api/pbx/cdr) | Query CDR theo điều kiện + tải ghi âm signed URL |
| Click-to-Call | [Tới trang](/api/pbx/click-to-call) | Khởi tạo cuộc gọi 2-leg từ API |
| Hàng đợi (Queue) | [Tới trang](/api/pbx/queue) | CRUD queue + quản lý tier agent |
| Webhook events PBX | [Tới trang](/api/pbx/webhooks) | Payload schema + HMAC verify + retry policy |

## Pagination & Response shape

### Pagination

Mọi list endpoint dùng query `?page=1&per_page=50` (max 200). Response:

```json
{
  "current_page": 1,
  "data": [],
  "last_page": 5,
  "per_page": 50,
  "total": 234
}
```

### Single resource / action

```json
{ "data": {} }
```

### Error

```json
{
  "message": "Mô tả lỗi tóm tắt",
  "errors": { "field_name": ["Mô tả chi tiết"] }
}
```

### Timezone

Mọi datetime trả ở ISO 8601 với offset (`+00:00` = UTC).

## Rate Limit

| Endpoint group | Limit |
|---|---|
| `/api/pbx/calls/click-to-call` | 10 req/min/token |
| `/api/pbx/*` (mọi endpoint khác) | 60 req/min/token |

Vượt quá → HTTP 429 với header `Retry-After: <giây>`.

## HTTP Status Codes

| HTTP | Khi nào |
|---|---|
| 200 | OK |
| 201 | Created (resource mới) |
| 202 | Accepted (click-to-call enqueued) |
| 401 | Token thiếu / sai / expired — re-login |
| 403 | Token hợp lệ nhưng thiếu permission `pbx_api_access` |
| 404 | Resource không tồn tại trong dữ liệu của token |
| 409 | Conflict (vd extension đã ở trong queue) |
| 422 | Validation lỗi (`errors` chi tiết field) hoặc enforce business rule |
| 429 | Rate limit hit |
| 500 | Server error (báo team Zorio) |
| 502 | Click-to-call: Zorio PBX không tiếp nhận originate |

## Base URL

| | URL |
|---|---|
| Production | `https://app.zorio.vn/api/pbx/` (cấp riêng theo khách hàng) |

## FAQ

**Q1: Webhook URL bị block tạm thời (vd CDN), Zorio retry tối đa bao lâu?**

A: 4 lần, tổng ~36 phút. Sau đó vào deadletter — client cần đăng ký webhook lại sau khi fix.

**Q2: Click-to-call thất bại — phân biệt agent không nhấc vs khách không nhận?**

A: Sau khi `pbx.call.hangup` fire, check `hangup_cause`:
- `NORMAL_CLEARING` + `billsec > 0`: cả 2 bên nhấc, gọi thành công
- `NO_ANSWER`: 1 trong 2 bên không nhấc
- `USER_BUSY`: số đích busy

**Q3: Tôi muốn nhận event cho ext cụ thể, không phải toàn bộ tài khoản?**

A: Hiện tại đăng ký subscription áp dụng cho toàn khách hàng. Filter theo extension chưa hỗ trợ.

**Q4: Tôi cần tài khoản test trước khi tích hợp production?**

A: Liên hệ Zorio để cấp khách hàng test riêng.


---

# Hàng đợi (Queue)

<!-- source: https://docs.zorio.vn/api/pbx/queue.md -->

# Hàng đợi (Queue)

Quản lý hàng đợi của Zorio PBX: CRUD queue, thêm/sửa/xoá tier agent.

## GET `/api/pbx/queues` — Liệt kê

**Query**: `search` (match `name` hoặc `queue_number`), `page`, `per_page` (1-200).

Response format giống Extensions (5 keys: `current_page`, `data`, `last_page`, `per_page`, `total`).

## GET `/api/pbx/queues/{name}` — Chi tiết

### Path parameter

`name` (string user-facing, KHÔNG phải `id`).

### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `name` | string | Tên queue user-facing | unique per tài khoản |
| `queue_number` | string | Số extension nội bộ để dial vào queue | 3-10 chữ số |
| `team_id` | integer\|null | Nhóm sở hữu | |
| `strategy` | string | Cách chọn agent | `ring-all` / `longest-idle-agent` / `round-robin` / `top-down` / `agent-with-least-talk-time` / `agent-with-fewest-calls` / `sequentially-by-agent-order` / `random` |
| `tier_rules_apply` | bool | Áp dụng tier rule không | |
| `tier_rule_wait_second` | integer | Số giây chờ trước khi escalate lên tier kế tiếp | 0-3600 |
| `tier_rule_wait_multiply_level` | bool | Nhân số giây theo tier level | |
| `tier_rule_no_agent_no_wait` | bool | Không chờ nếu tier không có agent online | |
| `abandoned_resume_allowed` | bool | Cho phép caller gọi lại sau khi cúp | |
| `discard_abandoned_after` | integer | Sau bao nhiêu giây mới xoá record abandoned | |
| `max_wait_time_with_no_agent` | integer | Tối đa chờ khi không có agent (giây) | ≥ 0 |
| `max_wait_time_with_no_agent_time_reached` | string | Hành động khi hết thời gian chờ | `hangup` / hoặc tên action khác |
| `time_base_score` | string | Tính điểm theo `system` (toàn hệ) hay `queue` (chỉ trong queue) | `system` / `queue` |
| `recording_template` | string\|null | Template tên file ghi âm (Zorio PBX variable interpolation) | |
| `status` | string | Trạng thái | `active` / `inactive` |
| `created_at` | datetime | | |
| `updated_at` | datetime | | |

### Response Body (JSON) — 200

```json
{
  "data": {
    "name": "Support01",
    "queue_number": "200",
    "team_id": 2,
    "strategy": "agent-with-fewest-calls",
    "tier_rules_apply": true,
    "tier_rule_wait_second": 15,
    "tier_rule_wait_multiply_level": true,
    "tier_rule_no_agent_no_wait": true,
    "abandoned_resume_allowed": false,
    "discard_abandoned_after": 14400,
    "max_wait_time_with_no_agent": 60,
    "max_wait_time_with_no_agent_time_reached": "hangup",
    "time_base_score": "queue",
    "recording_template": null,
    "status": "active"
  }
}
```

## POST `/api/pbx/queues` — Tạo mới

### Request body fields

| Field | Type | Required | Mô tả | Giá trị |
|---|---|---|---|---|
| `name` | string | ✅ | Tên queue | max 100, unique per tài khoản |
| `queue_number` | string | ✅ | Số dial vào queue | Regex `^[0-9]{3,10}$`, unique per tài khoản |
| `team_id` | integer | optional | Nhóm sở hữu | |
| `strategy` | string | optional | Cách chọn agent | 8 giá trị enum (xem Chi tiết) |
| `tier_rules_apply` | bool | optional | | |
| `tier_rule_wait_second` | integer | optional | | 0-3600 |
| `tier_rule_wait_multiply_level` | bool | optional | | |
| `tier_rule_no_agent_no_wait` | bool | optional | | |
| `abandoned_resume_allowed` | bool | optional | | |
| `discard_abandoned_after` | integer | optional | | ≥ 0 |
| `max_wait_time_with_no_agent` | integer | optional | | ≥ 0 |
| `max_wait_time_with_no_agent_time_reached` | string | optional | | |
| `time_base_score` | string | optional | | `system` / `queue` |

### Request Body (JSON)

```json
{
  "name": "Sales01",
  "queue_number": "300",
  "team_id": 2,
  "strategy": "agent-with-fewest-calls",
  "tier_rules_apply": true,
  "tier_rule_wait_second": 15,
  "tier_rule_no_agent_no_wait": true,
  "max_wait_time_with_no_agent": 60,
  "time_base_score": "queue"
}
```

### Response Body (JSON) — 201

```json
{
  "data": {
    "name": "Sales01",
    "queue_number": "300",
    "team_id": 2,
    "strategy": "agent-with-fewest-calls",
    "tier_rules_apply": true,
    "tier_rule_wait_second": 15,
    "tier_rule_wait_multiply_level": false,
    "tier_rule_no_agent_no_wait": true,
    "abandoned_resume_allowed": false,
    "discard_abandoned_after": 0,
    "max_wait_time_with_no_agent": 60,
    "max_wait_time_with_no_agent_time_reached": "hangup",
    "time_base_score": "queue",
    "recording_template": null,
    "status": "active"
  }
}
```

## PUT / DELETE `/api/pbx/queues/{name}`

### PUT

Body chấp nhận mọi field như Create trừ `name` và `queue_number` (immutable).

```json
{
  "strategy": "longest-idle-agent",
  "tier_rule_wait_second": 20,
  "max_wait_time_with_no_agent": 90
}
```

Response 200 = `{ data: { ...17 field queue } }`.

### DELETE

Soft delete + observer tự detach runtime.

```json
{ "data": { "deleted": true } }
```

## Quản lý tier agent

### GET `/api/pbx/queues/{name}/agents` — Liệt kê tier

#### Response body fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị |
|---|---|---|---|
| `extension_number` | string | Số máy nhánh agent | |
| `agent_name` | string | Tên agent `<ext>@<sip-domain>` | |
| `status` | string | Trạng thái presence agent | `available` / `available_on_demand` / `on_break` / `logged_out` |
| `state` | string | State runtime hàng đợi | `idle` / `waiting` / `receiving` / `in_a_queue_call` |
| `tier_level` | integer | Cấp ưu tiên (1 = cao nhất) | 1-9 |
| `tier_position` | integer | Thứ tự trong cùng level | 1-99 |
| `max_no_answer` | integer | Số lần ko nhấc trước khi auto logout | |
| `wrap_up_time` | integer | Thời gian wrap-up sau cuộc (giây) | |

```json
{
  "data": [
    {
      "extension_number": "2001",
      "agent_name": "2001@app.zorio.vn",
      "status": "available",
      "state": "idle",
      "tier_level": 1,
      "tier_position": 1,
      "max_no_answer": 3,
      "wrap_up_time": 5
    }
  ]
}
```

### POST `/api/pbx/queues/{name}/agents` — Thêm tier

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị |
|---|---|---|---|---|
| `extension` | string | ✅ | Số máy nhánh | Phải tồn tại. Regex `^[0-9]{3,10}$` |
| `tier_level` | integer | optional | Cấp ưu tiên | 1-9 (default 1) |
| `tier_position` | integer | optional | Vị trí trong level | 1-99 (default 1) |

Auto tạo record tier agent nếu agent chưa tồn tại. Trả 409 nếu ext đã ở trong queue này.

```json
{ "extension": "2001", "tier_level": 1, "tier_position": 1 }
```

Response 201: `{ "data": { "added": true } }`

### PATCH `/api/pbx/queues/{name}/agents/{ext}` — Sửa tier

**Path**: `name` (queue), `ext` (extension_number).

#### Request body fields (mọi field optional)

| Field | Type | Mô tả | Giá trị |
|---|---|---|---|
| `tier_level` | integer | Cấp ưu tiên | 1-9 |
| `tier_position` | integer | Vị trí trong level | 1-99 |
| `status` | string | Trạng thái presence agent | `available` / `available_on_demand` / `on_break` / `logged_out` |

```json
{ "tier_level": 2, "tier_position": 1, "status": "on_break" }
```

Response 200: `{ "data": { "updated": true } }`

### DELETE `/api/pbx/queues/{name}/agents/{ext}` — Xoá tier

Không có Request Body. Response 200: `{ "data": { "removed": true } }`

KHÔNG xoá tier agent record — chỉ remove khỏi queue (agent có thể tham gia queue khác).


---

# Webhook events PBX

<!-- source: https://docs.zorio.vn/api/pbx/webhooks.md -->

# Webhook events PBX

::: tip Đăng ký webhook
Webhook là **cấu hình của khách hàng** — đăng ký / xoá / xoay secret qua **giao diện Admin** (`Admin Console`). API công khai không expose CRUD subscription.

Tài liệu này document **payload schema** + **HMAC verify** để CRM khách hàng tự xử lý event nhận về.
:::

## Envelope chung

Mọi event đều có cấu trúc envelope:

| Field | Type | Mô tả |
|---|---|---|
| `event` | string | Tên event (xem chi tiết bên dưới) |
| `timestamp` | datetime | Lúc Zorio publish event (ISO 8601 UTC) |
| `data` | object | Payload event-specific |

## `pbx.call.ringing`

Cuộc gọi tới ext, ext đang đổ chuông chưa nhấc.

### `data` fields

| Field | Type | Mô tả | Giá trị |
|---|---|---|---|
| `call_uuid` | string | UUID cuộc gọi | |
| `extension` | string | Số máy nhánh đang đổ chuông | |
| `direction` | string | Hướng cuộc gọi | `inbound` / `outbound` / `internal` |
| `caller_number` | string | Số gọi đi (caller ID) | |
| `destination_number` | string | Số đích (thường = `extension`) | |
| `timestamp` | datetime | Lúc bắt đầu đổ chuông | ISO 8601 |

### Sample payload

```json
{
  "event": "pbx.call.ringing",
  "timestamp": "2026-06-29T03:30:00Z",
  "data": {
    "call_uuid": "...",
    "extension": "1001",
    "direction": "inbound",
    "caller_number": "0987654321",
    "destination_number": "0900000020",
    "timestamp": "2026-06-29T03:30:00Z"
  }
}
```

## `pbx.call.answered`

Ext đã nhấc máy.

`data` fields = giống `pbx.call.ringing` + thêm:

| Field | Type | Mô tả |
|---|---|---|
| `answered_at` | datetime | Lúc nhấc máy (ISO 8601) |

## `pbx.call.hangup`

Cuộc gọi kết thúc — fire ngay lúc sự kiện kết thúc cuộc gọi từ Zorio PBX.

### `data` fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `call_uuid` | string | UUID cuộc gọi | |
| `extension` | string | Máy nhánh liên quan | |
| `direction` | string | Hướng cuộc gọi | `inbound` / `outbound` / `internal` |
| `caller_number` | string | Caller ID | |
| `destination_number` | string | Số đích | |
| `started_at` | datetime\|null | Lúc cuộc gọi bắt đầu (thời điểm bắt đầu cuộc gọi) | ISO 8601 |
| `answered_at` | datetime\|null | Lúc nhấc máy (null nếu không nhấc) | ISO 8601 |
| `ended_at` | datetime | Lúc cúp máy | ISO 8601 |
| `duration_sec` | integer | Tổng thời lượng (giây) | ≥ 0 |
| `billsec` | integer | Thời gian tính tiền (giây) | ≥ 0 |
| `hangup_cause` | string | Mã hangup chuẩn Q.850 từ Zorio PBX | `NORMAL_CLEARING` / `NO_ANSWER` / `USER_BUSY` / `CALL_REJECTED` / `ORIGINATOR_CANCEL` / ... |
| `call_result` | string | Kết quả phân loại nhanh | `answered` (billsec > 0) / `no_answer` (billsec = 0) |
| `recording_url` | string\|null | URL tải ghi âm — `null` ở event realtime (gửi ngay khi cúp), URL có giá trị ở `pbx.cdr.created` (sau khi pipeline ghi âm xong) | |

### Sample payload

```json
{
  "event": "pbx.call.hangup",
  "timestamp": "2026-06-29T03:30:45Z",
  "data": {
    "call_uuid": "...",
    "extension": "1001",
    "direction": "inbound",
    "caller_number": "0987654321",
    "destination_number": "0900000020",
    "started_at": "2026-06-29T03:30:00Z",
    "answered_at": "2026-06-29T03:30:03Z",
    "ended_at": "2026-06-29T03:30:45Z",
    "duration_sec": 45,
    "billsec": 42,
    "hangup_cause": "NORMAL_CLEARING",
    "call_result": "answered",
    "recording_url": null
  }
}
```

## `pbx.cdr.created`

Fire SAU khi pipeline CDR insert row vào DB — có đầy đủ field từ A/B leg processed + `recording_url`.

### `data` fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `call_uuid` | string | UUID cuộc gọi (= UUID cuộc gọi) | |
| `extension` | string\|null | Máy nhánh (ưu tiên `extension_number`, fallback `agent_extension`) | |
| `direction` | string | Hướng | `inbound` / `outbound` / `internal` / `local` |
| `caller_number` | string | Caller ID | |
| `destination_number` | string | Số đích | |
| `started_at` | datetime\|null | Lúc bắt đầu | ISO 8601 |
| `answered_at` | datetime\|null | Lúc nhấc | ISO 8601 |
| `ended_at` | datetime\|null | Lúc cúp | ISO 8601 |
| `duration_sec` | integer | Tổng thời lượng | ≥ 0 |
| `billsec` | integer | Thời gian tính tiền | ≥ 0 |
| `hangup_cause` | string | Mã hangup | (như `pbx.call.hangup`) |
| `result` | string | Kết quả phân loại đầy đủ | `answered` / `busy` / `no_answer` / `failed` / `cancelled` / `rejected` / `voicemail` |
| `recording_url` | string\|null | URL nội bộ trỏ tới endpoint download (yêu cầu Bearer Token) | `https://app.zorio.vn/api/pbx/cdr/{uuid}/recording` hoặc `null` |

### Khác biệt với `pbx.call.hangup`

- `pbx.call.hangup` fire ngay từ sự kiện thời gian thực — `result` chỉ ở mức coarse (answered / no_answer).
- `pbx.cdr.created` fire sau khi pipeline CDR xử lý xong → `result` phân loại chi tiết hơn + có `recording_url`.

## Headers POST từ Zorio tới URL khách

| Header | Ý nghĩa |
|---|---|
| `X-Zorio-Event` | `pbx.call.hangup` |
| `X-Zorio-Timestamp` | epoch giây (UTC). Client reject nếu lệch >300s |
| `X-Zorio-Delivery` | UUID per delivery — dedupe khi retry |
| `X-Zorio-Signature` | `sha256=<hex>` HMAC-SHA256(secret, raw_body) |
| `Content-Type` | `application/json; charset=utf-8` |

## Verify HMAC ở client (mẫu Node.js)

```js
const crypto = require('crypto');

function verify(req, secret) {
  const ts = parseInt(req.headers['x-zorio-timestamp'], 10);
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const sig = req.headers['x-zorio-signature'];
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
```

## Retry policy

Zorio kỳ vọng client trả 2xx trong **5 giây**. Nếu không:

- Lần 2: sau 30 giây
- Lần 3: sau 5 phút
- Lần 4: sau 30 phút
- Max 4 lần → đánh dấu `deadletter` trong bảng nhật ký phân phối webhook

Client nên trả 200 ngay khi nhận event, xử lý async — tránh bị retry chồng.


---

# Caller-ID rotation groups

<!-- source: https://docs.zorio.vn/api/telesales/caller-id-groups.md -->

# Caller-ID rotation groups

::: tip Bối cảnh
Chiến dịch outbound cần xoay vòng nhiều caller-ID để tránh bị nhà mạng đánh dấu spam. Admin Zorio quản lý số gọi ra trong các **rotation group** thông qua UI quản trị; đối tác tích hợp **chỉ cần** đọc danh sách nhóm để gán vào chiến dịch (qua field `caller_id_group_id` khi [tạo Campaign](/api/telesales/campaigns)).
:::

::: warning Endpoint chỉ-đọc
Việc quản lý từng caller-ID, tạo / cập nhật / xoá nhóm (POST/PUT/DELETE), đồng bộ member và clear cooldown đều thực hiện qua UI quản trị Zorio và **không** mở qua Integration API.
:::

## Tổng quan endpoint

| Endpoint | Mục đích |
|---|---|
| `GET /api/caller-id-groups` | Danh sách rotation group của khách hàng |
| `GET /api/caller-id-groups/{id}` | Chi tiết một nhóm + danh sách caller-ID thành viên |
| `GET /api/caller-id-groups/{id}/monitor` | Snapshot runtime per-member (eligibility, cooldown, health) — phục vụ dashboard giám sát |

## `GET /api/caller-id-groups` — danh sách

### Query parameters

Endpoint chỉ trả các nhóm thuộc khách hàng (đã lọc tự động theo authentication). Không có filter bổ sung.

### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID nhóm xoay vòng | |
| `name` | string | Tên nhóm | max 150 ký tự |
| `description` | string\|null | Mô tả nội bộ | max 500 ký tự |
| `rotation_strategy` | string | Chiến lược chọn caller-ID khi gọi ra | `round_robin` / `least_used` / `cap_based` / `weighted` / `sticky_lead` / `random` |
| `sticky_enabled` | bool | Có ghim caller-ID đã dùng cho 1 lead ở các lần gọi sau hay không | `true` / `false` |
| `status` | string | Trạng thái nhóm — `disabled` sẽ bị engine bỏ qua | `active` / `disabled` |
| `caller_ids_count` | integer | Số caller-ID thành viên đang `active` | ≥ 0 |
| `created_at` | datetime | Thời điểm tạo nhóm (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "id":  3,
      "name": "Group A - Viettel Sales",
      "description": "Viettel outbound numbers for the summer campaign",
      "rotation_strategy": "round_robin",
      "sticky_enabled": true,
      "status": "active",
      "caller_ids_count": 12,
      "created_at": "2026-05-20T03:00:00Z"
    }
  ]
}
```

## `GET /api/caller-id-groups/{id}` — chi tiết

### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `id` | integer | ID nhóm (lấy từ list ở trên) |

### Response fields

Bao gồm toàn bộ field như list, kèm thêm mảng `caller_ids[]`:

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `caller_ids[]` | array | Danh sách caller-ID thành viên | |
| `caller_ids[].id` | integer | ID caller-ID | |
| `caller_ids[].number` | string | Số điện thoại gọi ra | E.164 hoặc số nội địa |
| `caller_ids[].display_name` | string\|null | Tên hiển thị nội bộ | max 100 ký tự |
| `caller_ids[].carrier` | string | Nhà mạng | `viettel` / `mobifone` / `vinaphone` / `vietnamobile` / `landline` / `other` |
| `caller_ids[].carrier_label` | string | Nhãn hiển thị nhà mạng | |
| `caller_ids[].status` | string | Trạng thái caller-ID | `active` / `disabled` |
| `caller_ids[].trunk_name` | string\|null | Tên trunk SIP gắn với caller-ID | |
| `caller_ids[].weight` | integer | Trọng số khi `rotation_strategy = weighted` | ≥ 1 (default 1) |

**Response 200**:
```json
{
  "data": {
    "id": 3,
    "name": "Group A - Viettel Sales",
    "description": "...",
    "rotation_strategy": "round_robin",
    "sticky_enabled": true,
    "status": "active",
    "caller_ids_count": 12,
    "created_at": "2026-05-20T03:00:00Z",
    "caller_ids": [
      {
        "id": 18,
        "number": "0900000010",
        "display_name": "Sales Line 1",
        "carrier": "viettel",
        "carrier_label": "Viettel",
        "status": "active",
        "trunk_name": "Trunk-Viettel-01",
        "weight": 2
      }
    ]
  }
}
```

## `GET /api/caller-id-groups/{id}/monitor` — snapshot runtime

Phục vụ dashboard giám sát realtime — hiển thị caller-ID nào đang eligible / cooldown / vượt quota.

### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `id` | integer | ID nhóm |

### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `group_id` | integer | ID nhóm | |
| `group_name` | string | Tên nhóm | |
| `total_members` | integer | Tổng số caller-ID thành viên | |
| `eligible_now` | integer | Số caller-ID đang sẵn sàng được chọn | |
| `in_cooldown` | integer | Số caller-ID đang bị cooldown tạm thời | |
| `disabled` | integer | Số caller-ID bị disable thủ công | |
| `members[]` | array | Snapshot từng caller-ID | |
| `members[].caller_id_id` | integer | ID caller-ID | |
| `members[].number` | string | Số điện thoại | |
| `members[].carrier` | string | Nhà mạng | `viettel` / `mobifone` / `vinaphone` / `vietnamobile` / `landline` / `other` |
| `members[].status` | string | Trạng thái runtime | `eligible` / `cooldown` / `disabled` / `quota_exceeded` |
| `members[].health_score` | integer | Điểm sức khoẻ — càng thấp càng có dấu hiệu bị nhà mạng đánh dấu | 0-100 |
| `members[].calls_today` | integer | Số cuộc đã gọi trong ngày | ≥ 0 |
| `members[].daily_cap` | integer | Giới hạn cuộc/ngày | ≥ 1 |
| `members[].cooldown_until` | datetime\|null | Thời điểm hết cooldown (null nếu không bị cooldown) | ISO 8601 UTC |

**Response 200**:
```json
{
  "data": {
    "group_id": 3,
    "group_name": "Group A - Viettel Sales",
    "total_members": 12,
    "eligible_now": 9,
    "in_cooldown": 2,
    "disabled": 1,
    "members": [
      {
        "caller_id_id": 18,
        "number": "0900000010",
        "carrier": "viettel",
        "status": "eligible",
        "health_score": 82,
        "calls_today": 87,
        "daily_cap": 200,
        "cooldown_until": null
      },
      {
        "caller_id_id": 19,
        "number": "0900000011",
        "carrier": "mobifone",
        "status": "cooldown",
        "health_score": 14,
        "calls_today": 53,
        "daily_cap": 200,
        "cooldown_until": "2026-06-06T12:00:00Z"
      }
    ]
  }
}
```

**Response 404**: `{ "message": "Pool not found." }`.

## Gán nhóm vào chiến dịch

Trong body khi **[tạo Campaign](/api/telesales/campaigns)**, gán `caller_id_group_id` bằng `id` trả về từ `GET /api/caller-id-groups`:

```json
{
  "name": "Summer Promo",
  "caller_id_group_id": 3,
  ...
}
```

Khi chiến dịch chuyển trạng thái `draft → active` (`PUT /api/telesales/campaigns/{id}/status`), field `caller_id_group_id` là **bắt buộc** — nếu thiếu, server trả 422.


---

# Chiến dịch (Campaigns)

<!-- source: https://docs.zorio.vn/api/telesales/campaigns.md -->

# Chiến dịch (Campaigns)

Nhóm endpoint quản trị chiến dịch outbound: tạo mới, điều khiển vòng đời (launch/pause/resume/archive/clone), thống kê hiệu suất + chuỗi thời gian, và quản lý đội ngũ agent gán vào từng chiến dịch. Vòng đời từng cuộc gọi (initiate / status / hangup / disposition) cũng được mô tả ở cuối trang để tiện đối tác tích hợp.

## 3.1 Tạo chiến dịch

```http
POST /api/telesales/campaigns
```

### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `name` | string | ✅ | Tên chiến dịch, unique trong tài khoản | max 150 ký tự |
| `description` | string | optional | Mô tả ngắn | max 500 ký tự |
| `dialer_mode` | string | ✅ | Chế độ quay số | `manual` / `preview` / `progressive` / `predictive` |
| `caller_id_group_id` | integer | ✅ | ID nhóm xoay vòng caller-ID (xem §Caller-ID rotation groups) | Phải tồn tại + `status=active` |
| `script_id` | integer | optional | ID kịch bản hội thoại gán cho chiến dịch | Phải tồn tại |
| `ring_timeout_sec` | integer | optional | Thời gian đổ chuông tối đa (giây) | 5-120 (default 25) |
| `preview_window_sec` | integer | optional | Thời gian agent xem trước lead khi `dialer_mode=preview` | 0-60 (default 10) |
| `priority` | integer | optional | Mức ưu tiên — số càng lớn càng ưu tiên | 0-1000 (default 100) |
| `max_attempts` | integer | optional | Số lần thử lại tối đa cho 1 lead | 1-20 (default 5) |
| `pdpl_enforce` | bool | optional | Bật khung giờ pháp lý (PDPL/TCPA) | `true` / `false` (default `true`) |
| `abandon_rate_limit_pct` | float | optional | Ngưỡng abandon rate tối đa (% — predictive mode) | 0.0-10.0 (default 3.0) |
| `time_window` | object | optional | Khung giờ gọi cho phép theo từng ngày trong tuần | Key: `mon`/`tue`/`wed`/`thu`/`fri`/`sat`/`sun` → mảng `{from,to}` HH:MM |

**Giá trị `dialer_mode`**:
- `manual` — agent tự bấm số gọi từng cuộc.
- `preview` — hệ thống đẩy lead cho agent xem trước rồi mới quay số.
- `progressive` — hệ thống tự quay số khi có agent rảnh.
- `predictive` — hệ thống quay số trước cả khi agent rảnh (giới hạn tuân thủ qua `abandon_rate_limit_pct`).

**Body**:
```json
{
  "name": "Outbound Sales Q3-2026",
  "description": "Q3 outbound campaign",
  "dialer_mode": "progressive",
  "caller_id_group_id": 3,
  "script_id": 12,
  "ring_timeout_sec": 25,
  "preview_window_sec": 10,
  "priority": 100,
  "max_attempts": 5,
  "pdpl_enforce": true,
  "abandon_rate_limit_pct": 3.0,
  "time_window": {
    "mon": [{"from": "08:00", "to": "17:30"}],
    "tue": [{"from": "08:00", "to": "17:30"}],
    "wed": [{"from": "08:00", "to": "17:30"}],
    "thu": [{"from": "08:00", "to": "17:30"}],
    "fri": [{"from": "08:00", "to": "17:30"}],
    "sat": [{"from": "08:00", "to": "12:00"}]
  }
}
```

### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID chiến dịch | |
| `name` | string | Tên chiến dịch | |
| `description` | string\|null | Mô tả ngắn | |
| `status` | string | Trạng thái vòng đời | `draft` / `active` / `paused` / `archived` |
| `dialer_mode` | string | Chế độ quay số | `manual` / `preview` / `progressive` / `predictive` |
| `caller_id_group_id` | integer | ID nhóm caller-ID rotation | |
| `script_id` | integer\|null | ID script | |
| `ring_timeout_sec` | integer | Thời gian đổ chuông tối đa | 5-120 |
| `preview_window_sec` | integer | Cửa sổ preview | 0-60 |
| `priority` | integer | Mức ưu tiên | 0-1000 |
| `max_attempts` | integer | Số lần thử lại tối đa | 1-20 |
| `pdpl_enforce` | bool | Bật khung giờ PDPL | |
| `abandon_rate_limit_pct` | float | Ngưỡng abandon rate (predictive) | 0.0-10.0 |
| `time_window` | object | Khung giờ gọi theo ngày | |
| `total_leads` | integer | Số lead đã import vào chiến dịch | |
| `created_by` | integer | ID user tạo chiến dịch | |
| `created_at` | datetime | Thời điểm tạo (ISO 8601 UTC) | |
| `updated_at` | datetime | Thời điểm cập nhật cuối | |

**Response 201**:
```json
{
  "data": {
    "id": 36,
    "name": "Outbound Sales Q3-2026",
    "description": "Q3 outbound campaign",
    "status": "draft",
    "dialer_mode": "progressive",
    "caller_id_group_id": 3,
    "script_id": 12,
    "ring_timeout_sec": 25,
    "preview_window_sec": 10,
    "priority": 100,
    "max_attempts": 5,
    "pdpl_enforce": true,
    "abandon_rate_limit_pct": 3.0,
    "time_window": { "mon": [{"from":"08:00","to":"17:30"}], "...": "..." },
    "total_leads": 0,
    "created_by": 7,
    "created_at": "2026-06-06T06:00:00Z",
    "updated_at": "2026-06-06T06:00:00Z"
  }
}
```

**Response 422** (validate sai):
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "dialer_mode": ["The selected dialer mode is invalid."],
    "caller_id_group_id": ["The selected caller id group id is invalid."]
  }
}
```

## 3.2 Điều khiển vòng đời chiến dịch

| Endpoint | Hành động | Response |
|---|---|---|
| `POST /api/telesales/campaigns/{id}/launch` | draft → active | `{ "data": { "id":36, "status":"active", "launched_at":"...Z" } }` |
| `POST /api/telesales/campaigns/{id}/pause` | active → paused | `{ "data": { "id":36, "status":"paused" } }` |
| `POST /api/telesales/campaigns/{id}/resume` | paused → active | `{ "data": { "id":36, "status":"active" } }` |
| `POST /api/telesales/campaigns/{id}/archive` | → archived | `{ "data": { "id":36, "status":"archived" } }` |
| `POST /api/telesales/campaigns/{id}/clone` | → bản draft mới | `{ "data": { "id":42, "status":"draft", "name":"... (clone)" } }` |
| `PUT  /api/telesales/campaigns/{id}` | Cập nhật field | trả về toàn bộ object chiến dịch |
| `DELETE /api/telesales/campaigns/{id}` | Xoá mềm | `204 No Content` |

## 3.3 Danh sách / chi tiết / thống kê

### `GET /api/telesales/campaigns` — danh sách

#### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `status` | string | optional | Lọc theo trạng thái vòng đời | `draft` / `active` / `paused` / `archived` |
| `dialer_mode` | string | optional | Lọc theo chế độ quay số | `manual` / `preview` / `progressive` / `predictive` |
| `q` | string | optional | Tìm theo `name` (LIKE %keyword%) | |
| `page` | integer | optional | Số trang | ≥ 1 (default 1) |
| `per_page` | integer | optional | Bản ghi mỗi trang | 1-200 (default 50) |

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID chiến dịch | |
| `name` | string | Tên chiến dịch | |
| `status` | string | Trạng thái vòng đời | `draft` / `active` / `paused` / `archived` |
| `dialer_mode` | string | Chế độ quay số | `manual` / `preview` / `progressive` / `predictive` |
| `total_leads` | integer | Tổng số lead đã import | |
| `dialled` | integer | Số lần đã quay số | |
| `answered` | integer | Số cuộc bắt máy | |
| `converted` | integer | Số cuộc chuyển đổi thành công | |
| `asr_pct` | float | Answer-Seizure Ratio (%) = `answered/dialled*100` | 0-100 |

**Response 200**:
```json
{
  "data": [
    { "id": 36, "name": "Outbound Sales Q3-2026", "status": "active",
      "dialer_mode": "progressive", "total_leads": 487, "dialled": 312,
      "answered": 198, "converted": 47, "asr_pct": 63.5 }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }
}
```

### `GET /api/telesales/campaigns/{id}/stats` — thống kê tổng hợp

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `dialled` | integer | Tổng số lần quay số | |
| `answered` | integer | Tổng số cuộc bắt máy | |
| `talked_over_30s` | integer | Số cuộc có `billsec ≥ 30` | |
| `converted` | integer | Số cuộc chuyển đổi (disposition `is_final=true` + outcome thành công) | |
| `answer_rate_pct` | float | `answered/dialled*100` | 0-100 |
| `conversion_rate_pct` | float | `converted/answered*100` | 0-100 |
| `asr_pct` | float | Answer-Seizure Ratio (%) | 0-100 |
| `aht_seconds` | integer | Average Handle Time (giây) — trung bình thời gian xử lý mỗi cuộc | |
| `abandon_rate_pct` | float | Tỷ lệ abandoned (% — chỉ tính trong predictive mode) | 0-100 |
| `callbacks_pending` | integer | Số callback đang chờ thực hiện | |

**Response 200**:
```json
{
  "data": {
    "dialled": 312,
    "answered": 198,
    "talked_over_30s": 142,
    "converted": 47,
    "answer_rate_pct": 63.46,
    "conversion_rate_pct": 15.06,
    "asr_pct": 63.46,
    "aht_seconds": 184,
    "abandon_rate_pct": 1.8,
    "callbacks_pending": 23
  }
}
```

### `GET /api/telesales/campaigns/{id}/timeseries` — chuỗi thời gian

#### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `group_by` | string | optional | Đơn vị group | `hour` / `day` / `week` (default `day`) |
| `date_from` | datetime | optional | Mốc bắt đầu (UTC ISO 8601) | |
| `date_to` | datetime | optional | Mốc kết thúc (UTC ISO 8601) | |

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `bucket` | string | Mốc thời gian — định dạng theo `group_by` | `YYYY-MM-DD` / `YYYY-Www` / `YYYY-MM-DD HH:00:00` |
| `dialled` | integer | Số lần quay số trong bucket | |
| `answered` | integer | Số cuộc bắt máy trong bucket | |
| `converted` | integer | Số cuộc chuyển đổi trong bucket | |

**Response 200**:
```json
{
  "data": [
    { "bucket": "2026-06-01", "dialled": 80, "answered": 51, "converted": 12 },
    { "bucket": "2026-06-02", "dialled": 92, "answered": 60, "converted": 15 },
    { "bucket": "2026-06-03", "dialled": 75, "answered": 47, "converted":  9 }
  ],
  "meta": { "range": "7d" }
}
```

## 3.4 Quản lý agent của chiến dịch

| Endpoint | Mục đích |
|---|---|
| `GET    /api/telesales/campaigns/{id}/agents` | Danh sách agent đang gán vào chiến dịch |
| `GET    /api/telesales/campaigns/{id}/agents/available` | Danh sách user đủ điều kiện gán (chưa thuộc chiến dịch khác xung đột, có role phù hợp) |
| `POST   /api/telesales/campaigns/{id}/agents` | Gán một agent vào chiến dịch |
| `PATCH  /api/telesales/campaigns/{id}/agents/{userId}` | Cập nhật role hoặc trạng thái của agent |
| `DELETE /api/telesales/campaigns/{id}/agents/{userId}` | Gỡ agent khỏi chiến dịch |

### `GET /api/telesales/agents` — danh sách agent của khách hàng

Đối tác tích hợp dùng để chọn `user_id` cho `POST /api/telesales/campaigns/{id}/agents`:

```http
GET /api/telesales/agents?per_page=50&page=1
```

#### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `q` | string | optional | Tìm theo `name` / `username` / `email` (LIKE %keyword%) | |
| `role` | string | optional | Lọc theo role | `agent` / `supervisor` / `manager` / ... |
| `team_id` | integer | optional | Lọc theo team | |
| `page` | integer | optional | Số trang | ≥ 1 (default 1) |
| `per_page` | integer | optional | Bản ghi mỗi trang | 1-200 (default 50) |

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | User ID | |
| `name` | string | Họ tên | |
| `username` | string | Tên đăng nhập | |
| `email` | string | Email | |
| `role` | string | Vai trò trong hệ thống | `agent` / `supervisor` / `manager` |
| `team_id` | integer\|null | ID team đang thuộc | |
| `extension` | string\|null | Số máy nhánh SIP đã gán | |
| `is_active` | bool | User còn hoạt động không | `true` / `false` |

**Response 200**:
```json
{
  "data": [
    {
      "id": 25,
      "name": "Nguyen Van A",
      "username": "nguyenvana",
      "email": "nguyenvana@company.com",
      "role": "agent",
      "team_id": 3,
      "extension": "1001",
      "is_active": true
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 50, "total": 142 }
}
```

Chỉ trả về user có `is_active=true`, sắp xếp theo `name`.

**Workflow gán agent vào chiến dịch**:
```http
# Bước 1: lấy danh sách agent có sẵn
GET /api/telesales/agents?role=agent

# Bước 2: gán user_id=25 vào chiến dịch
POST /api/telesales/campaigns/36/agents
{ "user_id": 25, "role": "agent" }
```

### `GET /api/telesales/campaigns/{id}/agents`

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `user_id` | integer | ID user agent | |
| `username` | string | Tên đăng nhập | |
| `display_name` | string | Tên hiển thị | |
| `campaign_id` | integer | ID chiến dịch | |
| `role` | string | Vai trò trong chiến dịch | `agent` / `supervisor` |
| `extension` | string\|null | Số máy nhánh SIP | |
| `team_id` | integer\|null | ID team | |
| `team_name` | string\|null | Tên team | |
| `is_active` | bool | User còn hoạt động không | `true` / `false` |
| `assigned_at` | datetime | Thời điểm gán vào chiến dịch (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "user_id": 25,
      "username": "agent01",
      "display_name": "Nguyen Van A",
      "campaign_id": 36,
      "role": "agent",
      "extension": "2001",
      "team_id": 3,
      "team_name": "Sales A",
      "is_active": true,
      "assigned_at": "2026-06-06T06:10:00Z"
    }
  ]
}
```

### `GET /api/telesales/campaigns/{id}/agents/available`

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `user_id` | integer | ID user agent có thể gán | |
| `username` | string | Tên đăng nhập | |
| `display_name` | string | Tên hiển thị | |
| `extension` | string\|null | Số máy nhánh SIP | |
| `team_id` | integer\|null | ID team | |
| `team_name` | string\|null | Tên team | |
| `role` | string | Vai trò hệ thống | `agent` / `supervisor` |
| `is_active` | bool | User còn hoạt động không | `true` / `false` |

**Response 200**:
```json
{
  "data": [
    {
      "user_id": 30,
      "username": "agent06",
      "display_name": "Tran Thi B",
      "extension": "2006",
      "team_id": 3,
      "team_name": "Sales A",
      "role": "agent",
      "is_active": true
    }
  ]
}
```

### `POST /api/telesales/campaigns/{id}/agents` — gán agent

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `user_id` | integer | ✅ | ID user cần gán | Phải tồn tại + `is_active=true` + có extension SIP |
| `role` | string | optional | Vai trò trong chiến dịch | `agent` (default) / `supervisor` |

**Body**:
```json
{ "user_id": 25, "role": "agent" }
```

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `user_id` | integer | ID user vừa gán | |
| `campaign_id` | integer | ID chiến dịch | |
| `role` | string | Vai trò trong chiến dịch | `agent` / `supervisor` |
| `assigned_at` | datetime | Thời điểm gán (ISO 8601 UTC) | |

**Response 201**:
```json
{
  "data": {
    "user_id": 25,
    "campaign_id": 36,
    "role": "agent",
    "assigned_at": "2026-06-06T06:10:00Z"
  }
}
```

**Response 422 — các trường hợp validate / xung đột**:

```json
// User không tồn tại hoặc đã ngừng hoạt động
{
  "message": "The given data was invalid.",
  "errors": { "user_id": ["The selected user id is invalid."] }
}

// User đã được gán vào chiến dịch khác (mỗi user chỉ thuộc 1 chiến dịch tại 1 thời điểm)
{
  "message": "Agent is already attached to another active campaign.",
  "errors": { "user_id": ["User 25 already assigned to campaign 38."] }
}

// User chưa được cấp extension SIP (không thể nhận cuộc gọi)
{
  "message": "User has no SIP extension assigned — cannot be assigned as an agent.",
  "errors": { "user_id": ["User 25 has no extension assigned."] }
}

// Role không hợp lệ (chỉ chấp nhận agent / supervisor)
{
  "message": "The given data was invalid.",
  "errors": { "role": ["The selected role is invalid."] }
}
```

### `PATCH /api/telesales/campaigns/{id}/agents/{userId}` — cập nhật role

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `role` | string | ✅ | Vai trò mới trong chiến dịch | `agent` / `supervisor` |

**Body**:
```json
{ "role": "supervisor" }
```

**Response 200**:
```json
{ "data": { "user_id": 25, "campaign_id": 36, "role": "supervisor", "assigned_at": "2026-06-06T06:10:00Z" } }
```

**Response 404** — agent chưa được gán vào chiến dịch này:
```json
{ "message": "Agent is not attached to this campaign." }
```

### `DELETE /api/telesales/campaigns/{id}/agents/{userId}`

**Response 204 No Content** (thành công).

**Response 422 — agent đang ở trên cuộc gọi**:
```json
{
  "message": "Cannot unassign an agent who is currently on a call.",
  "errors": { "user_id": ["Agent 25 is currently on call UUID xxx — wait for it to end or force-hangup first."] }
}
```

::: tip Lưu ý
Sau khi `DELETE` thành công, agent sẽ không nhận thêm cuộc gọi mới từ chiến dịch, nhưng cuộc gọi đang quay sẽ chạy đến lúc kết thúc. Trạng thái presence realtime tự đồng bộ trong vòng 5 giây.
:::

---

## 7. Vòng đời cuộc gọi (Call Lifecycle)

Một cuộc gọi đi qua 4 bước chính do agent (hoặc hệ thống) khởi tạo trong phạm vi chiến dịch.

::: tip Mẹo
Nếu đối tác dùng Webphone SDK, toàn bộ 4 bước được đóng gói trong `phone.call(number, options)` — không cần gọi trực tiếp các endpoint dưới. Xem tài liệu Webphone SDK.
:::

### 7.1 Khởi tạo cuộc gọi
```http
POST /api/telesales/calls/initiate
```

Extension của agent được lấy từ profile của user đã xác thực — không cần truyền tay.

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `campaign_id` | integer | ✅ | ID chiến dịch agent đang chạy | Phải tồn tại + `status=active` + agent đã được gán |
| `lead_id` | integer | ✅ | ID lead cần quay số | Phải thuộc `campaign_id` + `status` không phải `dnc`/`exhausted`/`converted` |

**Body**:
```json
{
  "campaign_id": 36,
  "lead_id": 78912
}
```

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi — dùng cho mọi endpoint con (`/status`, `/hangup`, `/disposition`) | UUID v4 |
| `status` | string | Trạng thái khởi tạo | `originating` |
| `caller_id_used` | string | Số gọi ra (caller-ID) được nhóm rotation chọn | E.164 |
| `lead_id` | integer | ID lead | |
| `campaign_id` | integer | ID chiến dịch | |

**Response 200**:
```json
{
  "uuid": "093e1024-82c6-49b3-8775-99edeb221898",
  "status": "originating",
  "caller_id_used": "0900000010",
  "lead_id": 78912,
  "campaign_id": 36
}
```

**Response 422** (vi phạm PDPL window):
```json
{
  "error": "pdpl_blocked",
  "message": "Outside the campaign calling window (08:00-17:30, Mon-Sat).",
  "next_eligible_at": "2026-06-07T01:00:00Z"
}
```

**Response 422** (các lý do khác):
```json
{
  "error": "lead_dnc",
  "message": "Lead phone is on the DNC list."
}
```
Các mã lỗi khác: `lead_blocked`, `no_caller_id_available`, `max_attempts_reached`.

### 7.2 Theo dõi trạng thái cuộc gọi
```http
GET /api/telesales/calls/{uuid}/status
```

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi | UUID v4 |
| `state` | string | Trạng thái hiện tại | `originating` / `ringing` / `answered` / `wrap_up` / `closed` |
| `start_time` | datetime | Thời điểm khởi tạo (ISO 8601 UTC) | |
| `answer_time` | datetime\|null | Thời điểm khách bắt máy | `null` nếu chưa bắt máy |
| `end_time` | datetime\|null | Thời điểm kết thúc | `null` nếu chưa kết thúc |
| `duration` | integer\|null | Tổng thời gian từ originate đến hangup (giây) | |
| `billsec` | integer\|null | Thời gian đàm thoại (giây) — từ `answer_time` đến `end_time` | |
| `result` | string\|null | Kết quả cuối — mapping từ hangup cause | `answered` / `no_answer` / `busy` / `failed` / `cancelled` |
| `hangup_cause` | string\|null | Lý do hangup từ Zorio PBX | vd `NORMAL_CLEARING` / `USER_BUSY` |
| `caller_id_used` | string | Số gọi ra | E.164 |
| `agent_extension` | string | Số máy nhánh của agent | |
| `destination_number` | string | Số điện thoại đích (lead) | |

### 7.3 Cúp máy thủ công

```http
POST /api/telesales/calls/{uuid}/hangup
```

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `cause` | string | optional | Lý do hangup tự đặt — lưu vào CDR để báo cáo | free text max 64 ký tự (default `MANUAL_HANGUP`) |

**Body** (tuỳ chọn):
```json
{ "cause": "MANUAL_HANGUP" }
```

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi | UUID v4 |
| `state` | string | Trạng thái sau hangup | `wrap_up` (sang chờ agent disposition) |
| `end_time` | datetime | Thời điểm hangup (ISO 8601 UTC) | |
| `duration` | integer | Tổng thời gian cuộc gọi (giây) | |
| `billsec` | integer | Thời gian đàm thoại (giây) | |
| `hangup_cause` | string | Lý do hangup (echo từ request hoặc tự sinh) | |

**Response 200**:
```json
{
  "data": {
    "uuid": "093e1024-82c6-49b3-8775-99edeb221898",
    "state": "wrap_up",
    "end_time": "2026-06-06T06:35:42Z",
    "duration": 222,
    "billsec": 213,
    "hangup_cause": "MANUAL_HANGUP"
  }
}
```

**Response 404** — UUID không tồn tại hoặc không thuộc tài khoản:
```json
{ "message": "Call not found." }
```

**Response 422** — cuộc gọi đã kết thúc:
```json
{
  "message": "Call has already ended, hangup is not possible.",
  "errors": { "uuid": ["Call already in state 'closed' since 2026-06-06T06:34:00Z."] }
}
```

**Response 403** — agent thường cố cúp máy cuộc gọi của người khác mà chưa có quyền supervisor:
```json
{ "message": "You are not allowed to hang up this call. Supervisor role is required to force hangup." }
```

### 7.4 Gửi kết quả cuộc gọi (Disposition)
```http
POST /api/telesales/calls/{uuid}/disposition
```

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `disposition_id` | integer | ✅ | ID disposition (map từ `code`, vd `SALE-OK`) | Phải tồn tại + `is_active=true` |
| `note` | string | optional | Ghi chú text của agent | max 1000 ký tự |
| `callback_at` | datetime | optional | Lịch gọi lại (ISO 8601 UTC) — chỉ dùng khi disposition có `trigger_callback=true` | Phải lớn hơn thời điểm hiện tại |
| `callback_agent_id` | integer | optional | Sticky agent cho cuộc callback | User ID phải là agent của chiến dịch |

**Body**:
```json
{
  "disposition_id": 5,
  "note": "Customer committed, follow-up email scheduled",
  "callback_at": null,
  "callback_agent_id": null
}
```

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi | UUID v4 |
| `state` | string | Trạng thái sau khi gửi disposition | `closed` |
| `disposition` | object | Chi tiết disposition vừa áp | `{id, code, label, category}` |
| `disposition.id` | integer | ID disposition | |
| `disposition.code` | string | Code immutable (vd `SALE-OK`) | |
| `disposition.label` | string | Nhãn hiển thị | |
| `disposition.category` | string | Phân loại | `contact` / `no_contact` / `callback` / `remove` |
| `lead_id` | integer | ID lead | |
| `lead_status_after` | string | Trạng thái lead sau khi áp disposition | `pending` / `contacted` / `converted` / `dnc` / `exhausted` |
| `callback_scheduled` | object\|null | Thông tin callback (nếu có) | `{callback_at, agent_id}` hoặc `null` |

**Response 200**:
```json
{
  "data": {
    "uuid": "093e1024-82c6-49b3-8775-99edeb221898",
    "state": "closed",
    "disposition": { "id": 5, "code": "SALE-OK", "label": "Sale Success", "category": "contact" },
    "lead_id": 78912,
    "lead_status_after": "converted",
    "callback_scheduled": null
  }
}
```

::: tip Các trường outcome theo ngành nghề
Các trường outcome chuyên biệt (Payment Method, Appointment Date, Survey Result, Lead Score, Notes, ...) được khai báo qua **custom field** ở từng disposition do admin của khách hàng cấu hình. Schema chi tiết cho từng ngành (chăm sóc khách hàng, lịch hẹn dịch vụ, khảo sát mức độ hài lòng, ...) nằm trong **gói cấu hình riêng** riêng cho khách hàng.
:::


---

# DNC list

<!-- source: https://docs.zorio.vn/api/telesales/dnc.md -->

# DNC list

Quản lý danh sách Do-Not-Call (DNC) của khách hàng: tra cứu, thêm/xoá đơn lẻ, bulk import CSV và export. Mọi số điện thoại đều được normalise sang E.164 (`+84...`) tự động ở phía server.

## Tổng quan endpoint

| Endpoint | Mục đích |
|---|---|
| `GET    /api/telesales/dnc` | Liệt kê số điện thoại trong DNC |
| `POST   /api/telesales/dnc` | Thêm một số vào DNC |
| `DELETE /api/telesales/dnc/{phone}` | Gỡ một số khỏi DNC |
| `POST   /api/telesales/dnc/import` | Bulk import qua CSV (multipart) |
| `GET    /api/telesales/dnc/export` | Export toàn bộ DNC ra CSV |

## `GET /api/telesales/dnc` — danh sách

### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `q` | string | optional | Tìm theo số điện thoại (LIKE %keyword%) | |
| `source` | string | optional | Lọc theo nguồn ghi nhận | `manual` / `import` / `disposition` / `webhook` |
| `date_from` | datetime | optional | Lọc `added_at ≥` (ISO 8601 UTC) | |
| `date_to` | datetime | optional | Lọc `added_at ≤` (ISO 8601 UTC) | |
| `page` | integer | optional | Số trang | ≥ 1 (default 1) |
| `per_page` | integer | optional | Bản ghi mỗi trang | 1-200 (default 50) |

### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `phone` | string | Số điện thoại gốc (định dạng khi insert) | |
| `phone_e164` | string | Số chuẩn hoá E.164 | `+84...` |
| `reason` | string\|null | Lý do thêm vào DNC | max 500 ký tự |
| `source` | string | Nguồn ghi nhận | `manual` / `import` / `disposition` / `webhook` |
| `added_by` | integer\|null | User ID người thêm (null nếu từ webhook/system) | |
| `added_by_name` | string\|null | Tên hiển thị người thêm | |
| `added_at` | datetime | Thời điểm thêm (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "phone": "0900000000",
      "phone_e164": "+84900000000",
      "reason": "Customer opt-out",
      "source": "manual",
      "added_by": 7,
      "added_by_name": "Nguyen Van A",
      "added_at": "2026-04-01T03:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 50, "total": 124 }
}
```

## `POST /api/telesales/dnc` — thêm một số

### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `phone` | string | ✅ | Số điện thoại — server tự normalise về `+84...` | `0xxxxxxxxx` hoặc `+84xxxxxxxxx` |
| `reason` | string | optional | Lý do thêm vào DNC | max 500 ký tự |

**Body**:
```json
{
  "phone": "0912345678",
  "reason": "Customer opt-out via inbound IVR"
}
```

### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `phone` | string | Số gốc khi POST | |
| `phone_e164` | string | Số đã chuẩn hoá | `+84...` |
| `reason` | string\|null | Lý do | |
| `source` | string | Nguồn — luôn `manual` khi tạo qua endpoint này | `manual` |
| `added_by` | integer | User ID người tạo | |
| `added_at` | datetime | Thời điểm tạo (ISO 8601 UTC) | |

**Response 201**:
```json
{
  "data": {
    "phone": "0912345678",
    "phone_e164": "+84912345678",
    "reason": "Customer opt-out via inbound IVR",
    "source": "manual",
    "added_by": 7,
    "added_at": "2026-06-06T07:00:00Z"
  }
}
```

**Response 422 — các trường hợp validate sai**:
```json
// Số điện thoại sai định dạng
{
  "message": "The given data was invalid.",
  "errors": { "phone": ["The phone format is invalid. Expected 0xxxxxxxxx or +84xxxxxxxxx."] }
}

// Số đã có trong DNC
{
  "message": "Phone number is already on the DNC list.",
  "errors": { "phone": ["Phone +84912345678 already in DNC since 2026-05-01."] }
}
```

## `DELETE /api/telesales/dnc/{phone}`

`{phone}` chấp nhận cả `0xxxxxxxxx` và `+84xxxxxxxxx` (server tự normalise).

**Response 204 No Content** (thành công).

**Response 404** — số không có trong DNC:
```json
{ "message": "Phone +84912345678 not found in DNC." }
```

## `POST /api/telesales/dnc/import` — bulk CSV

**Request**: `multipart/form-data`

| Field | Mô tả |
|---|---|
| `file` | File CSV (UTF-8). Cột bắt buộc: `phone`. Cột tuỳ chọn: `reason`. |
| `dedupe` | `skip` (mặc định — bỏ qua dòng đã tồn tại) \| `update` (ghi đè `reason`) |

**Ví dụ định dạng file**:
```csv
phone,reason
0912345678,Customer opt-out
0987654321,Wrong number
```

**Response 200**:
```json
{
  "data": {
    "total_rows":   1500,
    "created":      1342,
    "skipped":      147,
    "errors":       11,
    "error_samples": [
      { "row": 23, "phone": "12345",       "error": "Invalid phone format" },
      { "row": 47, "phone": "0999999999",  "error": "Already exists" }
    ]
  }
}
```

**Response 422** — file đọc không được:
```json
{
  "message": "Unable to read the CSV file.",
  "errors": { "file": ["Missing required column: phone."] }
}
```

## `GET /api/telesales/dnc/export`

**Query params**: cùng bộ filter với `GET /api/telesales/dnc` (`q`, `source`, `date_from`, `date_to`).

**Response 200**: `text/csv` — file stream với header `Content-Disposition: attachment; filename="dnc-export-YYYYMMDD.csv"`. Các cột: `phone, phone_e164, reason, source, added_by_name, added_at`.


---

# Telesales API — Tổng quan

<!-- source: https://docs.zorio.vn/api/telesales/index.md -->

# Telesales API — Tổng quan

> Public REST API cho Module Telesales. Tích hợp dialer + chiến dịch + lead + caller-ID rotation + ghi âm + báo cáo cho CRM khách hàng.
>
> **Xác thực**: Bearer Token (phiên user). **Base URL**: `https://app.zorio.vn/api/telesales/` (cấp riêng theo khách hàng).

## Phạm vi

Telesales API gồm **11 nhóm endpoint**:

- Quản lý chiến dịch (Campaigns) — CRUD + lifecycle (launch/pause/resume/archive/clone).
- Quản lý lead (Leads) — CRUD + bulk PATCH/DELETE/DNC.
- DNC (Do Not Call) — danh sách chặn gọi, hỗ trợ import CSV.
- Caller-ID rotation groups — 6 chiến lược xoay vòng (round_robin, least_used, cap_based, weighted, sticky_lead, random).
- Script + Outcome — kịch bản gọi + disposition codes.
- Recording — ghi âm + export bulk.
- 9 báo cáo: dashboard / agent-performance / funnel / disposition-breakdown / caller-id-health / hour-dow-heatmap / lead-source-attribution / time-series / abandon-rate.

## Các nhóm endpoint

| Nhóm | Tài liệu |
|---|---|
| Chiến dịch (Campaigns) | [Tới trang](/api/telesales/campaigns) |
| Khách hàng tiềm năng (Leads) | [Tới trang](/api/telesales/leads) |
| DNC list | [Tới trang](/api/telesales/dnc) |
| Caller-ID rotation groups | [Tới trang](/api/telesales/caller-id-groups) |
| Script + Outcome | [Tới trang](/api/telesales/scripts) |
| Recording | [Tới trang](/api/telesales/recording) |
| Báo cáo (9 báo cáo) | [Tới trang](/api/telesales/reports) |


---

# Khách hàng tiềm năng (Leads)

<!-- source: https://docs.zorio.vn/api/telesales/leads.md -->

# Khách hàng tiềm năng (Leads)

Nhóm endpoint quản lý lead trong từng chiến dịch: import 3 bước (preview → dry-run → commit), CRUD đơn lẻ, bulk update / delete / mark DNC, cùng cơ chế custom field linh hoạt qua JSON.

## 4.1 Import lead

::: tip Định dạng file
CSV (UTF-8) hoặc XLSX. Có template tổng quát `CallList_Template.xlsx`; template chuyên biệt theo từng ngành nghề được cấp trong gói cấu hình riêng riêng cho khách hàng.
:::

Quy trình 3 bước:

### Bước 1 — Preview (xem cấu trúc cột)
```http
POST /api/telesales/campaigns/{id}/leads/preview
Content-Type: multipart/form-data

file=@call_list.csv
```

#### Request form fields (multipart)

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `file` | file | ✅ | File CSV (UTF-8) hoặc XLSX cần preview | max 10MB |

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `headers` | string[] | Danh sách header phát hiện ở hàng đầu | |
| `sample` | array[] | Tối đa 5 hàng dữ liệu mẫu | |
| `mapping_suggestions` | object[] | Gợi ý mapping cột → field hệ thống | |
| `mapping_suggestions[].index` | integer | Vị trí cột (0-based) | |
| `mapping_suggestions[].header` | string | Tên cột | |
| `mapping_suggestions[].sample` | string | Mẫu dữ liệu | |
| `mapping_suggestions[].suggested` | string\|null | Field hệ thống được gợi ý mapping | `full_name` / `phone` / `email` / `null` |
| `row_count` | integer | Tổng số dòng (không kể header) | |

**Response 200**:
```json
{
  "headers": ["Customer Name","Primary Phone","Alt. Phone","Reference Code","Note"],
  "sample": [
    ["Nguyen Mai","0912345678","0988111222","REF-001","High-value prospect"],
    ["Tran Hoa","0987654321","","REF-002",""]
  ],
  "mapping_suggestions": [
    { "index": 0, "header": "Customer Name",  "sample": "Nguyen Mai",  "suggested": "full_name" },
    { "index": 1, "header": "Primary Phone",  "sample": "0912345678",  "suggested": "phone" },
    { "index": 2, "header": "Alt. Phone",     "sample": "0988111222",  "suggested": null },
    { "index": 3, "header": "Reference Code", "sample": "REF-001",     "suggested": null },
    { "index": 4, "header": "Note",           "sample": "High-value",  "suggested": null }
  ],
  "row_count": 487
}
```

### Bước 2 — Dry-run (phát hiện trùng / DNC / lỗi)
```http
POST /api/telesales/campaigns/{id}/leads/dry-run
Content-Type: multipart/form-data

file=@call_list.csv
mapping={"phone":1,"full_name":0,"custom_fields":{"reference_code":3,"alt_phone":2,"note":4}}
```

**Định dạng `mapping`**: giá trị là **index cột 0-based** trong hàng header của CSV. `phone` là bắt buộc (số nguyên). Có thể map bất kỳ số cột phụ nào vào `custom_fields.*` — key trong đây PHẢI khớp field code đã đăng ký ở định nghĩa trường tuỳ chỉnh cho `entity=Lead`.

#### Request form fields (multipart)

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `file` | file | ✅ | File CSV/XLSX cần dry-run | max 10MB |
| `mapping` | string (JSON) | ✅ | Mapping cột → field hệ thống | Object JSON `{phone, full_name?, email?, custom_fields?}` |

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `file_token` | string | Token tạm thời định danh file đã upload — truyền lại ở bước commit | Dạng `telesales/imports/{campaign_id}/{uuid}.csv` |
| `summary` | object | Tổng kết kết quả validate | |
| `summary.total` | integer | Tổng dòng | |
| `summary.valid` | integer | Số dòng hợp lệ | |
| `summary.duplicate` | integer | Số dòng trùng (phone đã có trong chiến dịch) | |
| `summary.dnc` | integer | Số dòng phone đang ở DNC | |
| `summary.errors` | array | Danh sách lỗi format | |
| `sample_rows` | array | Tối đa 50 dòng mẫu kèm trạng thái phân loại | |
| `sample_rows[].row` | integer | Số dòng trong file (1-based) | |
| `sample_rows[].phone` | string | Số điện thoại | |
| `sample_rows[].full_name` | string | Họ tên (nếu có map) | |
| `sample_rows[].status` | string | Phân loại dòng | `valid` / `duplicate` / `dnc` / `error` |
| `sample_rows[].reason` | string | Lý do (chỉ có khi `status` không phải `valid`) | |

**Response 200**:
```json
{
  "file_token": "telesales/imports/36/abc123.csv",
  "summary": {
    "total": 487,
    "valid": 462,
    "duplicate": 18,
    "dnc": 7,
    "errors": []
  },
  "sample_rows": [
    { "row": 1, "phone": "0912345678", "full_name": "Nguyen Mai", "status": "valid" },
    { "row": 5, "phone": "0900000000", "full_name": "Le Linh",    "status": "dnc",
      "reason": "Phone on DNC since 2026-04-01" }
  ]
}
```

### Bước 3 — Commit (ghi vào DB)
```http
POST /api/telesales/campaigns/{id}/leads/import
Content-Type: multipart/form-data

file_token=telesales/imports/36/abc123.csv
mapping={...giống bước 2...}
```

#### Request form fields (multipart)

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `file_token` | string | ✅ | Token trả về từ bước dry-run | Token còn hiệu lực (TTL 24h) |
| `mapping` | string (JSON) | ✅ | Mapping cột → field — phải khớp dry-run | Cùng định dạng bước 2 |

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `campaign_id` | integer | ID chiến dịch | |
| `inserted` | integer | Số lead vừa insert | |
| `skipped_duplicate` | integer | Bỏ qua do trùng | |
| `skipped_dnc` | integer | Bỏ qua do thuộc DNC | |
| `skipped_invalid` | integer | Bỏ qua do format sai | |
| `took_ms` | integer | Thời gian xử lý (ms) | |

**Response 201**:
```json
{
  "data": {
    "campaign_id": 36,
    "inserted": 462,
    "skipped_duplicate": 18,
    "skipped_dnc": 7,
    "skipped_invalid": 0,
    "took_ms": 1840
  }
}
```

### Khai báo custom field

Hệ thống lưu dữ liệu mở rộng của mỗi lead trong cột JSON trường tuỳ chỉnh của lead. Trước khi import, admin của khách hàng phải khai báo các key hợp lệ qua:

```http
GET    /api/custom-fields?entity=Lead
POST   /api/custom-fields
PATCH  /api/custom-fields/{id}
DELETE /api/custom-fields/{id}
```

Mỗi định nghĩa gồm `entity`, `code`, `type` (string / integer / decimal / date / datetime / boolean / enum), luật validate, thứ tự hiển thị và (tuỳ chọn) `is_encrypted=true` để bật pipeline mã hoá Layer 2. Thêm field mới **không cần** migrate schema.

## 4.2 Lead CRUD

| Endpoint | Mục đích |
|---|---|
| `GET    /api/telesales/campaigns/{id}/leads` | Danh sách lead (có phân trang + lọc: `?status=pending&assigned_agent_id=25`) |
| `GET    /api/telesales/leads/{id}` | Chi tiết (kèm JSON `custom_fields`) |
| `PATCH  /api/telesales/leads/{id}` | Cập nhật |
| `DELETE /api/telesales/leads/{id}` | Xoá |
| `PATCH  /api/telesales/leads/bulk` | Cập nhật hàng loạt |
| `DELETE /api/telesales/leads/bulk` | Xoá hàng loạt |
| `POST   /api/telesales/leads/bulk-dnc` | Đẩy hàng loạt vào DNC |

### `GET /api/telesales/campaigns/{id}/leads` — danh sách lead

```http
GET /api/telesales/campaigns/36/leads?page=1&per_page=50&status=pending&sort=priority_score&dir=desc
```

#### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `status` | string | optional | Lọc theo trạng thái lead | `pending` / `queued` / `contacted` / `converted` / `dnc` / `exhausted` |
| `assigned_agent_id` | integer | optional | Lọc theo agent đang được giao | User ID |
| `search` | string | optional | Tìm theo `phone` / `phone_normalized` / `full_name` / `email` (LIKE %keyword%) | |
| `sort` | string | optional | Cột sort | `priority_score` (default) / `imported_at` / `last_attempt_at` |
| `dir` | string | optional | Hướng sort | `asc` / `desc` (default `desc`) |
| `page` | integer | optional | Số trang | ≥ 1 (default 1) |
| `per_page` | integer | optional | Bản ghi mỗi trang | 1-200 (default 50) |

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID lead | |
| `campaign_id` | integer | ID chiến dịch | |
| `full_name` | string\|null | Họ tên lead | |
| `phone` | string | Số điện thoại (gốc — định dạng nhập vào) | |
| `status` | string | Trạng thái lead | `pending` / `queued` / `contacted` / `converted` / `dnc` / `exhausted` |
| `priority_score` | integer | Mức ưu tiên gọi — càng cao càng được xếp trước | 0-100 |
| `assigned_agent_id` | integer\|null | ID agent đang được giao (sticky) | |
| `attempts_count` | integer | Số lần đã thử quay số | |
| `next_attempt_at` | datetime\|null | Thời điểm dự kiến gọi lại (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "id": 78912,
      "campaign_id": 36,
      "full_name": "Nguyen Thi Mai",
      "phone": "0912345678",
      "status": "pending",
      "priority_score": 85,
      "assigned_agent_id": 25,
      "attempts_count": 0,
      "next_attempt_at": "2026-06-07T08:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 10, "per_page": 50, "total": 487 }
}
```

::: tip Tối ưu payload
Response của list **không kèm `custom_fields`** để giữ payload gọn (487 lead × 5–10 custom field rất lớn). Gọi `GET /api/telesales/leads/{id}` khi cần chi tiết đầy đủ.
:::

### `GET /api/telesales/leads/{id}` — chi tiết

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID lead | |
| `campaign_id` | integer | ID chiến dịch | |
| `full_name` | string\|null | Họ tên lead | |
| `phone` | string | Số điện thoại gốc | |
| `status` | string | Trạng thái lead | `pending` / `queued` / `contacted` / `converted` / `dnc` / `exhausted` |
| `priority_score` | integer | Mức ưu tiên | 0-100 |
| `next_attempt_at` | datetime\|null | Thời điểm dự kiến gọi lại | |
| `assigned_agent_id` | integer\|null | Agent sticky | |
| `attempts_count` | integer | Số lần đã thử | |
| `custom_fields` | object | Các field mở rộng — key khớp định nghĩa trường tuỳ chỉnh (entity `Lead`) | |
| `created_at` | datetime | Thời điểm tạo (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": {
    "id": 78912,
    "campaign_id": 36,
    "full_name": "Nguyen Thi Mai",
    "phone": "0912345678",
    "status": "pending",
    "priority_score": 85,
    "next_attempt_at": "2026-06-07T08:00:00Z",
    "assigned_agent_id": 25,
    "attempts_count": 0,
    "custom_fields": {
      "reference_code": "REF-2026-001",
      "alt_phone": "0988111222",
      "note": "Returning customer, prefers Vietnamese"
    },
    "created_at": "2026-06-06T06:30:00Z"
  }
}
```

Tập key bên trong `custom_fields` phụ thuộc vào định nghĩa trường tuỳ chỉnh của khách hàng cho entity `Lead`.

**Response 404**:
```json
{ "message": "Lead not found." }
```

### `PATCH /api/telesales/leads/{id}` — cập nhật một lead

#### Request body fields (mọi field optional — chỉ truyền field cần đổi)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `full_name` | string | Họ tên | max 150 ký tự |
| `email` | string | Email | Phải đúng định dạng email |
| `custom_fields` | object | Field mở rộng — key khớp định nghĩa trường tuỳ chỉnh | Object JSON |
| `priority_score` | integer | Mức ưu tiên | 0-100 |
| `next_attempt_at` | datetime | Thời điểm dự kiến gọi lại (ISO 8601 UTC) | |
| `consent_status` | string | Trạng thái đồng ý | `granted` / `withdrawn` / `unknown` |
| `consent_source` | string | Nguồn ghi nhận đồng ý | max 100 ký tự |

::: warning Field bị cấm
Các field sau **không** cập nhật qua endpoint này: `phone`, `campaign_id`, `status`, `assigned_agent_id` (dùng API re-assignment riêng).
:::

**Body**:
```json
{
  "full_name": "Nguyen Thi Mai Anh",
  "email": "mai.anh@example.com",
  "custom_fields": {
    "reference_code": "REF-2026-001-UPDATED",
    "note": "Customer requested callback Monday morning"
  },
  "priority_score": 92,
  "next_attempt_at": "2026-06-09T09:00:00Z",
  "consent_status": "granted",
  "consent_source": "phone_call_2026-06-08"
}
```

**Response 200**: trả về object lead đầy đủ (cùng shape với `GET /api/telesales/leads/{id}`).

**Response 422 — các trường hợp validate sai**:

```json
// priority_score nằm ngoài khoảng cho phép
{
  "message": "The given data was invalid.",
  "errors": { "priority_score": ["The priority score must be between 0 and 100."] }
}

// next_attempt_at sai định dạng
{
  "message": "The given data was invalid.",
  "errors": { "next_attempt_at": ["The next attempt at is not a valid date."] }
}

// custom_fields không phải array/object
{
  "message": "The given data was invalid.",
  "errors": { "custom_fields": ["The custom fields must be an array."] }
}

// consent_status không nằm trong enum cho phép
{
  "message": "The given data was invalid.",
  "errors": { "consent_status": ["The selected consent status is invalid."] }
}

// email sai định dạng
{
  "message": "The given data was invalid.",
  "errors": { "email": ["The email must be a valid email address."] }
}
```

### `DELETE /api/telesales/leads/{id}` — xoá một lead

**Response 204 No Content** (thành công).

**Response 404**: lead không tồn tại hoặc không thuộc tài khoản.

**Response 422 — lead đang có cuộc gọi active**:
```json
{
  "message": "Cannot delete a lead with an active call.",
  "errors": { "lead_id": ["Lead 78912 is currently on call UUID xxx — wait for it to end first."] }
}
```

::: tip Soft delete
Đây là soft delete — lead được set `deleted_at` nhưng lịch sử quay số vẫn giữ. Bulk delete cũng hoạt động cùng cách.
:::

### `PATCH /api/telesales/leads/bulk` — cập nhật hàng loạt

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `lead_ids` | integer[] | ✅ | Danh sách lead ID cần update | 1-1000 phần tử |
| `patch` | object | ✅ | Field cần cập nhật cho toàn bộ lead trong danh sách | Xem bảng `patch.*` |
| `patch.status` | string | optional | Trạng thái mới | `pending` / `queued` / `contacted` / `converted` / `dnc` / `exhausted` |
| `patch.assigned_agent_id` | integer\|null | optional | Sticky agent | User ID hoặc `null` để gỡ |
| `patch.priority_score` | integer | optional | Mức ưu tiên | 0-100 |
| `patch.next_attempt_at` | datetime | optional | Thời điểm gọi lại | ISO 8601 UTC |

**Body**:
```json
{
  "lead_ids": [78912, 78913, 78920, 78921],
  "patch": {
    "status": "queued",
    "assigned_agent_id": 25,
    "priority_score": 100
  }
}
```

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `success` | bool | Tổng quan thành công | `true` / `false` |
| `updated` | integer | Số lead update thực tế | |
| `skipped` | integer | Số lead bị bỏ qua (không thuộc tài khoản hoặc validate fail) | |

**Response 200**:
```json
{
  "success": true,
  "updated": 4,
  "skipped": 0
}
```

**Response 422 — `lead_ids` rỗng hoặc quá lớn**:
```json
{
  "message": "The given data was invalid.",
  "errors": { "lead_ids": ["The lead ids must have at least 1 item.", "The lead ids may not have more than 1000 items."] }
}
```

::: warning Giới hạn bulk
Tối đa **1000 lead_ids mỗi request**. Lead không thuộc tài khoản sẽ bị bỏ qua âm thầm (cộng vào `skipped`).
:::

### `DELETE /api/telesales/leads/bulk` — xoá hàng loạt

**Body**:
```json
{ "lead_ids": [78912, 78913, 78920] }
```

**Response 200**:
```json
{ "success": true, "deleted": 3 }
```

**Response 422**: validate giống `PATCH /api/telesales/leads/bulk`.

### `POST /api/telesales/leads/bulk-dnc` — đánh dấu DNC hàng loạt

Đưa nhiều lead vào DNC list trong một request.

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `lead_ids` | integer[] | ✅ | Danh sách lead ID cần đẩy vào DNC | 1-1000 phần tử |
| `reason` | string | ✅ | Lý do đưa vào DNC — bắt buộc cho audit trail | max 500 ký tự |

**Body**:
```json
{
  "lead_ids": [78912, 78913],
  "reason": "Customer requested opt-out"
}
```

#### Response body fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `success` | bool | Tổng quan thành công | `true` / `false` |
| `added_to_dnc` | integer | Số phone vừa thêm vào DNC | |
| `skipped_already_dnc` | integer | Số phone đã ở DNC từ trước | |
| `audit_trail_id` | string | ID bản ghi audit (nhật ký audit DNC) | Dạng `audit_dnc_*` |

**Response 200**:
```json
{
  "success": true,
  "added_to_dnc": 2,
  "skipped_already_dnc": 0,
  "audit_trail_id": "audit_dnc_abc123"
}
```

Sau khi mark DNC:
- Số điện thoại của lead được insert vào danh sách DNC (`source: 'customer_request'`).
- Lead `status` chuyển sang `dnc`.
- Mọi callback đang chờ của lead bị huỷ.
- Một bản ghi audit được tạo trong nhật ký audit DNC với `actor_id`, `lead_ids`, `reason`, `audit_trail_id`.

**Response 422 — thiếu `reason`**:
```json
{
  "message": "The given data was invalid.",
  "errors": { "reason": ["The reason field is required."] }
}
```


---

# Recording

<!-- source: https://docs.zorio.vn/api/telesales/recording.md -->

# Recording

Nhóm endpoint phát/tải ghi âm từng cuộc gọi, tạo job export hàng loạt (ZIP), điều khiển job và pause/resume ghi âm thời gian thực để tuân thủ PCI.

## Tạm dừng / tiếp tục ghi âm (PCI compliance)

```http
POST /api/telesales/calls/{uuid}/recording/pause
POST /api/telesales/calls/{uuid}/recording/resume
```

### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `uuid` | string | UUID cuộc gọi đang diễn ra |

### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `uuid` | string | UUID cuộc gọi | |
| `recording` | string | Trạng thái ghi âm sau khi gọi endpoint | `paused` / `recording` |

**Response 200**: `{ "data": { "uuid": "...", "recording": "paused" } }`

::: tip Use case
Agent có thể tạm dừng ghi âm khi khách hàng đang đọc thông tin nhạy cảm (số thẻ tín dụng, CVV, ...) để đảm bảo tuân thủ PCI-DSS, sau đó tiếp tục ghi khi đoạn nhạy cảm đã kết thúc.
:::

## Tổng quan endpoint

| Endpoint | Mục đích |
|---|---|
| `GET /api/telesales/recordings/{uuid}` | Stream audio để playback (trả `audio/wav`, hỗ trợ Range request) |
| `GET /api/telesales/recordings/{uuid}/download` | Tải file `.wav` kèm filename |
| `POST /api/telesales/recordings/export-bulk` | Tạo job export ZIP (async) |
| `GET /api/telesales/recordings/export-bulk/{jobId}` | Kiểm tra trạng thái job |
| `GET /api/telesales/recordings/export-bulk/{jobId}/download` | Tải ZIP khi job hoàn tất |
| `DELETE /api/telesales/recordings/export-bulk/{jobId}` | Huỷ job / dọn ZIP sớm |

## `GET /api/telesales/recordings/{uuid}` — stream

### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `uuid` | string | UUID cuộc gọi |

### Response headers

| Header | Mô tả | Giá trị |
|---|---|---|
| `Content-Type` | Loại MIME | `audio/wav` |
| `Accept-Ranges` | Hỗ trợ Range request | `bytes` |
| `Content-Length` | Kích thước file (byte) | |
| `Cache-Control` | Cache policy | `private, max-age=3600` |

**Response 200**:
- `Content-Type: audio/wav`
- `Accept-Ranges: bytes` (cho HTML5 audio scrubbing)
- `Content-Length: <bytes>`
- `Cache-Control: private, max-age=3600`

**Response 206 Partial Content** (HTTP Range request) — audio player dùng để scrub.

**Response 404** — không có ghi âm:
```json
{ "message": "Recording not found.", "error_code": "RECORDING_NOT_FOUND" }
```

**Response 410 Gone** — ghi âm đã hết hạn theo retention rule do admin cấu hình:
```json
{ "message": "Recording has exceeded the retention window.", "expired_at": "2026-03-01T00:00:00Z" }
```

## `GET /api/telesales/recordings/{uuid}/download`

### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `uuid` | string | UUID cuộc gọi |

### Response headers

| Header | Mô tả | Giá trị |
|---|---|---|
| `Content-Type` | Loại MIME | `audio/wav` |
| `Content-Disposition` | Filename gợi ý cho trình duyệt | `attachment; filename="call-{uuid}-{date}.wav"` |

**Response 200**:
- `Content-Type: audio/wav`
- `Content-Disposition: attachment; filename="call-093e1024-2026-06-06.wav"`

Lỗi 404/410 giống endpoint stream.

## `POST /api/telesales/recordings/export-bulk` — tạo job ZIP

### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `campaign_id` | integer | optional | Lọc theo chiến dịch | |
| `date_from` | datetime | ✅ | Mốc bắt đầu (ISO 8601 UTC) | |
| `date_to` | datetime | ✅ | Mốc kết thúc (ISO 8601 UTC) | Khoảng `date_from..date_to` ≤ 31 ngày |
| `agent_ids[]` | `array<integer>` | optional | Lọc theo agent | |
| `disposition_codes[]` | `array<string>` | optional | Chỉ export cuộc có disposition này | mã disposition của tài khoản |

**Body**:
```json
{
  "campaign_id": 36,
  "date_from": "2026-06-01T00:00:00Z",
  "date_to":   "2026-06-05T23:59:59Z",
  "agent_ids": [25, 26],
  "disposition_codes": ["SALE-OK", "CALLBACK_REQ"]
}
```

### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `job_id` | string | ID job export | `exp_<hex>` |
| `status` | string | Trạng thái khởi tạo | `queued` |
| `estimated_files` | integer | Ước tính số file ghi âm sẽ đóng gói | ≥ 1 |
| `estimated_size_mb` | integer | Ước tính dung lượng ZIP (MB) | ≥ 0 |
| `created_at` | datetime | Lúc tạo job (ISO 8601 UTC) | |
| `expires_at` | datetime | Lúc ZIP bị xoá tự động (default +30 ngày) | ISO 8601 UTC |

**Response 201**:
```json
{
  "data": {
    "job_id": "exp_abc123",
    "status": "queued",
    "estimated_files": 215,
    "estimated_size_mb": 480,
    "created_at": "2026-06-06T07:00:00Z",
    "expires_at": "2026-07-06T07:00:00Z"
  }
}
```

**Response 422 — các trường hợp validate sai**:
```json
// Khoảng thời gian vượt 31 ngày
{
  "message": "The given data was invalid.",
  "errors": { "date_to": ["The date_from..date_to range may not exceed 31 days."] }
}

// 0 file match filter → không tạo job
{
  "message": "No recordings match the filter.",
  "errors": { "filter": ["Estimated 0 files. Adjust date range or filters."] }
}
```

**Response 403** — caller không có quyền supervisor / admin:
```json
{ "message": "You are not allowed to bulk-export recordings. Supervisor or admin role is required." }
```

## `GET /api/telesales/recordings/export-bulk/{jobId}` — kiểm tra trạng thái

### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `jobId` | string | ID job trả về từ POST tạo job |

### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `job_id` | string | ID job export | |
| `status` | string | Trạng thái job | `queued` / `running` / `ready` / `failed` / `expired` / `cancelled` |
| `progress_pct` | integer | Phần trăm hoàn thành | 0-100 |
| `files` | integer | Số file đã đóng gói (chỉ khi `ready`) | ≥ 0 |
| `files_processed` | integer | Số file đã xử lý (chỉ khi `running`) | ≥ 0 |
| `size_mb` | integer | Dung lượng ZIP thực tế (MB) | |
| `download_url` | string | URL tải ZIP (khi `status=ready`) | |
| `created_at` | datetime | Lúc tạo job (ISO 8601 UTC) | |
| `completed_at` | datetime\|null | Lúc đóng gói xong | |
| `expires_at` | datetime | Lúc ZIP bị xoá tự động | |
| `error_code` | string | Mã lỗi khi `status=failed` | vd `STORAGE_ERROR` |
| `error_message` | string | Mô tả lỗi khi `status=failed` | |
| `failed_at` | datetime | Lúc job thất bại | |

**Response 200**:
```json
{
  "data": {
    "job_id":        "exp_abc123",
    "status":        "ready",
    "progress_pct":  100,
    "files":         215,
    "size_mb":       478,
    "download_url":  "/api/telesales/recordings/export-bulk/exp_abc123/download",
    "created_at":    "2026-06-06T07:00:00Z",
    "completed_at":  "2026-06-06T07:08:42Z",
    "expires_at":    "2026-07-06T07:00:00Z"
  }
}
```

Enum `status`: `queued` | `running` | `ready` | `failed` | `expired` | `cancelled`.

**Trạng thái `running`** trả thêm `progress_pct` (0..99) + `files_processed`.

**Trạng thái `failed`** trả thêm:
```json
{
  "data": {
    "job_id": "exp_abc123",
    "status": "failed",
    "error_code": "STORAGE_ERROR",
    "error_message": "Storage unavailable during ZIP packaging.",
    "failed_at": "2026-06-06T07:05:00Z"
  }
}
```

**Response 404** — job không tồn tại hoặc không thuộc tài khoản.

## `GET /api/telesales/recordings/export-bulk/{jobId}/download`

### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `jobId` | string | ID job (status phải = `ready`) |

### Response headers

| Header | Mô tả | Giá trị |
|---|---|---|
| `Content-Type` | Loại MIME | `application/zip` |
| `Content-Disposition` | Filename ZIP | `attachment; filename="recordings-{jobId}.zip"` |

**Response 200**:
- `Content-Type: application/zip`
- `Content-Disposition: attachment; filename="recordings-exp_abc123.zip"`

ZIP chứa các file `.wav` cùng một `manifest.csv` (call UUID, extension agent, tên agent, disposition code, start_time, duration, số điện thoại lead).

**Response 410 Gone** — ZIP đã hết hạn (30 ngày):
```json
{ "message": "Export ZIP has expired. Please create a new job." }
```

**Response 409 Conflict** — job chưa sẵn sàng:
```json
{ "message": "Job exp_abc123 is currently in state 'running' (38%). Wait until ready before downloading." }
```

## `DELETE /api/telesales/recordings/export-bulk/{jobId}` — huỷ / dọn

### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `jobId` | string | ID job cần huỷ hoặc dọn |

**Response 204 No Content** — `queued`/`running` → cancelled; `ready` → ZIP bị xoá sớm để giải phóng storage.


---

# Báo cáo (Reports)

<!-- source: https://docs.zorio.vn/api/telesales/reports.md -->

# Báo cáo (Reports)

Nhóm 9 báo cáo cho module Telesales: dashboard tổng quan, disposition breakdown, hiệu suất agent, funnel, sức khoẻ caller-ID, heatmap giờ × thứ, lead-source attribution, chuỗi thời gian và abandon rate. Tất cả đều hỗ trợ export CSV/Excel.

## Query params chung

Mọi endpoint chia sẻ bộ tham số sau (UTC ISO 8601):

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `campaign_id` | integer | optional | Lọc theo chiến dịch | |
| `date_from` | datetime | ✅ | Mốc bắt đầu (ISO 8601 UTC) | |
| `date_to` | datetime | ✅ | Mốc kết thúc (ISO 8601 UTC) | Khoảng `date_from..date_to` ≤ 90 ngày |
| `agent_ids[]` | `array<integer>` | optional | Mảng multi-select agent (`?agent_ids[]=25&agent_ids[]=26`) | |
| `team_id` | integer | optional | Lọc theo nhóm | |
| `timezone` | string | optional | Group theo ngày/giờ dùng timezone này | tên timezone TZDB (`UTC`, `Asia/Ho_Chi_Minh`, ...) — default `UTC` |
| `format` | string | optional | Định dạng response | `json` (default) / `csv` / `xlsx` (xem 9.2) |

**Lỗi 422 chung** — khoảng vượt 90 ngày:
```json
{
  "message": "The given data was invalid.",
  "errors": { "date_to": ["The date_from..date_to range may not exceed 90 days."] }
}
```

## Tổng quan 9 endpoint

| Endpoint | Nội dung |
|---|---|
| `GET /api/telesales/reports/dashboard` | KPI tổng quan: dials, answer rate, AHT, conversion |
| `GET /api/telesales/reports/disposition-breakdown` | Tỷ lệ phần trăm theo từng disposition code |
| `GET /api/telesales/reports/agent-performance` | KPI per-agent: calls, conversions, AHT, talk time |
| `GET /api/telesales/reports/funnel` | Funnel: Lead → Dialled → Connected → Talked > 30 s → Converted |
| `GET /api/telesales/reports/caller-id-health` | Sức khoẻ caller-ID rotation (ASR, short-call ratio, carrier) |
| `GET /api/telesales/reports/hour-dow-heatmap` | Matrix 24 giờ × 7 ngày (best calling windows) |
| `GET /api/telesales/reports/lead-source-attribution` | Conversion theo nguồn lead |
| `GET /api/telesales/reports/time-series` | Chuỗi thời gian theo `?group_by=day\|week\|hour` |
| `GET /api/telesales/reports/abandon-rate` | Abandon rate realtime (PDPL/TCPA gate) |

## 9.1 Response mẫu

### `GET /api/telesales/reports/dashboard?campaign_id=43&date_from=2026-06-01&date_to=2026-06-10`

#### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `total_dials` | integer | Tổng số lần quay số trong khoảng thời gian | ≥ 0 |
| `total_answers` | integer | Tổng số cuộc gọi được khách hàng bắt máy | ≥ 0 |
| `answer_rate_pct` | string | Chuỗi decimal (2 chữ số) — `total_answers / total_dials × 100` | "0.00"-"100.00" |
| `avg_talk_time_sec` | string | Thời gian đàm thoại trung bình (giây) | |
| `total_talk_time_sec` | string | Tổng thời gian đàm thoại (giây) | |
| `unique_agents` | integer | Số agent khác nhau đã quay số trong khoảng | ≥ 0 |
| `pdpl_blocked_count` | integer | Số cuộc gọi bị PDPL chặn (ngoài giờ cho phép) | ≥ 0 |

```json
{
  "data": {
    "total_dials":        487,
    "total_answers":      312,
    "answer_rate_pct":   "64.07",
    "avg_talk_time_sec": "184.5",
    "total_talk_time_sec": "57563",
    "unique_agents":       12,
    "pdpl_blocked_count":   5
  }
}
```

### `GET /api/telesales/reports/agent-performance?campaign_id=43&date_from=...&date_to=...`

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `agent_id` | integer | ID user agent | |
| `name` | string | Họ tên agent | |
| `username` | string | Tên đăng nhập | |
| `dials` | integer | Số cuộc đã quay trong khoảng | ≥ 0 |
| `answers` | integer | Số cuộc khách hàng bắt máy | ≥ 0 |
| `avg_aht_sec` | integer | AHT (Average Handle Time) — thời gian xử lý trung bình mỗi cuộc (giây) | ≥ 0 |
| `conversions` | integer | Số cuộc chốt thành công | ≥ 0 |
| `conv_rate` | number | `conversions / answers × 100` (float, KHÔNG phải string) | 0-100 |

```json
{
  "data": [
    {
      "agent_id":     3,
      "name":         "Nguyen Van A",
      "username":     "agent01",
      "dials":        152,
      "answers":       98,
      "avg_aht_sec":  191,
      "conversions":   28,
      "conv_rate":   18.42
    },
    {
      "agent_id":     4,
      "name":         "Tran Thi B",
      "username":     "agent02",
      "dials":        140,
      "answers":       86,
      "avg_aht_sec":  176,
      "conversions":   22,
      "conv_rate":   15.71
    }
  ]
}
```

### `GET /api/telesales/reports/funnel?campaign_id=43&date_from=...&date_to=...`

Trả về mảng phẳng (không phải object lồng `{stages, conversion_overall_pct}`).

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `stage` | string | Tên bước trong funnel | `Total leads` / `Dialed` / `Connected` / `Talked > 30s` / `Disposed` / `Converted` |
| `count` | integer | Số lead/cuộc gọi ở bước này | ≥ 0 |

```json
{
  "data": [
    { "stage": "Total leads",  "count":  487 },
    { "stage": "Dialed",       "count":  312 },
    { "stage": "Connected",    "count":  248 },
    { "stage": "Talked > 30s", "count":  198 },
    { "stage": "Disposed",     "count":  290 },
    { "stage": "Converted",    "count":   78 }
  ]
}
```

**Có 6 stage** — gồm cả `Disposed`. Client tự tính `conversion_overall_pct = Converted / Total_leads × 100` từ stage đầu và cuối.

### `GET /api/telesales/reports/disposition-breakdown?campaign_id=43&date_from=...&date_to=...`

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `code` | string | Mã disposition | |
| `label` | string | Nhãn hiển thị | |
| `category` | string | Nhóm kết quả | `contact` / `no_contact` / `callback` / `remove` |
| `color` | string | Mã màu UI badge | `#RRGGBB` |
| `count` | integer | Số cuộc gọi có disposition này | ≥ 0 |
| `pct` | string | Chuỗi decimal 2 chữ số — phần trăm trên tổng cuộc gọi | "0.00"-"100.00" |

```json
{
  "data": [
    {
      "code":     "no_answer",
      "label":    "No Answer",
      "category": "no_contact",
      "color":    "#6B7280",
      "count":     95,
      "pct":      "30.45"
    },
    {
      "code":     "sale",
      "label":    "Sale Success",
      "category": "contact",
      "color":    "#10B981",
      "count":     78,
      "pct":      "25.00"
    }
  ]
}
```

Mỗi item kèm `category` + `color` (UI dùng render badge). `pct` là chuỗi decimal. Không có wrapper `meta: {total_calls}` — client tự tính `total = sum(count)`.

### `GET /api/telesales/reports/caller-id-health?date_from=...&date_to=...`

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `cid` | string | Số caller-ID | |
| `display_name` | string\|null | Tên nội bộ | |
| `carrier` | string | Nhà mạng | `viettel` / `mobifone` / `vinaphone` / `vietnamobile` / `landline` / `other` |
| `cli_type` | string | Loại số | `mobile` / `fixed_02x` / `hotline_1900` / `hotline_1800` / `brandname` |
| `pool_status` | string | Trạng thái trong rotation pool | `active` / `cooldown` / `paused` / `disabled` |
| `cooldown_until` | datetime\|null | Lúc hết cooldown | ISO 8601 UTC |
| `daily_cap` | integer | Giới hạn cuộc/ngày | ≥ 1 |
| `total_calls` | integer | Tổng số cuộc đã gọi trong khoảng | ≥ 0 |
| `answered_calls` | integer | Số cuộc khách hàng bắt máy | ≥ 0 |
| `asr_pct` | number | Answer-Seizure Ratio (%) — `answered/total × 100` | 0-100 |
| `acd_sec` | integer | Average Call Duration — thời lượng đàm thoại trung bình (giây) | ≥ 0 |
| `short_calls` | integer | Số cuộc dưới ngưỡng "đàm thoại có ý nghĩa" | ≥ 0 |
| `short_call_ratio_pct` | number | Tỷ lệ cuộc ngắn / tổng | 0-100 |
| `rejected_calls` | integer | Số cuộc bị từ chối | ≥ 0 |
| `health_status` | string | Phân loại sức khoẻ | `healthy` / `warning` / `suspected_block` / `no_data` |
| `health_calls_today` | integer | Số cuộc gọi hôm nay (dùng đánh giá cooldown) | ≥ 0 |

```json
{
  "data": [
    {
      "cid":                  "0900000012",
      "display_name":         "Sales Line 1",
      "carrier":              "viettel",
      "cli_type":             "fixed_02x",
      "pool_status":          "active",
      "cooldown_until":        null,
      "daily_cap":             200,
      "total_calls":           152,
      "answered_calls":         98,
      "asr_pct":                64.5,
      "acd_sec":                121,
      "short_calls":             28,
      "short_call_ratio_pct":   18.4,
      "rejected_calls":           2,
      "health_status":         "healthy",
      "health_calls_today":      87
    }
  ]
}
```

### `GET /api/telesales/reports/hour-dow-heatmap?campaign_id=43&date_from=...&date_to=...`

Trả về **mảng phẳng 168 phần tử** (7 ngày × 24 giờ), không lồng theo day-of-week.

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `day_of_week` | integer | Thứ trong tuần | 0 = CN, 1 = T2, ..., 6 = T7 |
| `hour` | integer | Giờ trong ngày (theo `timezone` query param) | 0-23 |
| `dials` | integer | Số cuộc đã quay trong slot | ≥ 0 |
| `answered` | integer | Số cuộc khách bắt máy | ≥ 0 |
| `answer_rate_pct` | number | Tỷ lệ bắt máy `answered/dials × 100` | 0-100 |

```json
{
  "data": [
    { "day_of_week": 1, "hour": 0, "dials": 0,  "answered": 0,  "answer_rate_pct":  0 },
    { "day_of_week": 1, "hour": 1, "dials": 0,  "answered": 0,  "answer_rate_pct":  0 },
    { "day_of_week": 1, "hour": 9, "dials": 87, "answered": 56, "answer_rate_pct": 64.4 }
  ]
}
```

Client pivot thành matrix 7 × 24 để render heatmap.

### `GET /api/telesales/reports/lead-source-attribution?date_from=...&date_to=...`

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `source` | string | Nguồn lead — lead không có nguồn gom dưới `"(unknown)"` | |
| `total_leads` | integer | Tổng số lead từ nguồn này trong khoảng | ≥ 0 |
| `dialed_count` | integer | Số lead đã được quay số | ≥ 0 |
| `contacted_count` | integer | Số lead khách hàng bắt máy | ≥ 0 |
| `conv_count` | integer | Số lead chốt thành công | ≥ 0 |
| `conv_rate_pct` | string | Tỷ lệ chuyển đổi `conv_count/total_leads × 100` (decimal 2 chữ số) | "0.00"-"100.00" |

```json
{
  "data": [
    {
      "source":           "facebook_lead_ads",
      "total_leads":       240,
      "dialed_count":      230,
      "contacted_count":   152,
      "conv_count":         62,
      "conv_rate_pct":    "25.83"
    },
    {
      "source":           "(unknown)",
      "total_leads":         5,
      "dialed_count":        3,
      "contacted_count":     2,
      "conv_count":          0,
      "conv_rate_pct":     "0.00"
    }
  ]
}
```

### `GET /api/telesales/reports/time-series?campaign_id=43&group_by=day&date_from=...&date_to=...`

Trả về **mảng phẳng** — không có wrapper `{group_by, metrics, series}`.

#### Query parameter bổ sung

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `group_by` | string | optional | Bước nhóm thời gian | `day` (default) / `week` / `hour` |

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `bucket` | string | Mốc thời gian — format theo `group_by` | `day` → `YYYY-MM-DD`; `week` → `YYYY-Www` (ISO 8601); `hour` → `YYYY-MM-DD HH:00:00` |
| `dials` | integer | Số cuộc đã quay trong bucket | ≥ 0 |
| `answers` | integer | Số cuộc khách bắt máy | ≥ 0 |
| `talk_sec` | integer | Tổng thời gian đàm thoại (giây) | ≥ 0 |
| `conversions` | integer | Số cuộc chốt thành công | ≥ 0 |

```json
{
  "data": [
    { "bucket": "2026-06-01", "dials": 110, "answers": 68, "talk_sec":  9180, "conversions": 18 },
    { "bucket": "2026-06-02", "dials": 105, "answers": 71, "talk_sec": 10260, "conversions": 16 },
    { "bucket": "2026-06-05", "dials":  82, "answers": 55, "talk_sec":  6720, "conversions": 15 }
  ]
}
```

### `GET /api/telesales/reports/abandon-rate?campaign_id=43` (realtime)

Response của endpoint này phong phú hơn các báo cáo khác — chứa `current` (snapshot live) + `breaches` (lịch sử lần vượt ngưỡng gần đây).

#### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `current.campaign_id` | integer | ID chiến dịch | |
| `current.attempts_total` | integer | Tổng số attempt trong cửa sổ đo | ≥ 0 |
| `current.attempts_abandoned` | integer | Số attempt bị abandon trước khi agent kịp nói | ≥ 0 |
| `current.abandon_rate_pct` | number | Tỷ lệ abandon (%) | 0-100 |
| `current.window_minutes` | integer | Độ dài cửa sổ đo (phút, default 30 ngày = 43.200) | ≥ 1 |
| `current.window_from` | datetime | Mốc bắt đầu cửa sổ | ISO 8601 |
| `current.window_to` | datetime | Mốc kết thúc cửa sổ | ISO 8601 |
| `current.campaign_name` | string | Tên chiến dịch | |
| `current.campaign_status` | string | Trạng thái chiến dịch | `draft` / `active` / `paused` / `completed` |
| `current.limit_pct` | number | Ngưỡng PDPL/TCPA cho phép | default 3 |
| `current.breached` | bool | Đang vượt ngưỡng hay không | |
| `breaches[]` | array | Lịch sử các snapshot đã vượt ngưỡng (rỗng nếu chưa từng vượt) | |

```json
{
  "data": {
    "current": {
      "campaign_id":           43,
      "attempts_total":         1,
      "attempts_abandoned":     0,
      "abandon_rate_pct":       0,
      "window_minutes":     43200,
      "window_from":      "2026-05-10 02:31:14",
      "window_to":        "2026-06-09 02:31:14",
      "tenant_id":              1,
      "campaign_name":     "Outbound Sales Q3-2026 03",
      "campaign_status":   "active",
      "limit_pct":              3,
      "breached":           false
    },
    "breaches": []
  }
}
```

Khi `breached=true`, mảng `breaches` chứa lịch sử snapshot (các cửa sổ thời gian đã vượt giới hạn). Client dùng để render banner cảnh báo và vẽ trend.

## 9.2 Export CSV / Excel

```http
GET /api/telesales/reports/{report}/export?format=csv|xlsx
```

`{report}` ∈ {dashboard, disposition-breakdown, agent-performance, funnel, caller-id-health, hour-dow-heatmap, lead-source-attribution, time-series}.

Response: file stream (`Content-Type: text/csv` hoặc `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`).

Layout export mặc định là chuẩn chung. Template Excel theo từng khách hàng (thứ tự cột, label header, conditional formatting riêng) được cấu hình trong gói cấu hình riêng.


---

# Script + Outcome

<!-- source: https://docs.zorio.vn/api/telesales/scripts.md -->

# Script + Outcome

Nhóm endpoint cấu hình kịch bản hội thoại (Call Scripts) và bộ mã kết quả cuộc gọi (Disposition Codes). Đây là 2 thành phần cốt lõi mà agent dùng trong mỗi cuộc gọi: script hướng dẫn cách nói, disposition phân loại kết quả khi kết thúc.

## 5. Call Scripts

| Endpoint | Mục đích |
|---|---|
| `GET    /api/telesales/scripts` | Danh sách script của khách hàng |
| `GET    /api/telesales/scripts/{id}` | Chi tiết script kèm các placeholder được phát hiện |
| `POST   /api/telesales/scripts` | Tạo script mới |
| `PUT    /api/telesales/scripts/{id}` | Cập nhật script |
| `DELETE /api/telesales/scripts/{id}` | Xoá script |
| `POST   /api/telesales/scripts/{id}/preview` | Preview nội dung với lead + agent thật |

Script dùng cú pháp Markdown. Biến `{{placeholder}}` được **tự động phát hiện** từ nội dung — không cần khai báo riêng. Tại thời điểm agent mở lead, biến được thay thế bằng giá trị thực từ `custom_fields` của lead + profile của agent. Các placeholder chuyên ngành (số hợp đồng, account ID, mã đơn hàng, ...) được khai báo qua `custom_fields` của từng khách hàng.

### `GET /api/telesales/scripts` — danh sách

#### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `q` | string | optional | Tìm theo `name` (LIKE %keyword%) | |
| `campaign_id` | integer | optional | Lọc các script đang được chiến dịch này dùng | |
| `page` | integer | optional | Số trang | ≥ 1 (default 1) |
| `per_page` | integer | optional | Bản ghi mỗi trang | 1-200 (default 50) |

#### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID script | |
| `name` | string | Tên script (unique trong tài khoản) | max 150 ký tự |
| `content_preview` | string | Nội dung Markdown — cắt còn 200 ký tự đầu | |
| `placeholders_detected[]` | `array<string>` | Danh sách biến `{{ten_bien}}` phát hiện trong nội dung | |
| `used_by_campaigns[]` | `array<integer>` | Mảng ID chiến dịch đang gắn script này | |
| `created_at` | datetime | Thời điểm tạo (ISO 8601 UTC) | |
| `updated_at` | datetime | Lần cập nhật cuối (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "id": 12,
      "name": "Default Outbound Script",
      "content_preview": "## Opening\nHello {{customer_name}}...",
      "placeholders_detected": ["customer_name", "agent_name", "brand_name"],
      "used_by_campaigns": [36, 42],
      "created_at": "2026-06-06T06:00:00Z",
      "updated_at": "2026-06-06T06:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 3 }
}
```

`content_preview` được cắt còn 200 ký tự đầu. Dùng `GET /api/telesales/scripts/{id}` để lấy nội dung đầy đủ.

### `GET /api/telesales/scripts/{id}` — chi tiết

#### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `id` | integer | ID script |

#### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID script | |
| `name` | string | Tên script | max 150 ký tự |
| `content` | string | Toàn bộ nội dung Markdown | max 32 KB |
| `placeholders_detected[]` | `array<string>` | Biến `{{ten_bien}}` được parse từ `content` | |
| `used_by_campaigns[]` | `array<object>` | Mảng object `{id, name}` của chiến dịch đang gắn script | |
| `created_at` | datetime | Thời điểm tạo (ISO 8601 UTC) | |
| `updated_at` | datetime | Lần cập nhật cuối (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": {
    "id": 12,
    "name": "Default Outbound Script",
    "content": "## Opening\nHello {{customer_name}}, this is {{agent_name}} from {{brand_name}}...\n\n## Body\n... talk track ...\n\n## Closing\nThank you.",
    "placeholders_detected": ["customer_name", "agent_name", "brand_name"],
    "used_by_campaigns": [
      { "id": 36, "name": "Summer Promo" },
      { "id": 42, "name": "Retention Q3" }
    ],
    "created_at": "2026-06-06T06:00:00Z",
    "updated_at": "2026-06-06T06:00:00Z"
  }
}
```

**Response 404**: `{ "message": "Script not found." }`

### `POST /api/telesales/scripts` — tạo

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `name` | string | ✅ | Tên script — unique trong tài khoản | max 150 ký tự |
| `content` | string | ✅ | Nội dung Markdown, biến `{{placeholder}}` tự phát hiện | max 32 KB |

**Body**:
```json
{
  "name": "Default Outbound Script",
  "content": "## Opening\nHello {{customer_name}}, this is {{agent_name}} from {{brand_name}}...\n\n## Body\n... talk track for the campaign ...\n\n## Closing\nThank you for your time."
}
```

#### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID script vừa tạo | |
| `name` | string | Tên script | |
| `content` | string | Nội dung Markdown | |
| `placeholders_detected[]` | `array<string>` | Biến `{{ten_bien}}` parse được từ `content` | |
| `created_at` | datetime | Thời điểm tạo (ISO 8601 UTC) | |

**Response 201**:
```json
{
  "data": {
    "id": 12,
    "name": "Default Outbound Script",
    "content": "## Opening\nHello {{customer_name}}...",
    "placeholders_detected": ["customer_name", "agent_name", "brand_name"],
    "created_at": "2026-06-06T06:00:00Z"
  }
}
```

**Response 422 — các trường hợp validate sai**:
```json
// Trùng tên script
{
  "message": "The given data was invalid.",
  "errors": { "name": ["The name has already been taken."] }
}

// Nội dung quá dài
{
  "message": "The given data was invalid.",
  "errors": { "content": ["The content may not be greater than 32768 characters."] }
}
```

### `PUT /api/telesales/scripts/{id}` — cập nhật

**Body**: giống POST.

**Response 200**: object script đã cập nhật, kèm `placeholders_detected` được tính lại từ nội dung mới.

**Response 422 — xung đột**:
```json
// Script đang được chiến dịch active dùng — vẫn cho cập nhật nhưng kèm cảnh báo
{
  "data": { "id": 12, ... },
  "warnings": ["Script is currently used by 2 active campaigns. Agents will see new content on next call."]
}
```

### `DELETE /api/telesales/scripts/{id}`

**Response 204 No Content** (thành công).

**Response 422** — script đang được chiến dịch active dùng:
```json
{
  "message": "Cannot delete a script that is in use by a campaign.",
  "errors": { "id": ["Script 12 is bound to campaign(s): 36, 42. Detach from campaign first."] }
}
```

### `POST /api/telesales/scripts/{id}/preview` — render preview

#### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `id` | integer | ID script cần render preview |

#### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `lead_id` | integer | ✅ | ID lead — lấy giá trị cho `{{customer_name}}` từ `custom_fields` | Phải tồn tại |
| `agent_id` | integer | ✅ | ID user agent — lấy giá trị cho `{{agent_name}}` từ profile | Phải tồn tại |

**Body**:
```json
{
  "lead_id":   78912,
  "agent_id":  25
}
```

Render nội dung với từng `{{placeholder}}` được thay bằng giá trị thực từ `lead.custom_fields` + profile của agent + brand của khách hàng.

#### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID script | |
| `rendered_content` | string | Nội dung Markdown đã thay placeholder | |
| `missing_placeholders[]` | `array<string>` | Biến không resolve được từ `custom_fields` / profile — UI có thể cảnh báo agent | |

**Response 200**:
```json
{
  "data": {
    "id": 12,
    "rendered_content": "## Opening\nHello Anh Hung, this is Nguyen Van A from Zorio...\n\n## Body\n...",
    "missing_placeholders": ["policy_number"]
  }
}
```

---

## 6. Call Outcomes (Disposition Codes)

### 6.1 Quản lý catalog disposition

| Endpoint | Mục đích |
|---|---|
| `GET    /api/telesales/dispositions` | Danh sách disposition của khách hàng |
| `GET    /api/telesales/dispositions/{id}` | Chi tiết một disposition |
| `POST   /api/telesales/dispositions` | Tạo disposition (admin) |
| `PUT    /api/telesales/dispositions/{id}` | Cập nhật disposition (admin) |
| `DELETE /api/telesales/dispositions/{id}` | Xoá disposition (admin) |

#### `GET /api/telesales/dispositions` — danh sách

##### Query parameters

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `category` | string | optional | Lọc theo nhóm kết quả | `contact` / `no_contact` / `callback` / `remove` |
| `is_active` | bool | optional | Có bao gồm cả disposition đã ẩn không | `true` (default) / `false` |

##### Response fields (mỗi item trong `data[]`)

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID disposition | |
| `code` | string | Mã immutable — agent / API dùng để gắn cuộc gọi | `[A-Za-z0-9_-]`, max 32 ký tự |
| `label` | string | Nhãn hiển thị | max 100 ký tự |
| `description` | string\|null | Mô tả chi tiết | max 500 ký tự |
| `category` | string | Nhóm kết quả | `contact` / `no_contact` / `callback` / `remove` |
| `is_final` | bool | Là kết quả cuối hay còn thử lại | `true` / `false` |
| `trigger_callback` | bool | Tự tạo callback khi agent chọn mã này | `true` / `false` (chỉ true khi `category=callback`) |
| `trigger_dnc` | bool | Tự thêm số vào DNC khi agent chọn mã này | `true` / `false` |
| `default_retry_delay_minutes` | integer\|null | Thời gian chờ trước khi quay lại lead nếu không phải kết quả final | 1-43200 (phút) |
| `color` | string | Mã màu hex cho UI badge | `#RRGGBB` |
| `is_active` | bool | Còn hiển thị trong dropdown của agent hay không | `true` / `false` |
| `usage_count_30d` | integer | Số cuộc gọi đã dùng mã này trong 30 ngày gần nhất | ≥ 0 |
| `created_at` | datetime | Thời điểm tạo (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "id": 5,
      "code": "SALE-OK",
      "label": "Sale Success",
      "description": "Customer agreed and committed",
      "category": "contact",
      "is_final": true,
      "trigger_callback": false,
      "trigger_dnc": false,
      "default_retry_delay_minutes": null,
      "color": "#10b981",
      "is_active": true,
      "usage_count_30d": 78,
      "created_at": "2026-06-01T06:00:00Z"
    }
  ]
}
```

#### `GET /api/telesales/dispositions/{id}` — chi tiết

##### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `id` | integer | ID disposition |

**Response 200**: object disposition (shape giống một phần tử trong mảng list).

**Response 404**: `{ "message": "Disposition not found." }`

#### `POST /api/telesales/dispositions` — tạo (admin)

##### Request body fields

| Field | Type | Required | Mô tả | Giá trị hợp lệ |
|---|---|---|---|---|
| `code` | string | ✅ | Mã immutable — unique trong tài khoản | `[A-Za-z0-9_-]`, max 32 ký tự |
| `label` | string | ✅ | Nhãn hiển thị | max 100 ký tự |
| `description` | string | optional | Mô tả chi tiết | max 500 ký tự |
| `category` | string | ✅ | Nhóm kết quả | `contact` / `no_contact` / `callback` / `remove` |
| `is_final` | bool | optional | Là kết quả cuối (không thử lại) | `true` / `false` (default `false`) |
| `trigger_callback` | bool | optional | Tự tạo callback — yêu cầu `category=callback` | `true` / `false` (default `false`) |
| `trigger_dnc` | bool | optional | Tự thêm số vào DNC | `true` / `false` (default `false`) |
| `default_retry_delay_minutes` | integer | optional | Phút chờ trước khi quay lại lead | 1-43200 |
| `color` | string | optional | Mã màu UI | `#RRGGBB` |

**Body**:
```json
{
  "code": "SALE-OK",
  "label": "Sale Success",
  "description": "Customer agreed and committed",
  "category": "contact",
  "is_final": true,
  "trigger_callback": false,
  "trigger_dnc": false,
  "default_retry_delay_minutes": null,
  "color": "#10b981"
}
```

##### Response fields

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `id` | integer | ID disposition vừa tạo | |
| `code` | string | Mã immutable | |
| `label` | string | Nhãn hiển thị | |
| `category` | string | Nhóm kết quả | `contact` / `no_contact` / `callback` / `remove` |
| `is_final` | bool | Là kết quả cuối | |
| `trigger_callback` | bool | Tự tạo callback | |
| `trigger_dnc` | bool | Tự thêm DNC | |
| `color` | string | Mã màu | `#RRGGBB` |
| `is_active` | bool | Hiển thị trong dropdown agent (default `true`) | |
| `created_at` | datetime | Thời điểm tạo (ISO 8601 UTC) | |

**Response 201**:
```json
{
  "data": {
    "id": 5,
    "code": "SALE-OK",
    "label": "Sale Success",
    "category": "contact",
    "is_final": true,
    "trigger_callback": false,
    "trigger_dnc": false,
    "color": "#10b981",
    "is_active": true,
    "created_at": "2026-06-06T06:00:00Z"
  }
}
```

**Response 422 — các trường hợp validate sai**:
```json
// Trùng code
{
  "message": "The given data was invalid.",
  "errors": { "code": ["The code has already been taken."] }
}

// Category không hợp lệ
{
  "message": "The given data was invalid.",
  "errors": { "category": ["The selected category is invalid."] }
}

// trigger_callback=true nhưng category không phải 'callback'
{
  "message": "The given data was invalid.",
  "errors": { "trigger_callback": ["trigger_callback only applies when category='callback'."] }
}
```

**Response 403** — caller không phải admin:
```json
{ "message": "You are not allowed to create dispositions. The admin role is required." }
```

#### `PUT /api/telesales/dispositions/{id}` — cập nhật (admin)

##### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `id` | integer | ID disposition |

##### Request body fields

Giống POST nhưng mọi field optional — chỉ truyền field cần đổi. `code` **không thể đổi** sau khi tạo (immutable identifier); truyền `code` mới sẽ trả 422.

| Field | Type | Mô tả | Giá trị hợp lệ |
|---|---|---|---|
| `label` | string | Nhãn hiển thị | max 100 ký tự |
| `description` | string\|null | Mô tả chi tiết | max 500 ký tự |
| `category` | string | Nhóm kết quả | `contact` / `no_contact` / `callback` / `remove` |
| `is_final` | bool | Là kết quả cuối | |
| `trigger_callback` | bool | Tự tạo callback (chỉ true khi `category=callback`) | |
| `trigger_dnc` | bool | Tự thêm DNC | |
| `default_retry_delay_minutes` | integer\|null | Phút chờ retry | 1-43200 |
| `color` | string | Mã màu | `#RRGGBB` |
| `is_active` | bool | Bật/tắt hiển thị | `true` / `false` |

**Response 200**: object đã cập nhật.

**Response 422**:
```json
// Cố ý đổi code
{
  "message": "The given data was invalid.",
  "errors": { "code": ["Code is immutable. Create a new disposition if a different code is needed."] }
}
```

#### `DELETE /api/telesales/dispositions/{id}` — xoá (admin)

##### Path parameter

| Field | Type | Mô tả |
|---|---|---|
| `id` | integer | ID disposition cần xoá |

**Response 204 No Content** (thành công — soft delete; set `is_active=false`).

**Response 422** — disposition đang được dùng:
```json
{
  "message": "Cannot delete a disposition with associated call history.",
  "errors": { "id": ["Disposition 5 has 78 calls in last 30 days. Hide instead of deleting (set is_active=false)."] }
}
```

::: tip Ẩn vs Xoá
Để giữ lịch sử báo cáo, delete mặc định là soft delete (set `is_active=false`). Disposition cũ vẫn xuất hiện trong báo cáo nhưng bị ẩn khỏi dropdown của agent. Hard delete chỉ được phép khi `usage_count = 0`.
:::

### 6.2 Catalog khởi tạo gợi ý (8 mã chung)

Mỗi tài khoản mới sẽ được seed sẵn một bộ catalog tổng quát, không gắn với ngành cụ thể. Khách hàng có thể mở rộng hoặc thay thế qua API hoặc UI quản trị.

| Code | Label | Category | is_final | trigger_callback | trigger_dnc |
|---|---|---|---|---|---|
| `SUCCESS` | Successful Contact | contact | x | | |
| `CALLBACK_REQ` | Customer Asked for Callback | callback | | x | |
| `REFUSED` | Customer Refused | contact | x | | |
| `NO_ANSWER` | No Answer | no_contact | | | |
| `BUSY` | Busy | no_contact | | | |
| `VOICEMAIL` | Voicemail Left | no_contact | | | |
| `WRONG_NUMBER` | Wrong Number | remove | x | | |
| `DNC_REQUEST` | DNC Request | remove | x | | x |

Đối với **catalog chuyên ngành** (chăm sóc khách hàng, lịch hẹn dịch vụ, khảo sát, lịch hẹn y tế, ...), tham khảo **gói cấu hình riêng** riêng cho khách hàng — sẽ seed sẵn bộ code mở rộng phù hợp workflow nghiệp vụ.


---

# API Token (machine-to-machine)

<!-- source: https://docs.zorio.vn/auth/api-token.md -->

# API Token (machine-to-machine)

API Token cấp cho **hệ thống máy** (CRM backend, dialer engine, integration service) gọi API Zorio mà **không gắn với phiên user**. Phù hợp cho server-to-server traffic, cron job, microservice tích hợp.

## Khác biệt với Bearer (phiên user) (user session)

| Đặc điểm | Bearer (phiên user) (user) | API Token (machine) |
|---|---|---|
| Gắn với user nào | 1 user cụ thể | 1 ứng dụng / service |
| Khi user logout | Token mất hiệu lực | Vẫn sống |
| Khi user đổi mật khẩu | Còn sống | Còn sống |
| Audit log ghi nhận | Theo `user.username` | Theo tên ứng dụng |
| Phù hợp cho | App có người dùng (frontend, mobile) | Server-to-server / cron |

::: tip
Cả 2 dạng đều dùng header `Authorization: Bearer <token>` giống nhau — phân biệt qua **cách cấp** + **audit log**, không phải qua format token.
:::

## Tạo API Token

::: warning Chỉ admin được tạo
API Token chỉ admin của tài khoản tạo được — qua **Admin Console**. Không có endpoint API để tự tạo (tránh CRM tự nhân bản token).
:::

### Quy trình

1. Vào **Admin Console → Cài đặt → API Tokens**.
2. Chọn tab **Machine Tokens** (khác tab "User Tokens").
3. Bấm **Tạo Machine Token**:
   - **Tên** — vd "CRM Salesforce Production", "Dialer Engine v2".
   - **Permission scope** — chọn permissions cụ thể (vd `pbx_api_access`, `telesales_create_lead`).
   - **IP whitelist** (tùy chọn) — chỉ chấp nhận request từ các IP cụ thể.
   - **Expiration** (tùy chọn) — auto-expire sau N ngày.
4. Hệ thống sinh token → **copy ngay 1 lần**.

## Dùng API Token

Giống Bearer (phiên user) — chỉ thêm header `Authorization: Bearer <token>` vào mọi request.

```bash
curl -X POST 'https://app.zorio.vn/api/pbx/calls/click-to-call' \
  -H 'Authorization: Bearer <YOUR_MACHINE_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"from_extension":"1001","to_phone":"0987654321"}'
```

## Permission scope

API Token có **scope hẹp hơn user** — chỉ làm được thao tác trong danh sách permission đã chọn lúc tạo.

Ví dụ scope phổ biến:

| Scope | Cho phép |
|---|---|
| `pbx_api_access` | Mọi endpoint `/api/pbx/*` |
| `manage_caller_ids` | CRUD caller ID + groups |
| `telesales_api_access` | Đọc/ghi campaign + lead Telesales |
| `autocall_api_access` | Đọc/ghi campaign + lead AutoCall |
| `view_all_cdr` | Xem CDR toàn tài khoản |
| `view_team_cdr` | Chỉ xem CDR trong team |

Endpoint kiểm tra permission của token hiện tại:

```
GET /api/auth/me
Authorization: Bearer <token>
```

Response 200 trả về `permissions[]` array.

## IP whitelist

Khi tạo token với IP whitelist:

- Mọi request từ IP **không trong list** → HTTP 403 với body `{ "message": "Forbidden: IP not whitelisted." }`.
- IP `0.0.0.0/0` = chấp nhận mọi IP (mặc định).
- Hỗ trợ CIDR range (vd `203.0.113.0/24`).

::: tip Lưu ý load balancer
Nếu app deploy sau LB / nginx proxy — Zorio đọc IP từ header `X-Forwarded-For` (chuỗi `client, proxy1, proxy2`). LB cần cấu hình forward đúng client IP.
:::

## Audit log

Mỗi request với API Token được log với:

| Field | Mô tả |
|---|---|
| `token_name` | Tên token (vd "CRM Salesforce Production") |
| `ip` | IP gửi request |
| `endpoint` | Method + path |
| `status` | HTTP status response |
| `at` | Timestamp |

Truy cập tại **Admin Console → Audit Log → API Token Activity**.

## Rotate token

Vì lý do bảo mật, rotate token định kỳ (khuyến nghị **90 ngày 1 lần**):

1. Vào Admin Console → API Tokens → bấm **Rotate** bên cạnh token.
2. Hệ thống sinh token mới — copy.
3. **Update token mới vào ứng dụng** (deploy code mới với token mới).
4. Verify ứng dụng chạy OK với token mới.
5. **Revoke** token cũ sau khi confirm.

::: warning Không xoay 2 token cùng lúc
Nếu app dùng nhiều token (vd LB → N replicas), rotate từng cái một, không đồng loạt, để có rollback path khi gặp lỗi.
:::

## Revoke

Token bị compromise hoặc không còn dùng — **Admin Console → API Tokens → Revoke**. Mọi request với token sau khi revoke → HTTP 401.

::: danger Revoke ngay khi nghi ngờ lộ
- Code có token vô tình commit lên git public.
- Server có token bị hack.
- Nhân viên có quyền tạo token rời công ty.

Revoke ngay, không chờ điều tra. Tạo token mới + deploy.
:::

## Bổ sung token vào CI/CD

| Tool | Cách lưu token |
|---|---|
| GitHub Actions | Repository secrets → `ZORIO_API_TOKEN` |
| GitLab CI | CI/CD Variables (Masked + Protected) |
| Jenkins | Credentials → Secret Text |
| Vault | Path `secret/zorio/api-token` → fetch lúc deploy |
| K8s | Secret → mount vào env var pod |

KHÔNG echo token ra log build. Tool CI thường có "masked output" — bật flag này.

## Sample server-to-server (cron import lead)

```js
// cron-job.js — chạy mỗi 5 phút
const axios = require('axios');

const api = axios.create({
  baseURL: 'https://app.zorio.vn/api',
  headers: {
    Authorization: 'Bearer ' + process.env.ZORIO_TOKEN,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  timeout: 30_000,
});

async function syncLeads() {
  const crmLeads = await fetchFromCRM();
  for (const lead of crmLeads) {
    try {
      await api.post(`/telesales/campaigns/${lead.campaign_id}/leads`, {
        phone: lead.phone,
        custom_fields: lead.fields,
      });
    } catch (err) {
      if (err.response?.status === 422) {
        console.error('Lead invalid:', lead, err.response.data.errors);
      } else {
        throw err;
      }
    }
  }
}

syncLeads().catch(console.error);
```

## Tài liệu liên quan

- [Lấy API Token](/bat-dau/xin-token)
- [Bearer (phiên user) (user session)](/auth/sanctum-bearer)
- [Rate limit + Idempotency](/auth/rate-limit)
- [Ký webhook HMAC-SHA256](/auth/webhook-hmac)


---

# Rate limit + Idempotency

<!-- source: https://docs.zorio.vn/auth/rate-limit.md -->

# Rate limit + Idempotency

Hai cơ chế Zorio dùng để bảo vệ API + giúp CRM xử lý retry an toàn.

## Rate limit

### Mục đích

- Bảo vệ hệ thống Zorio khỏi flood request (vô tình hoặc DDoS).
- Đảm bảo công bằng giữa các tài khoản — 1 tài khoản không thể chiếm hết tài nguyên.
- Khuyến khích CRM caching + batch xử lý thay vì spam endpoint.

### Mức giới hạn mặc định

Tính theo **token** (mỗi token riêng):

| Endpoint group | Limit | Window |
|---|---|---|
| `/api/pbx/calls/click-to-call` | **10 req/phút** | 60 giây trượt |
| `/api/pbx/*` (mọi endpoint khác) | **60 req/phút** | 60 giây trượt |
| `/api/telesales/*` | **120 req/phút** | 60 giây trượt |
| `/api/autocall/*` | **120 req/phút** | 60 giây trượt |
| `/api/auth/login` | **5 req/phút** | 60 giây trượt (chống brute-force) |
| `/api/auth/*` (các endpoint khác) | **30 req/phút** | 60 giây trượt |

::: tip Cần limit cao hơn?
Khách hàng enterprise có thể request limit cao hơn qua hợp đồng SLA. Liên hệ team Zorio.
:::

### Header trả về

Mọi response có header sau:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1782706011
```

| Header | Ý nghĩa |
|---|---|
| `X-RateLimit-Limit` | Tổng request cho phép trong window |
| `X-RateLimit-Remaining` | Còn lại bao nhiêu request trong window |
| `X-RateLimit-Reset` | Epoch giây UTC khi quota reset về `Limit` |

### Khi vượt giới hạn

HTTP 429 với body:

```json
{ "message": "Too many requests. Retry after 25 seconds." }
```

Header:

```
Retry-After: 25
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782706036
```

### Best practice CRM

#### 1. Tôn trọng `Retry-After`

```js
const response = await fetch(url, options);
if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After'), 10) || 60;
  await sleep(retryAfter * 1000);
  return retry();
}
```

#### 2. Exponential backoff + jitter

Tránh thundering herd khi nhiều client cùng retry:

```js
async function callWithBackoff(fn, attempt = 0) {
  try {
    return await fn();
  } catch (err) {
    if (err.status !== 429 && err.status < 500) throw err;
    if (attempt >= 5) throw err;

    const baseDelay = Math.min(1000 * Math.pow(2, attempt), 30_000);
    const jitter = Math.random() * 1000;
    await sleep(baseDelay + jitter);
    return callWithBackoff(fn, attempt + 1);
  }
}
```

#### 3. Batch endpoint khi có

Nhiều endpoint hỗ trợ batch:

- `POST /api/telesales/campaigns/{id}/leads/bulk-import` — import N lead 1 lần
- `PATCH /api/telesales/leads/bulk` — update N lead 1 lần
- `DELETE /api/telesales/leads/bulk` — xoá N lead 1 lần

Dùng batch tiết kiệm rate limit + nhanh hơn so với loop call từng cái.

#### 4. Cache response

Resource ít đổi (vd `caller-ids`, `queues`, `users`) — cache 1-5 phút ở CRM. Không poll mỗi giây.

#### 5. Monitor `X-RateLimit-Remaining`

Khi `Remaining < 5` — slow down chủ động, đừng đợi đến 0 rồi retry.

## Idempotency

### Vấn đề

Khi client retry 1 POST/PATCH/DELETE do timeout, làm sao đảm bảo:

- Không **tạo trùng** resource (vd 2 lead cùng số).
- Không **double charge** (vd 2 cuộc gọi cho 1 click).
- Không **double action** (vd disposition 2 lần cho 1 cuộc gọi).

### Giải pháp Zorio: Idempotency-Key

Client gửi header `Idempotency-Key: <UUID v4>` với mỗi request retry-able.

```bash
curl -X POST 'https://app.zorio.vn/api/pbx/calls/click-to-call' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -d '{"from_extension":"1001","to_phone":"0987654321"}'
```

### Cách Zorio xử lý

1. **Lần đầu** thấy `Idempotency-Key` → xử lý request bình thường, lưu response vào cache với key này (TTL 24h).
2. **Lần sau** thấy `Idempotency-Key` đã thấy → trả ngay response cached, KHÔNG xử lý lại.

### Endpoint hỗ trợ Idempotency-Key

| Method + endpoint | Lý do cần |
|---|---|
| `POST /api/pbx/calls/click-to-call` | Tránh gọi 2 lần khi mạng glitch |
| `POST /api/telesales/campaigns` | Tránh tạo 2 campaign cùng tên |
| `POST /api/telesales/campaigns/{id}/leads` | Tránh tạo 2 lead trùng |
| `POST /api/autocall/campaigns` | Tránh tạo 2 campaign cùng tên |
| `POST /api/integrations/sms` | Tránh gửi SMS 2 lần (kép phí) |

### Yêu cầu với Idempotency-Key

- **Format**: UUID v4 (`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`).
- **Unique per request**: KHÔNG dùng lại key cho request khác — bạn sẽ nhận response cũ.
- **TTL 24 giờ**: sau 24h key tự expire, retry với cùng key có thể tạo resource mới.

### Sample tích hợp Node.js

```js
const { v4: uuidv4 } = require('uuid');

async function clickToCall(fromExt, toPhone) {
  const key = uuidv4();

  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      const res = await api.post('/pbx/calls/click-to-call', {
        from_extension: fromExt,
        to_phone: toPhone,
      }, {
        headers: { 'Idempotency-Key': key },
      });
      return res.data;
    } catch (err) {
      if (attempt === 2) throw err;
      await sleep(1000 * (attempt + 1));
    }
  }
}
```

→ Dù retry 3 lần, chỉ **1 cuộc gọi** được tạo.

### Lưu ý

- Body request phải **giống hệt** giữa các lần retry (cùng `Idempotency-Key`). Khác body → HTTP 422 với `"message": "Idempotency-Key đã dùng với body khác."`.
- Endpoint **không hỗ trợ** Idempotency-Key sẽ ignore header này — không gây lỗi.

## Concurrency control

### Optimistic locking với `If-Match`

Một số endpoint update hỗ trợ `If-Match` để chống race:

```
PUT /api/pbx/extensions/1001
If-Match: "etag-abc123"
```

Nếu resource đã đổi giữa lúc client GET → ETag mismatch → HTTP 412 `{ "message": "Resource đã thay đổi, vui lòng GET lại." }`. CRM cần re-fetch + re-apply changes.

### Connection limit

- Tối đa **20 connection đồng thời** per token.
- Vượt → HTTP 429 với body `{ "message": "Too many concurrent connections." }`.

## Tài liệu liên quan

- [Bearer (phiên user)](/auth/sanctum-bearer)
- [API Token](/auth/api-token)
- [HTTP status codes](/tham-chieu/http-codes) — chi tiết 429
- [Webhook retry policy](/webhooks/retry) — idempotency phía receiver


---

# Bearer (phiên user) (user session)

<!-- source: https://docs.zorio.vn/auth/sanctum-bearer.md -->

# Bearer (phiên user) (user session)

Bearer Token (phiên user) là cơ chế xác thực **gắn với phiên đăng nhập của user** trên trang Admin Console. Phù hợp cho các ứng dụng tích hợp **có người dùng cuối** (frontend, dashboard nội bộ, app mobile riêng).

## Khi nào dùng Bearer (phiên user)?

| Use case | Cơ chế phù hợp |
|---|---|
| Frontend Vue/React/Mobile gọi API thay user | **Bearer (phiên user)** ✅ |
| CRM thực hiện hành động under user context (vd "Sales A click-to-call") | **Bearer (phiên user)** ✅ |
| Server-to-server background job (không có user) | [API Token](/auth/api-token) |
| Webhook receiver verify Zorio đẩy event | [Ký HMAC-SHA256](/auth/webhook-hmac) |

## Lấy token

### Cách 1 — Đăng nhập qua API

**Endpoint**: `POST /api/auth/login`

#### Request body

| Field | Type | Required | Mô tả |
|---|---|---|---|
| `username` | string | ✅ | Tên đăng nhập của user |
| `password` | string | ✅ | Mật khẩu |
| `device_name` | string | optional | Tên thiết bị / app để phân biệt token (vd `CRM-Salesforce`, `iPhone-Sales-01`) |

```json
{
  "username": "sales01",
  "password": "...",
  "device_name": "CRM-Salesforce"
}
```

#### Response 200

```json
{
  "data": {
    "user": {
      "id": 7,
      "username": "sales01",
      "email": "sales01@example.com",
      "role": "agent",
      "team_id": 2
    }
  },
  "token": "12|abcdefghijklmnopqrstuvwxyz0123456789"
}
```

**Lưu token** ngay vào storage an toàn (httpOnly cookie hoặc Keychain mobile). Token là chuỗi `<id>|<random>`.

#### Response 401

```json
{ "message": "Sai tài khoản hoặc mật khẩu." }
```

#### Response 422

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "username": ["Trường username là bắt buộc."]
  }
}
```

### Cách 2 — Tạo token qua Admin Console

Vào **Cài đặt → API Tokens** → bấm **Tạo token mới** → đặt tên + chọn permission scope. Token chỉ hiển thị 1 lần — copy ngay.

## Dùng token trong request

Mọi request kèm 2 header:

```
Authorization: Bearer <token>
Accept: application/json
```

### Ví dụ cURL

```bash
curl -X GET 'https://app.zorio.vn/api/pbx/extensions' \
  -H 'Authorization: Bearer 12|abcdefghijklmnopqrstuvwxyz' \
  -H 'Accept: application/json'
```

### Ví dụ Node.js (axios)

```js
const axios = require('axios');

const api = axios.create({
  baseURL: 'https://app.zorio.vn/api',
  headers: {
    Authorization: 'Bearer ' + process.env.ZORIO_TOKEN,
    Accept: 'application/json',
  },
});

const res = await api.get('/pbx/extensions');
console.log(res.data);
```

### Ví dụ PHP (Guzzle)

```php
$client = new GuzzleHttp\Client([
    'base_uri' => 'https://app.zorio.vn/api/',
    'headers'  => [
        'Authorization' => 'Bearer ' . getenv('ZORIO_TOKEN'),
        'Accept'        => 'application/json',
    ],
]);
$res = $client->get('pbx/extensions');
```

## Logout / Revoke

### Logout phiên hiện tại

```
POST /api/auth/logout
Authorization: Bearer <token>
```

Trả 200 `{ "data": { "logged_out": true } }`. Token bị invalidate ngay — request sau dùng token này → 401.

### Revoke 1 token cụ thể (admin)

Vào **Admin Console → API Tokens** → bấm **Revoke** bên cạnh token cần xoá.

### Revoke tất cả token của user (logout-all)

```
POST /api/auth/logout-all
Authorization: Bearer <token>
```

Mọi token đang sống của user bị invalidate — dùng khi nghi ngờ tài khoản bị hack.

## Thời hạn token

- Mặc định **không tự expire** — chỉ revoke thủ công.
- Có thể cấu hình **expiration policy** ở Admin Console: 30/60/90/180 ngày.
- Khi token expired/revoked → API trả **HTTP 401** với body `{ "message": "Unauthenticated." }`.

## Whoami (kiểm tra token)

```
GET /api/auth/me
Authorization: Bearer <token>
```

Response 200:

```json
{
  "data": {
    "id": 7,
    "username": "sales01",
    "email": "sales01@example.com",
    "role": "agent",
    "team_id": 2,
    "permissions": ["pbx_api_access", "telesales_make_call", "view_my_cdr"]
  }
}
```

CRM có thể call endpoint này lúc khởi động để biết user hiện tại + check permission có sẵn.

## Đổi mật khẩu

```
POST /api/auth/change-password
Authorization: Bearer <token>

{
  "current_password": "...",
  "new_password": "...",
  "new_password_confirmation": "..."
}
```

Response 200 `{ "data": { "changed": true } }`. **Token hiện tại KHÔNG bị invalidate** — user vẫn duy trì phiên.

## Best practice

- KHÔNG hardcode token trong code frontend (bị lộ qua DevTools).
- KHÔNG commit token vào git.
- Token dài hạn → lưu ở vault (1Password, AWS Secrets Manager, Vault Hashicorp).
- Rotate token 90 ngày 1 lần.
- Mỗi app / thiết bị → tạo token riêng (`device_name`) để dễ revoke targeted.
- Catch 401 graceful → redirect user đến login page, không crash app.

## Tài liệu liên quan

- [Lấy API Token](/bat-dau/xin-token)
- [API Token (machine-to-machine)](/auth/api-token)
- [Rate limit + Idempotency](/auth/rate-limit)


---

# Ký webhook HMAC-SHA256

<!-- source: https://docs.zorio.vn/auth/webhook-hmac.md -->

# Ký webhook HMAC-SHA256

Webhook nội dung sâu hơn và sample code đầy đủ ở [Webhooks chung → Ký HMAC-SHA256](/webhooks/hmac). Trang này tóm tắt nhanh để CRM kỹ thuật onboarding mới hiểu cơ chế ký + verify.

## Vì sao cần ký HMAC

CRM nhận webhook từ Zorio gửi đến URL của bạn. Nếu KHÔNG ký:

- Kẻ tấn công có thể **giả Zorio** → gửi event giả tới URL của bạn → CRM xử lý nhầm.
- Payload có thể bị **sửa giữa đường** (man-in-the-middle).
- Kẻ tấn công **replay** lại event hợp lệ đã bắt được.

Ký HMAC-SHA256 giải quyết cả 3.

## Cơ chế

### Lúc tạo webhook

Khi đăng ký webhook qua Admin Console, hệ thống sinh **secret** 32 ký tự alphanumeric. Bạn:

1. Copy secret ngay (chỉ hiện 1 lần).
2. Lưu vào ENV của receiver (`ZORIO_WEBHOOK_SECRET`).
3. KHÔNG hardcode trong code, KHÔNG commit vào git.

### Mỗi event Zorio gửi

Zorio gửi POST request kèm headers:

```
X-Zorio-Event: pbx.call.hangup
X-Zorio-Timestamp: 1782706011
X-Zorio-Delivery: 7c9e6679-7425-40de-944b-e07fc1f90ae7
X-Zorio-Signature: sha256=ab9d7f4...
Content-Type: application/json; charset=utf-8
```

### Cách Zorio tính signature

```
signature = "sha256=" + lowercase(hex(HMAC-SHA256(secret, raw_body)))
```

- `secret`: secret bạn lưu lúc tạo webhook.
- `raw_body`: bytes nguyên văn của body request (KHÔNG parse JSON trước).

## Receiver verify như nào

### 4 bước

1. **Reject timestamp cũ** — nếu `X-Zorio-Timestamp` lệch quá **300 giây** với now → reject 400.
2. **Tính lại signature** với secret + raw body.
3. **So sánh constant-time** với `X-Zorio-Signature` — dùng API timing-safe của ngôn ngữ.
4. **Dedupe** theo `X-Zorio-Delivery` UUID — khoá phân tán NX với TTL 24h.

### Sample Node.js (tối giản)

```js
const crypto = require('crypto');

function verifyZorioWebhook(req, secret) {
  // 1. Timestamp window
  const ts = parseInt(req.headers['x-zorio-timestamp'], 10);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) {
    throw new Error('Stale timestamp');
  }

  // 2. Recompute
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(req.rawBody).digest('hex');

  // 3. Timing-safe compare
  const sig = req.headers['x-zorio-signature'] || '';
  if (sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    throw new Error('Invalid signature');
  }
}
```

### Sample PHP / Python / Go

Xem [Mẫu receiver đầy đủ 4 ngôn ngữ](/webhooks/receiver-mau).

## Pitfall thường gặp

### ❌ Parse JSON trước khi tính HMAC

```js
// SAI — body đã bị parser modify
app.use(express.json());
app.post('/webhook', (req, res) => {
  const expected = createHmac(secret, JSON.stringify(req.body)).digest('hex');
  // → KHÔNG match vì JSON.stringify khác raw bytes Zorio gửi
});

// ĐÚNG — dùng raw bytes
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = createHmac(secret, req.body).digest('hex');
});
```

### ❌ So `==` thay vì timing-safe

```js
// SAI — leak signature từng byte qua timing attack
if (sig === expected) { ... }

// ĐÚNG
if (crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) { ... }
```

### ❌ Không check timestamp

Không check timestamp → replay attack. Kẻ tấn công bắt 1 event hợp lệ → gửi lại 1.000 lần cách 1 năm sau vẫn pass signature.

### ❌ Reverse proxy modify body

Một số reverse proxy (nginx + module compress) hoặc Cloudflare có thể nén lại body → bytes khác. Config skip compression cho route webhook:

```nginx
location /webhook {
    gzip off;
    proxy_pass http://app;
}
```

### ❌ Cấu hình TLS sai

Zorio CHỈ gửi đến URL HTTPS. Nếu cert TLS:

- Self-signed → Zorio reject ngay.
- Expired → Zorio reject.
- Hostname mismatch → Zorio reject.

Test: `curl https://your-webhook-url/` từ ngoài internet, không lỗi cert.

## Replay protection cấp 2 (optional)

Để bảo mật cao hơn, dedupe theo cả `(timestamp + body hash)` thay vì chỉ `Delivery UUID`:

```js
const fingerprint = ts + ':' + sha256(rawBody);
const isNew = await redis.set(`zorio:fp:${fingerprint}`, '1', 'NX', 'EX', 600);
if (!isNew) return res.status(200).send('Duplicate fingerprint');
```

Lý do: nếu attacker bắt được 1 request hợp lệ trong window 300s, vẫn không replay được vì fingerprint đã thấy.

## Tài liệu liên quan

- [Webhook → Đăng ký](/webhooks/dang-ky)
- [Webhook → Ký HMAC chi tiết](/webhooks/hmac)
- [Webhook → Retry policy](/webhooks/retry)
- [Webhook → Mẫu receiver Node/PHP/Python/Go](/webhooks/receiver-mau)


---

# Giới thiệu

<!-- source: https://docs.zorio.vn/bat-dau/gioi-thieu.md -->

# Giới thiệu

Zorio là nền tảng Contact Center cho doanh nghiệp gồm:

- **PBX**: tổng đài SIP/WebRTC, hỗ trợ máy nhánh nội bộ, hàng đợi (queue), IVR, ghi âm, click-to-call.
- **Telesales**: dialer + chiến dịch + lead + caller-ID rotation + báo cáo + audit log.
- **AutoCall TTS**: voice bot tự động hoá outbound với DTMF actions + voice library.
- **Webphone SDK**: SDK WebRTC nhúng webphone vào CRM/ứng dụng riêng của khách hàng.
- **Webhook outbound**: gửi sự kiện realtime qua HMAC-SHA256 ký chuẩn ngành.

Tài liệu này phục vụ:

| Đối tượng | Mục đích sử dụng |
|---|---|
| **Đối tác CRM** | Tích hợp Zorio vào CRM riêng (Salesforce, HubSpot, Odoo, custom...) |
| **Đội kỹ thuật doanh nghiệp** | Xây ứng dụng riêng quanh hệ thống Zorio đã được cấp |
| **AI agent** (Claude Code, Codex, GPT...) | Tự động đọc tài liệu, sinh code tích hợp, debug request |
| **Bất kỳ developer nào** | Tham khảo public REST API + SDK của Zorio |

## Các bước tích hợp điển hình

1. **Lấy thông tin truy cập**: đăng nhập vào tài khoản Zorio đã được cấp → vào trang Cài đặt → API tokens → tạo token mới.
2. **Xác định module cần tích hợp**: PBX (cuộc gọi cơ bản), Telesales (dialer), AutoCall (TTS bot), Webphone (giao diện gọi).
3. **Đọc tài liệu module tương ứng** trong portal này.
4. **Gọi thử endpoint** bằng cURL/Postman.
5. **Cài đặt webhook** để nhận sự kiện realtime nếu cần.
6. **Triển khai production**.

## Kiến trúc tích hợp

```
┌──────────────────────────┐
│ Hệ thống/CRM của bạn     │
└──────────┬───────────────┘
           │
   REST API (Bearer token)  +  Webhook (HMAC-SHA256)  +  Webphone SDK
           │
┌──────────▼───────────────┐
│ app.zorio.vn    │  ← REST API endpoint chính
│  ├─ /api/pbx/...         │
│  ├─ /api/telesales/...   │
│  ├─ /api/autocall/...    │
│  └─ /api/integrations/   │
└──────────┬───────────────┘
           │
┌──────────▼───────────────┐
│ Zorio PBX (SIP/WebRTC)  │
└──────────────────────────┘
```

## Tiếp theo

- [Khái niệm cơ bản](/bat-dau/khai-niem) — Tài khoản khách hàng, tên miền, vai trò, permission tier.
- [Lấy API Token](/bat-dau/xin-token) — Cấp token từ tài khoản đã được cấp.
- [Quy ước chung](/bat-dau/quy-uoc) — Base URL, pagination, error format, timestamp.


---

# Khái niệm cơ bản

<!-- source: https://docs.zorio.vn/bat-dau/khai-niem.md -->

# Khái niệm cơ bản

## Tài khoản khách hàng

Mỗi khách hàng Zorio có hệ thống riêng biệt với:

- Tên miền truy cập riêng (vd `app.zorio.vn` hoặc tên miền tuỳ chỉnh do khách hàng cấu hình).
- API token cấp riêng cho mỗi hệ thống.

## Tên miền & Base URL

| Loại | Format | Ví dụ |
|---|---|---|
| Trang quản trị | tên miền của khách hàng | `app.zorio.vn` |
| API endpoint | `<tên miền>/api/...` | `app.zorio.vn/api/pbx/extensions` |
| SIP/WebRTC | `<tên miền>:5061` (TLS) | `app.zorio.vn:5061` |
| Webhook nhận từ Zorio | URL nhận của bạn | (do bạn cấu hình) |

## Vai trò + Permission tier

Người dùng trong tài khoản có vai trò:

- **admin**: toàn quyền trong tài khoản.
- **supervisor**: quản lý đội/chiến dịch.
- **agent**: gọi/nhận cuộc + cập nhật lead.
- **read_only**: chỉ xem.

Permission tier áp cho module (vd `crm`, `pbx`, `autocall`):

- **viewer**: chỉ xem.
- **operator**: thao tác CRUD cơ bản.
- **admin**: full quyền module.

::: tip Lưu ý
Permission `pbx_api_access` là điều kiện tiên quyết để gọi PBX API. Tương tự `telesales_api_access`, `autocall_api_access`.
:::

## Cô lập dữ liệu

Mọi resource đều được enforce theo tài khoản ở backend. Token sai khách hàng → HTTP 404 (không leak existence).


---

# Quy ước chung

<!-- source: https://docs.zorio.vn/bat-dau/quy-uoc.md -->

# Quy ước chung

## Base URL

| Loại | URL |
|---|---|
| REST API | `https://app.zorio.vn/api/` |
| Webhook nhận (do bạn cấu hình) | URL của bạn |

Tên miền truy cập được cấp riêng khi onboarding.

## Header chuẩn

Mọi request:

```
Authorization: Bearer <token>
Accept: application/json
```

Mọi request có body:

```
Content-Type: application/json; charset=utf-8
```

## Response shape

### Single resource / action

```json
{ "data": {} }
```

### List (paginated)

```json
{
  "current_page": 1,
  "data": [],
  "last_page": 5,
  "per_page": 50,
  "total": 234
}
```

### Error

```json
{
  "message": "Mô tả lỗi tóm tắt",
  "errors": { "field_name": ["Mô tả chi tiết"] }
}
```

## Pagination

Query `?page=1&per_page=50` (mặc định 50, tối đa 200).

## Timestamp & Timezone

Mọi datetime ở **ISO 8601** với offset:

- UTC: `2026-06-30T03:30:45+00:00`
- VN: `2026-06-30T10:30:45+07:00`

Khi gửi request, chấp nhận cả định dạng có/không microseconds (`.000000Z`).

## Status codes phổ biến

| HTTP | Khi nào |
|---|---|
| 200 | OK |
| 201 | Created |
| 202 | Accepted (async) |
| 400 | Bad request |
| 401 | Token thiếu / sai / expired |
| 403 | Thiếu permission |
| 404 | Resource không tồn tại |
| 409 | Conflict (duplicate / state machine vi phạm) |
| 422 | Validation lỗi |
| 429 | Rate limit hit (kèm `Retry-After`) |
| 500 | Server error |

## Phone number format

- **Lưu trong DB**: format E.164 không dấu `+` (vd `84987654321`).
- **Request body chấp nhận**: cả `0987654321` lẫn `84987654321` — backend tự normalize.
- **Response trả về**: format gốc client gửi lên (preserve).

## Recording URL

Ghi âm trả qua **signed URL** TTL **30 phút** (HMAC SHA256). Client download trong 30' — quá hạn phải request URL mới qua endpoint `/recording`.


---

# Lấy API Token

<!-- source: https://docs.zorio.vn/bat-dau/xin-token.md -->

# Lấy API Token

## Tổng quan

API token là **Bearer (phiên user) token** cấp cho user của khách hàng. Mỗi user tự quản lý token riêng — admin có thể revoke token của user khác.

## Lấy token từ tài khoản đã được cấp

1. **Đăng nhập** vào trang admin: `https://app.zorio.vn`
2. Vào **Cài đặt** → **API Tokens**.
3. Bấm **Tạo token mới** → đặt tên + chọn permission scope.
4. **Sao chép token** ngay — chỉ hiển thị 1 lần. Mất → revoke + tạo mới.

::: warning Bảo mật token
- KHÔNG commit token vào git.
- KHÔNG nhúng token trong code frontend.
- Lưu token ở vault/secret manager (1Password, AWS Secrets Manager, ...).
- Token có thể bị **revoke** bất cứ lúc nào → CRM cần handle 401 graceful.
:::

## Dùng token trong request

Mọi request HTTP gửi tới API kèm 2 header:

```
Authorization: Bearer <YOUR_TOKEN>
Accept: application/json
```

### Ví dụ cURL

```bash
curl -X GET 'https://app.zorio.vn/api/pbx/extensions' \
  -H 'Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz0123456789' \
  -H 'Accept: application/json'
```

### Ví dụ Node.js

```js
const response = await fetch('https://app.zorio.vn/api/pbx/extensions', {
  headers: {
    Authorization: 'Bearer ' + process.env.ZORIO_TOKEN,
    Accept: 'application/json',
  },
});
const json = await response.json();
```

## Token rotation

Khuyến nghị rotation 90 ngày 1 lần — chuẩn ngành.

## Khi token bị revoke

API trả **HTTP 401** với body:

```json
{ "message": "Unauthenticated." }
```

CRM cần catch 401 → hiển thị thông báo "Token hết hạn" + hướng dẫn user vào trang admin lấy token mới.


---

# Campaigns

<!-- source: https://docs.zorio.vn/en/api/autocall/campaigns.md -->

# Campaigns

Manage AutoCall campaigns — CRUD + lifecycle controls (launch / pause / resume / archive / unarchive) + statistics.

## Create a campaign

```http
POST /api/autocall/campaigns
```

**Body**:
```json
{
  "name": "Customer care Q3-2026",
  "description": "Reactivation outreach for customers inactive 30-60 days",
  "script_id": 12,
  "caller_id_group_id": 3,
  "max_retries": 3,
  "retry_interval_minutes": 60,
  "retry_only_when": "no_answer",
  "max_concurrent": 10,
  "originate_timeout": 40,
  "write_to_main_cdr": false,
  "start_at": "2026-06-25T08:00:00Z",
  "end_at": "2026-06-30T17:30:00Z"
}
```

**Fields**:

| Field | Required | Type | Description |
|---|---|---|---|
| `name` | Yes | string, max:255 | Campaign name |
| `description` | No | string, max:2000 | Description |
| `script_id` | Yes | integer | TTS script ID (see [Scripts](/en/api/autocall/scripts)). Must exist **AND** be `status='active'`. Passing a `draft`/`archived` script returns **422**. |
| `caller_id_group_id` | No | integer | Caller-ID pool ID. Leave empty → engine falls back to the account's default trunk. Must exist + `status='active'`. |
| `max_retries` | No | integer (0-10, default 3) | Maximum retries when an attempt fails |
| `retry_interval_minutes` | No | integer (1-43200, default 60) | Delay between attempts (minutes) |
| `retry_only_when` | No | enum (`no_answer`/`busy`/`failed`/`any`, default `no_answer`) | Only retry when attempt result matches |
| `max_concurrent` | No | integer (1-200, default 10) | Maximum concurrent calls |
| `originate_timeout` | No | integer (10-180, default 40) | Timeout waiting for B-leg to answer (seconds) |
| `write_to_main_cdr` | No | boolean (default false) | Whether to write into the main system CDR. False = log internally to AutoCall only. |
| `start_at` | No | datetime UTC | Time at which dialing is allowed to begin. Leave empty = launch immediately |
| `end_at` | No | datetime UTC | Stop time (must be > start_at) |

**Response 201** (full field set returned):
```json
{
  "data": {
    "id": 19,
    "tenant_id": 1,
    "name": "Customer care Q3-2026",
    "description": "Reactivation outreach for customers inactive 30-60 days",
    "script_id": 12,
    "status": "draft",
    "gateway_name": null,
    "caller_id": null,
    "caller_id_group_id": 8,
    "max_retries": 3,
    "retry_interval_minutes": 60,
    "retry_only_when": "no_answer",
    "write_to_main_cdr": false,
    "max_concurrent": 10,
    "originate_timeout": 40,
    "start_at": "2026-06-25T08:00:00.000000Z",
    "end_at": "2026-06-30T17:30:00.000000Z",
    "total_leads": 0,
    "total_calls": 0,
    "total_connected": 0,
    "total_failed": 0,
    "created_by": 3,
    "created_at": "2026-06-25T09:53:47.000000Z",
    "updated_at": "2026-06-25T09:53:47.000000Z",
    "deleted_at": null
  }
}
```

::: tip Note
The response includes every configuration field of the campaign. Stats fields (`total_*`) are 0 at creation time (no lead/call activity yet). Fields `gateway_name` and `caller_id` (single-number override) are null when the pool referenced by `caller_id_group_id` is used. `deleted_at` is null until the campaign is archived (soft delete).
:::

**Response 422** (validation):
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "script_id": ["The selected script id is invalid."],
    "retry_only_when": ["The selected retry only when is invalid."]
  }
}
```

## Lifecycle controls

| Endpoint | Action | From → To |
|---|---|---|
| `POST /api/autocall/campaigns/{id}/launch` | Activate | `draft`/`paused` → `active` |
| `POST /api/autocall/campaigns/{id}/pause` | Pause | `active` → `paused` |
| `POST /api/autocall/campaigns/{id}/resume` | Resume | `paused` → `active` (alias of launch) |
| `POST /api/autocall/campaigns/{id}/archive` | Archive | `draft`/`paused`/`done` → `archived` (campaign must NOT be active) |
| `POST /api/autocall/campaigns/{id}/unarchive` | Restore | `archived` → `paused` |
| `PUT /api/autocall/campaigns/{id}` | Update metadata | keeps current status |
| `DELETE /api/autocall/campaigns/{id}` | Delete PERMANENTLY | requires `archived` first (hard delete cascade: campaign + leads + attempts + dtmf_events) |

::: warning Mandatory rules
- You must `pause` before `archive` (an active campaign cannot be archived).
- You must `archive` before `delete` (permanent deletion → all report data is lost).
:::

**Response 200** (applies to every launch/pause/resume/archive/unarchive action):
```json
{
  "data": {
    "id": 21,
    "tenant_id": 1,
    "name": "Customer care Q3-2026 2",
    "description": "Reactivation outreach for customers inactive 30-60 days",
    "script_id": 12,
    "status": "active",
    "gateway_name": null,
    "caller_id": null,
    "caller_id_group_id": 8,
    "max_retries": 3,
    "retry_interval_minutes": 60,
    "retry_only_when": "no_answer",
    "write_to_main_cdr": false,
    "max_concurrent": 10,
    "originate_timeout": 40,
    "start_at": "2026-06-25T08:00:00.000000Z",
    "end_at": "2026-06-30T17:30:00.000000Z",
    "total_leads": 0,
    "total_calls": 0,
    "total_connected": 0,
    "total_failed": 0,
    "created_by": 3,
    "created_at": "2026-06-25T14:26:16.000000Z",
    "updated_at": "2026-06-25T14:27:41.000000Z",
    "deleted_at": null
  }
}
```

**Extra fields** (not present in the POST body):

| Field | Type | Description |
|---|---|---|
| `gateway_name` | string \| null | Override of the dial gateway (default null = default routing) |
| `caller_id` | string \| null | Override of a single caller ID (default null = use the pool from `caller_id_group_id`) |
| `total_leads` | integer | Total leads imported into the campaign |
| `total_calls` | integer | Total calls dialed |
| `total_connected` | integer | Total successfully connected calls |
| `total_failed` | integer | Total failed calls |
| `deleted_at` | timestamp \| null | Soft delete timestamp (null while not archived) |

::: tip Timestamps format
ISO 8601 with **microseconds** `.000000Z`. Client parsers must support this format (e.g. `new Date("2026-06-25T14:26:16.000000Z")` in JavaScript works correctly).
:::

**Response 422** (state machine failure):
```json
{ "message": "Only draft/paused campaigns can be launched" }
{ "message": "Only active campaigns can be paused" }
{ "message": "Campaign must be paused before archiving" }
{ "message": "Only archived campaigns can be restored" }
{ "message": "Campaign must be archived before permanent deletion (Archive → Delete)" }
```

**Response 200** (`PUT /api/autocall/campaigns/{id}` — update metadata): returns the updated campaign object, same shape as Response 201.

**Response 200** (`DELETE /api/autocall/campaigns/{id}`):
```json
{ "data": { "deleted": true } }
```

## List / show details / stats

### `GET /api/autocall/campaigns?status=active`

**Query params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `status` | string | No | Filter by campaign status | `draft` / `active` / `paused` / `done` / `archived` |
| `archived` | integer | No | Fetch archived campaigns. By default archived ones are HIDDEN | `1` = archived only; empty = exclude archived |
| `q` | string | No | Fuzzy search by campaign name (LIKE `%keyword%`) | Any text string |

**Response 200**:
```json
{
  "data": [
    {
      "id": 36,
      "name": "Customer care Q3-2026",
      "status": "active",
      "script": { "id": 12, "name": "Standard care", "voice_id": "evln-vi-nature" },
      "total_leads": 487,
      "total_calls": 312,
      "total_connected": 198,
      "total_failed": 89,
      "created_at": "2026-06-24T07:30:00Z"
    }
  ]
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data[].id` | integer | Campaign ID | Positive integer |
| `data[].name` | string | Campaign name | Up to 255 characters |
| `data[].status` | string | Current lifecycle status | `draft` / `active` / `paused` / `done` / `archived` |
| `data[].script` | object | Attached TTS script (eager-loaded) | Object with `id`, `name`, `voice_id` |
| `data[].script.id` | integer | Script ID | Positive integer |
| `data[].script.name` | string | Script name | — |
| `data[].script.voice_id` | string | TTS voice ID used by the script | — |
| `data[].total_leads` | integer | Total leads imported into the campaign | >= 0 |
| `data[].total_calls` | integer | Total calls dialed | >= 0 |
| `data[].total_connected` | integer | Total connected calls (B-leg answered) | >= 0 |
| `data[].total_failed` | integer | Total failed calls | >= 0 |
| `data[].created_at` | datetime ISO 8601 | Campaign creation time (UTC) | — |

### `GET /api/autocall/campaigns/{id}`

Returns the full details including `script.dtmfActions` and `agents`.

**Path params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `id` | integer | Yes | Campaign ID | Positive integer existing in the account |

**Response 200**:
```json
{
  "data": {
    "id": 36,
    "name": "Customer care Q3-2026",
    "description": "Reactivation outreach for customers inactive 30-60 days",
    "status": "active",
    "script_id": 12,
    "caller_id_group_id": 3,
    "max_retries": 3,
    "retry_interval_minutes": 60,
    "retry_only_when": "no_answer",
    "max_concurrent": 10,
    "originate_timeout": 40,
    "write_to_main_cdr": false,
    "start_at": "2026-06-25T08:00:00Z",
    "end_at": "2026-06-30T17:30:00Z",
    "total_leads": 487,
    "total_calls": 312,
    "total_connected": 198,
    "total_failed": 89,
    "tenant_id": 1,
    "created_by": 7,
    "created_at": "2026-06-24T07:30:00Z",
    "updated_at": "2026-06-25T02:34:00Z",
    "script": {
      "id": 12,
      "name": "Standard care",
      "voice_id": "evln-vi-nature",
      "dtmf_actions": [
        { "id": 45, "digit": "1", "label": "Confirm", "action_type": "playback_then_hangup", "target_audio_url": "/media/thanks.wav" },
        { "id": 46, "digit": "2", "label": "Transfer to agent", "action_type": "queue", "target_queue_name": "support_queue" }
      ]
    },
    "agents": []
  }
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data.id` | integer | Campaign ID | Positive integer |
| `data.name` | string | Campaign name | — |
| `data.description` | string \| null | Description | — |
| `data.status` | string | Lifecycle status | `draft` / `active` / `paused` / `done` / `archived` |
| `data.script_id` | integer | ID of the TTS script in use | — |
| `data.caller_id_group_id` | integer \| null | Caller-ID rotation pool ID | — |
| `data.max_retries` | integer | Maximum retries when an attempt fails | 0-10 |
| `data.retry_interval_minutes` | integer | Delay between attempts (minutes) | 1-43200 |
| `data.retry_only_when` | string | Only retry when the result matches | `no_answer` / `busy` / `failed` / `any` |
| `data.max_concurrent` | integer | Maximum concurrent calls | 1-200 |
| `data.originate_timeout` | integer | Timeout waiting for B-leg to answer (seconds) | 10-180 |
| `data.write_to_main_cdr` | boolean | Whether to record into the main system CDR | `true` / `false` |
| `data.start_at` | datetime ISO 8601 \| null | Earliest time dialing may begin (UTC) | — |
| `data.end_at` | datetime ISO 8601 \| null | Time dialing must stop (UTC) | — |
| `data.total_leads` | integer | Total leads imported | >= 0 |
| `data.total_calls` | integer | Total calls dialed | >= 0 |
| `data.total_connected` | integer | Total connected calls | >= 0 |
| `data.total_failed` | integer | Total failed calls | >= 0 |
| `data.tenant_id` | integer | ID of the owning account | — |
| `data.created_by` | integer | User ID of the creator | — |
| `data.created_at` | datetime ISO 8601 | Creation time (UTC) | — |
| `data.updated_at` | datetime ISO 8601 | Last update time (UTC) | — |
| `data.script` | object | Attached TTS script + DTMF keypress list | — |
| `data.script.dtmf_actions[]` | array | DTMF keypress configuration of the script (see [Scripts](/en/api/autocall/scripts)) | — |
| `data.agents[]` | array | Agents specifically assigned to the campaign (empty if none) | — |

**Response 404** (campaign does not exist or belongs to a different account):
```json
{ "message": "Campaign not found" }
```

### `GET /api/autocall/campaigns/{id}/stats`

**Path params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `id` | integer | Yes | Campaign ID | Positive integer |

**Response 200**:
```json
{
  "data": {
    "total_leads": 487,
    "total_calls": 312,
    "total_connected": 198,
    "total_failed": 89,
    "total_no_answer": 65,
    "total_busy": 18,
    "connection_rate": 63.5
  }
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data.total_leads` | integer | Total leads imported into the campaign | >= 0 |
| `data.total_calls` | integer | Total calls dialed | >= 0 |
| `data.total_connected` | integer | Total connected calls (B-leg answered) | >= 0 |
| `data.total_failed` | integer | Total failed calls (sum of `failed` + `no_answer` + `busy`) | >= 0 |
| `data.total_no_answer` | integer | Total unanswered calls | >= 0 |
| `data.total_busy` | integer | Total busy calls | >= 0 |
| `data.connection_rate` | number | Successful connection rate (`total_connected / total_calls * 100`) | 0-100, rounded to 1 decimal |

### `GET /api/autocall/campaigns/{id}/attempts?per_page=50`

List of calls for a campaign (standard pagination via `page`/`per_page`, default 50, max 200).

**Path params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `id` | integer | Yes | Campaign ID | Positive integer |

**Query params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `page` | integer | No | Page number (1-indexed) | >= 1, default `1` |
| `per_page` | integer | No | Attempts per page | 1-200, default `50` |

**Response 200**:
```json
{
  "data": [
    {
      "id": 8721,
      "uuid": "093e1024-1234-5678-9abc-def012345678",
      "campaign_id": 36,
      "lead_id": 78912,
      "lead_phone_number": "0912345678",
      "attempt_number": 1,
      "started_at": "2026-06-24T08:32:00Z",
      "answered_at": "2026-06-24T08:32:05Z",
      "ended_at": "2026-06-24T08:32:47Z",
      "duration_sec": 42,
      "result": "connected",
      "hangup_cause": "NORMAL_CLEARING",
      "dtmf_pressed": "2",
      "final_action": "queue:support_queue"
    }
  ],
  "current_page": 1,
  "last_page": 7,
  "per_page": 50,
  "total": 312
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data[].id` | integer | Attempt ID | Positive integer |
| `data[].uuid` | string | Call UUID (used for hangup or lookup) | UUID v4 |
| `data[].campaign_id` | integer | Campaign ID | — |
| `data[].lead_id` | integer | Lead ID | — |
| `data[].lead_phone_number` | string | Lead phone number (E.164 `84xxx`) | — |
| `data[].attempt_number` | integer | Which attempt this is | 1-N |
| `data[].started_at` | datetime ISO 8601 | Originate start time (UTC) | — |
| `data[].answered_at` | datetime ISO 8601 \| null | B-leg answer time (UTC) | null if not answered |
| `data[].ended_at` | datetime ISO 8601 | Call end time (UTC) | — |
| `data[].duration_sec` | integer | Total call duration (seconds) | >= 0 |
| `data[].result` | string | Call outcome | `connected` / `no_answer` / `busy` / `failed` / `abandoned` |
| `data[].hangup_cause` | string | Hangup code from Zorio PBX | `NORMAL_CLEARING` / `NO_ANSWER` / `USER_BUSY` / ... |
| `data[].dtmf_pressed` | string \| null | DTMF key pressed by the called party (if any) | `0`-`9`, `*`, `#`, null |
| `data[].final_action` | string \| null | Final action executed | `queue:<name>` / `playback:<url>` / `hangup` / `switch:<id>` |
| `current_page` | integer | Current page | >= 1 |
| `last_page` | integer | Last page | >= 1 |
| `per_page` | integer | Items per page | 1-200 |
| `total` | integer | Total attempts matching the filter | >= 0 |

## Caller-ID Groups (read-only picker)

### `GET /api/autocall/caller-id-pools`

Returns the list of caller-ID pools so you can pick a `caller_id_group_id` when creating a campaign.

**Response 200**:
```json
{
  "data": [
    {
      "id": 3,
      "name": "Pool VNPT 028",
      "label": "Pool VNPT 028",
      "description": "5 numbers in 028xxxx, Round Robin rotation"
    }
  ]
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data[].id` | integer | Pool ID — used as `caller_id_group_id` when calling `POST /api/autocall/campaigns` | Positive integer |
| `data[].name` | string | Pool name (technical identifier) | Up to 255 characters |
| `data[].label` | string | Friendly display name for the UI | Up to 255 characters |
| `data[].description` | string \| null | Short description of the pool (rotation strategy, list of numbers...) | — |

## Hangup an in-progress call

Hangup an in-progress call from an AutoCall campaign — AutoCall and Telesales share the same hangup endpoint.

```http
POST /api/telesales/calls/{uuid}/hangup
```

**Path params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `uuid` | string | Yes | Call UUID (from the `call.answered` webhook event or the `uuid` field of an attempt) | UUID v4 belonging to the current account |

**Sample request**:
```bash
curl -X POST https://app.zorio.vn/api/telesales/calls/abc-def-123/hangup \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

**Response 200**:
```json
{ "success": true }
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `success` | boolean | Hangup command successfully sent to Zorio PBX | `true` |

**Error 404** (uuid does not exist or does not belong to the account):
```json
{ "error": "Call not found" }
```

::: warning Permission
Requires `manage_telesales_campaigns` or the `admin` role. The call ends with hangup cause `NORMAL_CLEARING`.
:::


---

# AutoCall TTS API — Overview

<!-- source: https://docs.zorio.vn/en/api/autocall/index.md -->

# AutoCall TTS API — Overview

> Public REST API for the AutoCall TTS module — automated outbound calling with natural-sounding TTS voices + DTMF actions + voices library.
>
> **Authentication**: Bearer Token (user session). **Base URL**: `https://app.zorio.vn/api/autocall/` (provisioned per customer).

## Scope

The AutoCall API covers these groups:

- Campaign management (Campaigns).
- Scripts + DTMF actions (playback / playback_then_hangup / switch_script / queue / repeat_script / hangup).
- Leads + Variables (`{{xxx}}` placeholders inside the template).
- Voices + Media files (Tier A premium realtime, Tier B local pre-rendered).
- Reports — KPIs / Trend / Comparison / Hangup / Heatmap / DTMF / Funnel / Export.
- Webhook events.

## Tier A / Tier B

- **Tier A**: premium realtime — TTS via a premium provider, billed per character. You bring your own API key.
- **Tier B**: local unlimited — uses the pre-rendered vi-VN-female-01 audio library, no per-character cost. Recommended default for high-volume use.

## Glossary

| Term | Meaning |
|---|---|
| Campaign | Outbound TTS campaign bound to 1 script + lead list + caller-ID configuration + dial pacing |
| Script | TTS script containing a `template_text` with `{{placeholder}}` variables + a DTMF action tree |
| DTMF | Keypad digits the called party presses after hearing the TTS (0-9, *, #) — Zorio captures them for branching |
| DTMF action | Behavior when the called party presses a key — `playback` / `playback_then_hangup` / `switch_script` / `queue` / `repeat_script` / `hangup` |
| Lead | A phone number to call + the variable payload used in the TTS render |
| Variable | A variable defined by the customer that represents dynamic data in the script (e.g. `customer_name`, `appointment_date`, `callback_date`) |
| Voice | A specific voice (e.g. `vi-VN-female-01` for Tier B, `Roger` for Tier A premium TTS provider) |
| Media file | An audio file uploaded for direct playback (no TTS) — used for fixed intros, music on hold, IVR fallback |
| Tier A | Realtime TTS via a premium provider — high quality, billed per character |
| Tier B | Pre-rendered audio library — no fee, high throughput, fixed voice |
| Attempt | A single dial of one lead — may be retried on busy / no_answer |
| Hangup cause | Standard Q.850 reason code for call termination — see [Hangup codes](/en/reference/hangup-codes) |

## End-to-end workflow

```
1. Login                  POST /api/auth/login        → Bearer token
2. Create script          POST /api/autocall/scripts  → ID + template_text + dtmf_actions
3. Create campaign        POST /api/autocall/campaigns → bind script_id + caller_id_group_id
4. Import leads           POST /api/autocall/campaigns/{id}/leads
5. Launch                 POST /api/autocall/campaigns/{id}/start
6. Realtime monitoring    Webhook autocall.lead.* delivered to your URL
7. View reports           GET  /api/autocall/campaigns/{id}/reports/...
8. Pause / Resume / Stop  POST /api/autocall/campaigns/{id}/pause | resume | stop
```

## Authentication

Use a Bearer Token (user session) — see [Authentication](/en/auth/sanctum-bearer) for details.

```
Authorization: Bearer <token>
Accept: application/json
```

Required permission: `autocall_api_access` (granted to the admin role by default). Some sensitive endpoints (e.g. start campaign) additionally require `autocall_manage_campaign`.

## Endpoint groups

| Group | Documentation |
|---|---|
| Campaigns | [Open page](/en/api/autocall/campaigns) |
| Scripts + DTMF actions | [Open page](/en/api/autocall/scripts) |
| Leads + Variables | [Open page](/en/api/autocall/leads) |
| Voices + Media files | [Open page](/en/api/autocall/voices) |
| Reports | [Open page](/en/api/autocall/reports) |
| AutoCall webhook events | [Open page](/en/api/autocall/webhooks) |

## General conventions

### Pagination

Every list endpoint uses `?page=1&per_page=50` (max 200). Standard paginated response — see [General conventions](/en/getting-started/conventions).

### Response shape

```json
{ "data": {} }                              // single resource
{ "current_page": 1, "data": [], ... }      // list paginated
{ "message": "...", "errors": {} }          // 422 validation
```

### Timezone

ISO 8601 with offset (`2026-06-30T07:30:45+00:00`). The backend returns timestamps with microseconds (`.000000Z`) — requests accept either format.

### Phone numbers

- Stored in the DB in E.164 without the leading `+` (e.g. `84987654321`).
- Request bodies accept `0xxx` or `84xxx` — the backend normalizes them automatically.
- Responses return the original format the client sent (preserved).

## Rate limit

| Endpoint group | Limit |
|---|---|
| `/api/autocall/*` | 120 req/min/token |
| `/api/autocall/campaigns/{id}/leads` (bulk import) | 30 req/min/token |
| `/api/autocall/campaigns/{id}/start` | 5 req/min/token |

See [Rate limit + Idempotency](/en/auth/rate-limit) for details.

## HTTP Status Codes

| HTTP | When |
|---|---|
| 200 | OK |
| 201 | Created (new campaign / script / lead) |
| 202 | Accepted (campaign start enqueued, audio render in progress) |
| 401 | Missing / invalid / expired token |
| 403 | Missing `autocall_api_access` or `autocall_manage_campaign` permission |
| 404 | Resource does not exist within the account |
| 409 | State machine violation (e.g. start a campaign that is already running) |
| 422 | Validation error — see `errors[]` for field details |
| 429 | Rate limit hit |
| 500 | Server error |

## Base URL

| | URL |
|---|---|
| Production | `https://app.zorio.vn/api/autocall/` (provisioned per customer) |

## FAQ

**Q1: Which Vietnamese voice is best?**

A: Tier B ships **vi-VN-female-01** pre-rendered — high quality, no fee, high throughput. Tier A offers more voices via the provider — list them via `GET /api/autocall/voices`.

**Q2: What is the maximum number of leads per campaign?**

A: No hard limit. We recommend ≤ **100,000 leads** per campaign so the engine processes them smoothly.

**Q3: Where do I receive the DTMF data when the called party presses a key?**

A: Subscribe to the `autocall.lead.dtmf_pressed` webhook — it fires every keypress. The payload includes `digit` + `lead_id` + `script_id`.

**Q4: Audio render is failing — how do I troubleshoot?**

A: Check in this order:
1. Is `voice_id` still `status=active` in `/api/autocall/voices`?
2. Does the Tier A provider have a valid key and remaining quota?
3. For Tier B: is the `voice_id` pre-rendered in the audio library?
4. Does the template contain any `{{xxx}}` variable that has not been defined in Variables?

**Q5: Can I transfer to a live agent when the called party presses a DTMF key?**

A: Yes — set `action_type=queue` in the DTMF action and provide `target_queue_name`. The call is transferred into the queue and an available agent picks it up.


---

# Leads + Variables

<!-- source: https://docs.zorio.vn/en/api/autocall/leads.md -->

# Leads + Variables

Manage leads (bulk import, list, blacklist/DNC) and customer-defined TTS variables used in the `template_text`.

## Push leads into a campaign (bulk)

```http
POST /api/autocall/campaigns/{id}/leads/import
```

**Path params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `id` | integer | Yes | Target campaign ID | Positive integer existing in the account |

**Body**:
```json
{
  "leads": [
    {
      "phone": "0912345678",
      "payload": {
        "name": "Nguyễn Văn An",
        "amount": "500000",
        "callback_date": "2026-06-30",
        "order_id": "ORD-12345"
      }
    },
    {
      "phone": "0987654321",
      "payload": {
        "name": "Trần Thị Bích",
        "amount": "1200000",
        "callback_date": "2026-07-05"
      }
    }
  ]
}
```

**Body fields**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `leads` | array | Yes | Array of leads to push into the campaign | Up to 5000 items per request |
| `leads[].phone` | string | Yes | Lead phone number, Vietnamese format | `0xxx` / `84xxx` / `+84xxx` (auto-normalized). Legacy alias `phone_number` is also accepted |
| `leads[].payload` | object | Yes (if the template uses variables) | JSON object containing TTS variables keyed by `variable_code`. Legacy alias `variables` is also accepted | snake_case keys matching defined `variable_code` values |

**Field `phone`**: required, Vietnamese format. **Internally stored in E.164 `84xxx`** (for dedup + DNC matching), but **GET endpoints return the original `0xxx` format** to match the client input. *The legacy alias `phone_number` is still accepted in request bodies for backward compatibility — RECOMMENDED to use `phone` for new integrations.*

::: tip Example
The client sends `"phone": "0987654321"` → the `GET` response returns `"phone_number": "0987654321"`. The system stores E.164 `84987654321` for dedup with DNC. Search `?phone=0987` is normalized automatically.
:::

**Field `payload`**: a JSON object containing TTS variables keyed by the `variable_code` previously defined in the pool (see [Variables](#variables-customer-defined-tts-variables)). Keys must match `variable_code` (lowercase snake_case). *The legacy alias `variables` is accepted.*

**Behaviour**:
- Leads with a duplicate phone within the same campaign → skipped → counted in `skipped_duplicate`
- Leads in DNC → skipped → counted in `skipped_dnc`
- Invalid phone format → skipped → counted in `skipped_invalid`, reason `invalid_phone_format`
- **Payload missing variables required** by `script.template_text` placeholders `{{xxx}}` → skipped → counted in `skipped_invalid`, reason `missing_variables`
- Leads are inserted with `status=pending`; the audio render job dispatches asynchronously
- If the campaign is `active` → the engine picks the lead as soon as the audio is ready

::: warning Validate variables vs template_text
The system extracts `{{xxx}}` placeholders from the campaign's `script.template_text` → every such key MUST be present in the lead's `payload`. Any missing key → the lead is rejected and logged into `errors[]` (max 20 samples). This ensures the audio render succeeds for every lead.
:::

**Response 200** (with some leads missing variables):
```json
{
  "data": {
    "inserted": 1,
    "skipped_invalid": 2,
    "skipped_duplicate": 0,
    "skipped_dnc": 0,
    "errors": [
      {
        "index": 0,
        "phone": "0912345678",
        "reason": "missing_variables",
        "missing": ["total_amount", "appointment_date"],
        "hint": "Script template_text requires variables: {{total_amount}}, {{appointment_date}} — the payload is missing them."
      },
      { "index": 487, "phone": "0912abc", "reason": "invalid_phone_format" }
    ]
  }
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data.inserted` | integer | Number of leads inserted successfully | >= 0 |
| `data.skipped_invalid` | integer | Leads skipped because invalid (bad phone format / missing variable) | >= 0 |
| `data.skipped_duplicate` | integer | Leads skipped because of a duplicate phone in the same campaign | >= 0 |
| `data.skipped_dnc` | integer | Leads skipped because they are on the DNC list | >= 0 |
| `data.errors[]` | array | Sample errors (up to 20 items) | — |
| `data.errors[].index` | integer | Position of the lead in the request `leads` array | 0-indexed |
| `data.errors[].phone` | string | Phone number of the failed lead | — |
| `data.errors[].reason` | string | Skip reason | `missing_variables` / `invalid_phone_format` / `duplicate` / `dnc_blocked` |
| `data.errors[].missing` | string[] | Missing variables (only with `reason=missing_variables`) | — |
| `data.errors[].hint` | string | Hint for fixing the error | — |

::: tip Bulk limit
Bulk lead push is capped at **5000 leads per request** (chunk client-side if you have more). Lead import rate limit: **5 batches/min/token**.
:::

## List leads

### `GET /api/autocall/campaigns/{id}/leads?status=pending&page=1`

**Path params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `id` | integer | Yes | Campaign ID | Positive integer |

**Query params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `status` | string \| string[] | No | Filter by lead status (single or `status[]=a&status[]=b`) | `pending` / `dialing` / `connected` / `completed` / `failed` / `abandoned` / `blacklisted` |
| `phone` | string | No | Fuzzy search by phone number (auto-normalized to 84xxx) | Digits |
| `page` | integer | No | Page number | >= 1, default `1` |
| `per_page` | integer | No | Leads per page | 1-200, default `50` |

**Response 200**:
```json
{
  "data": [
    {
      "id": 78912,
      "campaign_id": 36,
      "phone_number": "84912345678",
      "payload": {"name": "Nguyễn Văn An", "amount": "500000"},
      "status": "completed",
      "attempt_count": 1,
      "last_attempt_at": "2026-06-24T08:32:00Z",
      "last_hangup_cause": "NORMAL_CLEARING",
      "next_retry_at": null,
      "final_audio_path": "/audio/render/lead_78912.wav",
      "created_at": "2026-06-24T07:35:00Z"
    }
  ],
  "current_page": 1,
  "last_page": 10,
  "per_page": 50,
  "total": 487
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data[].id` | integer | Lead ID | Positive integer |
| `data[].campaign_id` | integer | Campaign ID | — |
| `data[].phone_number` | string | Phone number in E.164 format (`84xxx`) | — |
| `data[].payload` | object | TTS variables received at import time | snake_case keys |
| `data[].status` | string | Lead lifecycle status | `pending` / `dialing` / `connected` / `completed` / `failed` / `abandoned` / `blacklisted` |
| `data[].attempt_count` | integer | Number of times dialed | >= 0 |
| `data[].last_attempt_at` | datetime ISO 8601 \| null | Most recent attempt time (UTC) | — |
| `data[].last_hangup_cause` | string \| null | Hangup cause of the last attempt | `NORMAL_CLEARING` / `NO_ANSWER` / ... |
| `data[].next_retry_at` | datetime ISO 8601 \| null | Next scheduled retry time (UTC) | null if no further retry |
| `data[].final_audio_path` | string \| null | Path to the rendered WAV (server-local) | — |
| `data[].created_at` | datetime ISO 8601 | Lead import time (UTC) | — |
| `current_page` | integer | Current page | >= 1 |
| `last_page` | integer | Last page | >= 1 |
| `per_page` | integer | Items per page | 1-200 |
| `total` | integer | Total leads matching the filter | >= 0 |

### `GET /api/autocall/leads?campaign_id=36&phone=0912&status[]=completed&status[]=failed`

Cross-campaign lead listing. The response shape is the same as the endpoint above (`data[]` + pagination).

**Query params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `campaign_id` | integer | No | Filter by campaign | Existing campaign ID |
| `phone` | string | No | Fuzzy search by phone number | — |
| `status[]` | string[] | No | Multi-status filter | `pending` / `dialing` / `connected` / `completed` / `failed` / `abandoned` / `blacklisted` |
| `from` | datetime ISO 8601 | No | Filter by `created_at >= from` | `YYYY-MM-DD` or ISO 8601 |
| `to` | datetime ISO 8601 | No | Filter by `created_at <= to` | `YYYY-MM-DD` or ISO 8601 |
| `per_page` | integer | No | Leads per page | 1-200, default `50` |

## Bulk actions

### Blacklist

```http
POST /api/autocall/leads/blacklist
```

**Body**:
```json
{
  "phones": ["0912345678", "0987654321"],
  "lead_ids": [78912, 78913],
  "reason": "Customer requested no further calls",
  "source": "customer_request"
}
```

**Body fields**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `phones` | string[] | No (one of two) | Phone numbers to blacklist | Vietnamese format (`0xxx` / `84xxx`) |
| `lead_ids` | integer[] | No (one of two) | Lead IDs — corresponding phones are auto-resolved and merged into `phones` | Existing lead IDs |
| `reason` | string | No | Reason for blacklisting (stored in the DNC log) | Up to 500 characters |
| `source` | string | No | Blacklist source | `manual` / `customer_request` / `duplicate` / `complaint` / `other` (default `manual`) |

**Response 200**:
```json
{ "data": { "blacklisted": 2 } }
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data.blacklisted` | integer | Number of phones inserted into the DNC (after dedup) | >= 0 |

### Unblacklist

```http
POST /api/autocall/leads/unblacklist
{ "phones": ["0912345678"] }
```

**Body fields**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `phones` | string[] | Yes | Phones to remove from the DNC | Vietnamese format |

**Response 200**: `{"data": {"unblacklisted": 1}}`

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data.unblacklisted` | integer | Number of phones removed from the DNC | >= 0 |

### Bulk re-render audio

```http
POST /api/autocall/leads/bulk-rerender
{ "lead_ids": [78912, 78913] }
```

Re-dispatch the audio render job for the given leads (e.g. when the script has changed and needs to be re-rendered).

**Body fields**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `lead_ids` | integer[] | Yes | Lead IDs whose audio should be re-rendered | Existing lead IDs in the account |

**Response 200**: `{"data": {"dispatched": 2}}`

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data.dispatched` | integer | Number of render jobs queued | >= 0 |

## Do-Not-Call list

### `GET /api/autocall/dnc?phone=0912&source=manual`

**Query params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `phone` | string | No | Fuzzy search by phone number | — |
| `source` | string | No | Filter by blacklist source | `manual` / `customer_request` / `duplicate` / `complaint` / `other` |
| `page` | integer | No | Page number | >= 1, default `1` |
| `per_page` | integer | No | Items per page | 1-200, default `50` |

**Response 200**:
```json
{
  "data": [
    {
      "id": 543,
      "phone_number": "84912345678",
      "source": "customer_request",
      "reason": "Customer request",
      "blocked_by": 7,
      "created_at": "2026-06-24T07:40:00Z"
    }
  ],
  "current_page": 1,
  "last_page": 12,
  "per_page": 50,
  "total": 567
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data[].id` | integer | DNC record ID | Positive integer |
| `data[].phone_number` | string | Phone number in E.164 (`84xxx`) | — |
| `data[].source` | string | Blacklist source | `manual` / `customer_request` / `duplicate` / `complaint` / `other` |
| `data[].reason` | string \| null | Blacklist reason | — |
| `data[].blocked_by` | integer \| null | User ID who blocked the number | — |
| `data[].created_at` | datetime ISO 8601 | Blacklist time (UTC) | — |
| `current_page` | integer | Current page | >= 1 |
| `last_page` | integer | Last page | >= 1 |
| `per_page` | integer | Items per page | 1-200 |
| `total` | integer | Total records matching the filter | >= 0 |

::: tip DNC is global per account
A number on the DNC list is skipped from EVERY campaign belonging to that account.
:::

## Variables (customer-defined TTS variables)

Customer-defined variables used inside `template_text`. At render time the system resolves `{{variable_code}}` according to its `data_type` → applying the right formatting (money → spelled-out amount, date → "the fifteenth of July"...).

### List variables

```http
GET /api/autocall/variables
```

**Response 200**:
```json
{
  "data": [
    {
      "id": 1,
      "code": "name",
      "label": "Customer name",
      "data_type": "name",
      "description": "Given name of the customer"
    },
    {
      "id": 2,
      "code": "salutation_name",
      "label": "Salutation + name",
      "data_type": "salutation_name",
      "description": "e.g. Mr. An, Ms. Bich"
    },
    {
      "id": 3,
      "code": "amount",
      "label": "Amount",
      "data_type": "money",
      "description": "Amount in VND, read out in words"
    }
  ]
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data[].id` | integer | Variable ID | Positive integer |
| `data[].code` | string | Variable key (used as a payload key when importing leads, and as `{{code}}` in `template_text`) | snake_case, max 64 chars, unique per account, immutable |
| `data[].label` | string | Localized display name | Up to 255 characters |
| `data[].data_type` | string | Data type so TTS reads the value correctly | `name` / `salutation_name` / `salutation_fullname` / `fullname` / `date` / `time` / `number` / `money` |
| `data[].description` | string \| null | User-facing description | Up to 2000 characters |

**Supported data types**:

| `data_type` | Description | Input example | Spoken output |
|---|---|---|---|
| `name` | Short name | "Nam" | "Nam" |
| `salutation_name` | Salutation + name | "anh Nam" | "anh Nam" |
| `salutation_fullname` | Salutation + full name | "anh Nguyễn Văn Nam" | full |
| `fullname` | Full name | "Nguyễn Văn Nam" | full |
| `date` | Date Y-m-d | "2026-06-30" | "the thirtieth of June, two thousand twenty-six" |
| `time` | Time H:i | "14:30" | "fourteen thirty" |
| `number` | Integer | "1234" | "one thousand two hundred thirty-four" |
| `money` | VND amount | "500000" | "five hundred thousand dong" |

### CRUD variables (admin only)

```http
POST   /api/autocall/variables       (admin tier)
PUT    /api/autocall/variables/{id}
DELETE /api/autocall/variables/{id}
```

Create/update body:
```json
{
  "code": "order_id",
  "label": "Order code",
  "data_type": "name",
  "description": "Format ORD-xxxxx",
  "example_value": "ORD-12345",
  "sort_order": 100,
  "is_active": true
}
```

| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| `code` | Yes (create) | string, max 64, snake_case | — | Variable key, unique per account, **immutable** once created |
| `label` | Yes | string, max 255 | — | Display name |
| `data_type` | Yes | enum (8 types, see table above) | — | Data type so TTS reads the value correctly |
| `description` | No | string, max 2000 | null | Description |
| `example_value` | No | string | null | Sample value used for TTS preview |
| `sort_order` | No | integer | 999 | Display order in the UI picker |
| `is_active` | No | boolean | true | Disable the variable (does NOT delete) — scripts still render but the UI hides it |

`is_builtin: true` (read-only) marks built-in system variables — they cannot be deleted nor have their `code` changed.

**`POST /api/autocall/variables` response 201**:
```json
{
  "data": {
    "id": 15,
    "code": "order_id",
    "label": "Order code",
    "data_type": "name",
    "description": "Format ORD-xxxxx",
    "example_value": "ORD-12345",
    "sort_order": 100,
    "is_active": true,
    "is_builtin": false,
    "tenant_id": 1,
    "created_at": "2026-06-25T03:00:00Z",
    "updated_at": "2026-06-25T03:00:00Z"
  }
}
```

**`PUT /api/autocall/variables/{id}` response 200**: same shape as the POST response (updated object). Send only fields you want to change (partial update). The `code` field is immutable — the system ignores it if sent.

**`DELETE /api/autocall/variables/{id}` response 200**:
```json
{ "data": { "deleted": true } }
```

**Response 422** (built-in variable):
```json
{ "message": "Cannot delete a built-in variable (is_builtin=true)" }
```

**Response 422** (create validation — e.g. duplicate `code`):
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "code": ["The code has already been taken."]
  }
}
```


---

# Reports

<!-- source: https://docs.zorio.vn/en/api/autocall/reports.md -->

# Reports

Reporting endpoints for AutoCall campaigns — KPIs, trend, comparison, hangup analysis, heatmap, DTMF analytics, funnel, and Excel export.

::: tip Required permission
Every endpoint below requires `autocall_api_access`. The export endpoint additionally requires `autocall_export_report`.
:::

## GET `/api/autocall/campaigns/{id}/reports/kpis` — KPI summary

### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `from` | datetime | optional | Window start | ISO 8601. Default: campaign start time |
| `to` | datetime | optional | Window end | ISO 8601. Default: now |
| `timezone` | string | optional | Aggregation timezone | Default: `Asia/Ho_Chi_Minh` |

### Response 200

```json
{
  "data": {
    "total_leads": 5000,
    "dialed": 4823,
    "answered": 3120,
    "no_answer": 1234,
    "busy": 287,
    "failed": 182,
    "abandoned": 0,
    "answer_rate_pct": "64.69",
    "avg_call_duration_sec": 42,
    "total_talk_time_sec": 131040,
    "dtmf_distribution": {
      "1": 1840,
      "2": 950,
      "0": 215,
      "no_input": 115
    },
    "transfer_to_queue_count": 1840,
    "transfer_success_rate_pct": "98.21",
    "computed_at": "2026-06-30T08:00:00+00:00"
  }
}
```

### Field reference

| Field | Description |
|---|---|
| `total_leads` | Total leads in the campaign |
| `dialed` | Number of attempts executed (a single lead may have many attempts) |
| `answered` / `no_answer` / `busy` / `failed` | Breakdown by `result` |
| `answer_rate_pct` | `answered ÷ dialed × 100` — the main quality metric for the pool |
| `avg_call_duration_sec` | Average `billsec` for answered calls |
| `dtmf_distribution` | Distribution of pressed keys (key = digit, value = count) |
| `transfer_to_queue_count` | Number of calls successfully transferred to an agent queue |

## GET `/api/autocall/campaigns/{id}/reports/trend` — Daily trend

### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `from` | date | optional | Start date | YYYY-MM-DD |
| `to` | date | optional | End date | YYYY-MM-DD |
| `granularity` | string | optional | Bucket size | `day` (default), `hour` |

### Response 200

```json
{
  "data": [
    {
      "bucket": "2026-06-28",
      "dialed": 1200,
      "answered": 780,
      "answer_rate_pct": "65.00",
      "avg_duration_sec": 41,
      "transfer_count": 460
    },
    {
      "bucket": "2026-06-29",
      "dialed": 1612,
      "answered": 1098,
      "answer_rate_pct": "68.11",
      "avg_duration_sec": 43,
      "transfer_count": 642
    }
  ]
}
```

Use this for a line chart that tracks campaign performance over time.

## GET `/api/autocall/campaigns/comparison` — Compare several campaigns

::: tip Cross-campaign endpoint
Unlike other endpoints (which are nested under a campaign), this one lives directly at `/campaigns/comparison` so you can compare N campaigns at once.
:::

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `campaign_ids` | string | Yes | Comma-separated campaign IDs (e.g. `5,8,12`) |
| `metric` | string | optional | Metric to compare: `answer_rate_pct` (default) / `avg_duration_sec` / `transfer_rate_pct` |

### Response 200

```json
{
  "data": [
    { "campaign_id": 5,  "campaign_name": "Renewal Q3",      "metric_value": "62.30" },
    { "campaign_id": 8,  "campaign_name": "Cross-sell Q3",   "metric_value": "55.18" },
    { "campaign_id": 12, "campaign_name": "Win-back churned", "metric_value": "48.92" }
  ]
}
```

## GET `/api/autocall/campaigns/{id}/reports/hangup` — Hangup reason analysis

Helps operations understand why a campaign is failing so they can optimize it.

### Response 200

```json
{
  "data": {
    "total_calls": 4823,
    "by_hangup_cause": [
      { "hangup_cause": "NORMAL_CLEARING",   "count": 3120, "pct": "64.69" },
      { "hangup_cause": "NO_ANSWER",         "count": 1234, "pct": "25.59" },
      { "hangup_cause": "USER_BUSY",         "count": 287,  "pct": "5.95" },
      { "hangup_cause": "CALL_REJECTED",     "count": 95,   "pct": "1.97" },
      { "hangup_cause": "RECOVERY_ON_TIMER", "count": 87,   "pct": "1.80" }
    ]
  }
}
```

Hangup code reference: [Hangup cause codes](/en/reference/hangup-codes).

## GET `/api/autocall/campaigns/{id}/reports/heatmap` — Hour × day heatmap

Visualize the busiest hours of the week to adjust the schedule.

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `metric` | string | optional | `dialed` (default) / `answered` / `answer_rate_pct` |

### Response 200

```json
{
  "data": [
    { "day_of_week": 1, "hour": 9,  "dialed": 156, "answered": 102, "answer_rate_pct": "65.38" },
    { "day_of_week": 1, "hour": 10, "dialed": 178, "answered": 121, "answer_rate_pct": "67.98" },
    { "day_of_week": 2, "hour": 14, "dialed": 201, "answered": 134, "answer_rate_pct": "66.67" }
  ]
}
```

`day_of_week`: `0` = Sunday, `1` = Monday, ... `6` = Saturday. Flat array of 168 entries (7 days × 24 hours).

## GET `/api/autocall/campaigns/{id}/reports/dtmf` — Detailed DTMF analysis

### Response 200

```json
{
  "data": {
    "total_answered": 3120,
    "with_dtmf_input": 3005,
    "no_input": 115,
    "no_input_rate_pct": "3.69",
    "by_digit": [
      { "digit": "1", "count": 1840, "pct": "61.23", "label": "Accept transfer to agent" },
      { "digit": "2", "count": 950,  "pct": "31.61", "label": "Not interested" },
      { "digit": "0", "count": 215,  "pct": "7.16",  "label": "Replay" }
    ],
    "by_script_path": [
      { "path": "intro -> press_1 -> queue_sales", "count": 1840 },
      { "path": "intro -> press_2 -> playback_polite -> hangup", "count": 950 }
    ]
  }
}
```

`label` is taken from the script's `dtmf_actions[].label`.

## GET `/api/autocall/campaigns/{id}/reports/funnel` — Conversion funnel

### Response 200

```json
{
  "data": [
    { "stage": "Imported lead",       "count": 5000, "drop_rate_pct": null    },
    { "stage": "Dialed",              "count": 4823, "drop_rate_pct": "3.54"  },
    { "stage": "Answered",            "count": 3120, "drop_rate_pct": "35.31" },
    { "stage": "Pressed valid DTMF",  "count": 3005, "drop_rate_pct": "3.69"  },
    { "stage": "Transferred to agent","count": 1840, "drop_rate_pct": "38.77" },
    { "stage": "Agent disposed",      "count": 1640, "drop_rate_pct": "10.87" }
  ]
}
```

`drop_rate_pct`: drop ratio versus the previous stage.

## POST `/api/autocall/campaigns/{id}/reports/export` — Export to Excel

### Request body

| Field | Type | Required | Description | Values |
|---|---|---|---|---|
| `report_type` | string | Yes | Report kind | `kpis` / `trend` / `hangup` / `dtmf` / `funnel` / `full` |
| `from` | date | optional | Window from | YYYY-MM-DD |
| `to` | date | optional | Window to | YYYY-MM-DD |
| `format` | string | optional | File format | `xlsx` (default) / `csv` |

### Request body (JSON)

```json
{
  "report_type": "full",
  "from": "2026-06-01",
  "to": "2026-06-30",
  "format": "xlsx"
}
```

### Response 202 (Accepted, async)

```json
{
  "data": {
    "job_id": "export_a7b3c5d2",
    "status": "queued",
    "report_type": "full",
    "estimated_seconds": 30
  }
}
```

### Polling for status

```
GET /api/autocall/campaigns/{id}/reports/export/{job_id}
```

```json
{
  "data": {
    "job_id": "export_a7b3c5d2",
    "status": "ready",
    "download_url": "https://app.zorio.vn/api/public/exports/...?signature=...",
    "expires_in_seconds": 3600,
    "file_size": 542600,
    "completed_at": "2026-06-30T08:01:23+00:00"
  }
}
```

`status` enum: `queued` / `running` / `ready` / `failed` / `expired`.

### Download

`download_url` is a signed URL with a TTL of **1 hour** — follow the redirect to download the `.xlsx` file.

## Best practice

### Cache reports

KPIs / Trend change slowly (aggregates update once a minute). Cache for 1-5 minutes in your CRM to reduce load.

### Realtime vs Reports

- **Realtime** (lead-level updates): subscribe to the `autocall.lead.*` webhooks.
- **Reports** (aggregates): poll these endpoints on an interval (every 1-5 minutes).

Do NOT poll Reports every second — it wastes rate limit budget and is unnecessary.

### Exporting large volumes

For campaigns with > 50k leads, `full` exports can take 1-2 minutes. To avoid blocking the UI:

1. Submit the job via POST -> receive a `job_id`.
2. Poll status every 5 seconds.
3. On `ready` -> trigger an auto-download or show a "Download file" button.

## Related documentation

- [AutoCall — Overview](/en/api/autocall/)
- [AutoCall — Campaigns](/en/api/autocall/campaigns)
- [AutoCall — Webhooks](/en/api/autocall/webhooks)
- [Hangup cause codes](/en/reference/hangup-codes)


---

# Scripts + DTMF actions

<!-- source: https://docs.zorio.vn/en/api/autocall/scripts.md -->

# Scripts + DTMF actions

Manage TTS scripts (template + voice + DTMF actions) for AutoCall. Includes script CRUD, the DTMF action types enum, a queue helper list, and TTS preview.

## Create a script

```http
POST /api/autocall/scripts
```

**Body**:
```json
{
  "name": "Standard care",
  "description": "Template for the reactivation care campaign for customers inactive 30-60 days",
  "template_text": "Hello {{salutation_name}}, this is a reminder of your appointment on {{callback_date}}. Press 1 to confirm, press 2 to be transferred to an agent, press 9 to skip.",
  "voice_id": "voice_id_premium_02",
  "tts_tier": "B",
  "max_repeat_per_attempt": 1,
  "status": "draft",
  "dtmf_actions": [
    {
      "digit": "1",
      "label": "Confirm appointment",
      "action_type": "playback_then_hangup",
      "target_audio_url": "/media/thank_you.wav"
    },
    {
      "digit": "2",
      "label": "Transfer to agent",
      "action_type": "queue",
      "target_queue_name": "support@default"
    },
    {
      "digit": "9",
      "label": "Skip",
      "action_type": "hangup"
    }
  ]
}
```

**Fields**:

| Field | Required | Type | Description |
|---|---|---|---|
| `name` | Yes | string, max:255 | Script name |
| `template_text` | Yes | text | Template with `{{variable_code}}` placeholders |
| `voice_id` | Yes | string | Voice ID — MUST come from `GET /api/autocall/voices` ([Voices](/en/api/autocall/voices)). The system automatically routes to the matching provider. A `voice_id` that does not exist in the available voice library returns **422**. |
| `tts_tier` | No | enum (`A`/`B`, default `B`) | **A** = premium, rendered realtime by a premium TTS provider with your own key, billed per character. **B** = local unlimited, uses the pre-rendered Vietnamese voice library, no fee, high throughput. Recommended default `B` for high volume. |
| `max_repeat_per_attempt` | No | integer (1-5, default 1) | Times to replay the audio if the user does not press DTMF |
| `status` | No | enum (`draft`/`active`/`archived`, default `draft`) | Only `active` scripts can be used by the engine for real campaign runs |
| `dtmf_actions[]` | No | array max:12 | Keypress configuration; each item has `digit`/`label`/`action_type`/`target_*` |

::: warning The `voice_provider` field is NOT in the request body
You do NOT pass it. The system auto-routes by `voice_id` → the matching tier (A premium / B local). The server response still RETURNS this field — read-only, indicating which provider was used.
:::

**Error 422 — `voice_id` does not exist**:
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "voice_id": [
      "voice_id 'voice_id_premium_01' does not exist in the available voice library. Fetch the valid voice list via GET /api/autocall/voices."
    ]
  }
}
```

### DTMF action types

| `action_type` | Required companion field | Behavior |
|---|---|---|
| `playback` | `target_audio_url` | Play the file then wait for the next DTMF |
| `playback_then_hangup` | `target_audio_url` | Play the file then hang up |
| `switch_script` | `target_script_id` | Load a different script, replay from the beginning |
| `queue` | `target_queue_name` (= queue `name` identifier) | Transfer into a queue for a live agent to answer |
| `hangup` | — | Hang up immediately |
| `repeat_script` | — | Replay the full current script audio |

::: tip Fetch the enum dynamically via API
Instead of hardcoding the 6 action types client-side, you can fetch the full enum from `GET /api/autocall/dtmf-action-types` (see [List action types](#list-action-types-for-dtmf-enum--label)). Similarly, the list of `target_queue_name` values comes from `GET /api/autocall/queues` (see [List queues](#list-queues-for-action_type-queue)).
:::

::: warning Reference-integrity validation (server-side)
- `playback` / `playback_then_hangup` → `target_audio_url` MUST match the `file_path` of a media file belonging to the account (from `GET /api/media-files`). Passing an external URL → 422.
- `switch_script` → `target_script_id` MUST be an existing script in the account (from `GET /api/autocall/scripts`). Passing a bogus ID → 422.
- `queue` → `target_queue_name` MUST match the `name` of an active queue (from `GET /api/autocall/queues`). Mismatched → 422.
:::

**Error 422 sample**:
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "dtmf_actions.0.target_audio_url": [
      "target_audio_url '/data/wrong/path.wav' does not exist in the customer's Media Files. Upload via POST /api/media-files first, then use the returned file_path."
    ]
  }
}
```

## List action types for DTMF (enum + label)

```http
GET /api/autocall/dtmf-action-types
```

**Purpose**: returns the 6 action types together with localized labels and the list of required companion fields. Integrators use this to populate the "Behavior on keypress" dropdown in the UI without hardcoding the enum.

**Response 200**:
```json
{
  "data": [
    {
      "code": "playback",
      "label": "Play audio",
      "description": "Play the specified audio file, then continue the script.",
      "required_fields": ["target_audio_url"]
    },
    {
      "code": "playback_then_hangup",
      "label": "Play audio then hang up",
      "description": "Play the audio file and then hang up automatically.",
      "required_fields": ["target_audio_url"]
    },
    {
      "code": "switch_script",
      "label": "Switch to another script",
      "description": "Switch the call to a different AutoCall script (chained IVR).",
      "required_fields": ["target_script_id"]
    },
    {
      "code": "queue",
      "label": "Transfer to agent queue",
      "description": "Transfer the call into a queue for a live agent.",
      "required_fields": ["target_queue_name"]
    },
    {
      "code": "repeat_script",
      "label": "Repeat the script",
      "description": "Replay the current script from the beginning (so the called party can listen again).",
      "required_fields": []
    },
    {
      "code": "hangup",
      "label": "Hang up",
      "description": "End the call immediately.",
      "required_fields": []
    }
  ]
}
```

**Response fields**:

| Field | Type | Description |
|---|---|---|
| `code` | string | Enum value to use for `dtmf_actions[].action_type` in `POST/PUT /scripts` |
| `label` | string | Display label for the dropdown UI |
| `description` | string | Short description shown to the end user |
| `required_fields` | string[] | List of companion fields that must accompany this action (e.g. `playback` → requires `target_audio_url`) |

## List queues for `action_type=queue`

```http
GET /api/autocall/queues
```

**Purpose**: returns the list of active queues so the client can use them as `target_queue_name` when picking `action_type=queue`. Populates the "Select queue" dropdown in the UI.

**Response 200**:
```json
{
  "data": [
    {
      "id": 1,
      "name": "support_q1",
      "queue_number": "2001",
      "strategy": "ring_all"
    },
    {
      "id": 2,
      "name": "sales_outbound",
      "queue_number": "2002",
      "strategy": "longest_idle_agent"
    }
  ]
}
```

**Response fields**:

| Field | Type | Description |
|---|---|---|
| `id` | integer | Queue DB ID (for reference) |
| `name` | string | Queue technical name — USED as `target_queue_name` when POST/PUT a script with a DTMF `queue` action |
| `queue_number` | string | Queue extension number (e.g. `2001`) — displayed to the end user |
| `strategy` | string | Distribution strategy: `ring_all` / `longest_idle_agent` / `round_robin` / ... |

::: danger Important note
The `target_queue_name` field in `dtmf_actions[]` MUST match the queue's **`name`** (not `queue_number` or `id`). Mismatches cause dialing to fail because the system cannot resolve the queue.
:::

## Sample Response 201 after creating a script

```json
{
  "data": {
    "name": "Standard care",
    "description": "Template for the reactivation care campaign for customers inactive 30-60 days",
    "template_text": "Hello {{salutation_name}}, this is a reminder of your appointment on {{appointment_date}}. Press 1 to confirm, press 2 to be transferred to an agent, press 9 to skip.",
    "voice_provider": "tts_provider_01",
    "voice_id": "evln-vi-nature",
    "tts_tier": "A",
    "max_repeat_per_attempt": 1,
    "status": "draft",
    "created_by": 3,
    "tenant_id": 1,
    "updated_at": "2026-06-25T04:37:49.000000Z",
    "created_at": "2026-06-25T04:37:49.000000Z",
    "id": 4,
    "dtmf_actions": [
      {
        "id": 1,
        "tenant_id": 1,
        "script_id": 4,
        "digit": "1",
        "label": "Confirm appointment",
        "action_type": "playback_then_hangup",
        "target_audio_url": "/media/thank_you.wav",
        "target_script_id": null,
        "target_queue_name": null,
        "sort_order": 0,
        "created_at": "2026-06-25T04:37:49.000000Z",
        "updated_at": "2026-06-25T04:37:49.000000Z"
      },
      {
        "id": 2,
        "tenant_id": 1,
        "script_id": 4,
        "digit": "2",
        "label": "Transfer to agent",
        "action_type": "queue",
        "target_audio_url": null,
        "target_script_id": null,
        "target_queue_name": "support@default",
        "sort_order": 1,
        "created_at": "2026-06-25T04:37:49.000000Z",
        "updated_at": "2026-06-25T04:37:49.000000Z"
      },
      {
        "id": 3,
        "tenant_id": 1,
        "script_id": 4,
        "digit": "9",
        "label": "Skip",
        "action_type": "hangup",
        "target_audio_url": null,
        "target_script_id": null,
        "target_queue_name": null,
        "sort_order": 2,
        "created_at": "2026-06-25T04:37:49.000000Z",
        "updated_at": "2026-06-25T04:37:49.000000Z"
      }
    ]
  }
}
```

::: tip Field order + tenant_id
The system serializes fields in **insert/create** order plus auto-injected ones (`created_at`/`updated_at`/`id`) at the end. The client MUST NOT rely on key order — parse by key name. `tenant_id` appears at both the script level and on each `dtmf_actions[]` item — redundant but correct, because both entities carry `tenant_id`.
:::

## List / show / update / delete

| Endpoint | Purpose |
|---|---|
| `GET /api/autocall/scripts?status=active` | List scripts (optional filter) |
| `GET /api/autocall/scripts/{id}` | Details including `dtmfActions` |
| `PUT /api/autocall/scripts/{id}` | Update. If `dtmf_actions` is sent → entire list is replaced |
| `DELETE /api/autocall/scripts/{id}` | Soft delete (returns 422 if still used by a campaign) |

### `GET /api/autocall/scripts` — list

**Query params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `status` | string | No | Filter by script status | `draft` / `active` / `archived` |

```json
{
  "data": [
    {
      "id": 2,
      "tenant_id": 1,
      "name": "Appointment reminder",
      "description": null,
      "template_text": "ABC Company kindly informs you of the service appointment on {{appointment_date}}. Please confirm before 6 PM on {{appointment_date}}. If you have already confirmed, please ignore this call. Press 3 to reach our hotline. Thank you.",
      "voice_provider": "tts_provider_01",
      "voice_id": "voice_id_premium_02",
      "tts_tier": "B",
      "audio_fixed_paths": null,
      "max_repeat_per_attempt": 1,
      "status": "active",
      "created_by": 1,
      "created_at": "2026-06-22T03:34:01.000000Z",
      "updated_at": "2026-06-22T08:11:49.000000Z",
      "deleted_at": null
    }
  ]
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data[].id` | integer | Script ID | Positive integer |
| `data[].tenant_id` | integer | ID of the account that owns the script | — |
| `data[].name` | string | Script name | Up to 255 characters |
| `data[].description` | string \| null | Description | Up to 2000 characters |
| `data[].template_text` | text | TTS template with `{{variable_code}}` placeholders | — |
| `data[].voice_provider` | string | TTS provider (read-only, derived from `voice_id`) | `tts_provider_01` / `local` / ... |
| `data[].voice_id` | string | TTS voice ID | From `GET /api/autocall/voices` |
| `data[].tts_tier` | string | TTS tier | `A` (premium realtime) / `B` (local pre-rendered) |
| `data[].audio_fixed_paths` | object \| null | Cache of rendered fixed audio segments (variable-free template parts). Integrators do not need to handle this | — |
| `data[].max_repeat_per_attempt` | integer | Times to replay audio if the user does not press DTMF | 1-5 |
| `data[].status` | string | Script status | `draft` / `active` / `archived` |
| `data[].created_by` | integer | User ID of the creator | — |
| `data[].created_at` | datetime ISO 8601 | Creation time (UTC, microseconds) | — |
| `data[].updated_at` | datetime ISO 8601 | Last update time (UTC, microseconds) | — |
| `data[].deleted_at` | datetime ISO 8601 \| null | Soft delete timestamp | null until deleted |

::: tip Timestamp format
The API returns ISO 8601 with microseconds `YYYY-MM-DDTHH:mm:ss.uuuuuuZ` (e.g. `2026-06-22T03:34:01.000000Z`). Clients should parse standard ISO 8601 (microseconds optional).
:::

### `GET /api/autocall/scripts/{id}` — details

Full object including `dtmf_actions[]`:
```json
{
  "data": {
    "id": 2,
    "tenant_id": 1,
    "name": "Appointment reminder",
    "description": null,
    "template_text": "ABC Company kindly informs you of the service appointment on {{appointment_date}}, with a total amount of {{total_amount}}. ... Thank you.",
    "voice_provider": "tts_provider_01",
    "voice_id": "voice_id_premium_02",
    "tts_tier": "B",
    "audio_fixed_paths": null,
    "max_repeat_per_attempt": 1,
    "status": "active",
    "created_by": 1,
    "created_at": "2026-06-22T03:34:01.000000Z",
    "updated_at": "2026-06-22T08:11:49.000000Z",
    "deleted_at": null,
    "dtmf_actions": [
      {
        "id": 7,
        "script_id": 2,
        "digit": "1",
        "label": "Confirm appointment",
        "action_type": "playback_then_hangup",
        "target_audio_url": "/media/thank_you.wav",
        "target_script_id": null,
        "target_queue_name": null,
        "sort_order": 0,
        "created_at": "2026-06-22T03:34:01.000000Z",
        "updated_at": "2026-06-22T03:34:01.000000Z"
      },
      {
        "id": 8,
        "script_id": 2,
        "digit": "3",
        "label": "Transfer to hotline",
        "action_type": "queue",
        "target_audio_url": null,
        "target_script_id": null,
        "target_queue_name": "support_queue",
        "sort_order": 1,
        "created_at": "2026-06-22T03:34:01.000000Z",
        "updated_at": "2026-06-22T03:34:01.000000Z"
      }
    ]
  }
}
```

### `PUT /api/autocall/scripts/{id}` — update

**Request**:
```http
PUT /api/autocall/scripts/2
Content-Type: application/json
Authorization: Bearer <token>
```

**Body** (partial update — send only fields to change; if you send `dtmf_actions` the system deletes all old DTMF entries and recreates them from the new array):
```json
{
  "name": "Appointment reminder — v2",
  "description": "Updated template for Q3-2026",
  "voice_id": "voice_id_premium_01",
  "max_repeat_per_attempt": 2,
  "dtmf_actions": [
    {
      "digit": "1",
      "label": "Confirm appointment",
      "action_type": "playback_then_hangup",
      "target_audio_url": "/media/thank_you.wav"
    },
    {
      "digit": "3",
      "label": "Transfer to hotline",
      "action_type": "queue",
      "target_queue_name": "support@default"
    }
  ]
}
```

**Response 200** (full updated script + new `dtmf_actions[]`):
```json
{
  "data": {
    "id": 2,
    "tenant_id": 1,
    "name": "Appointment reminder — v2",
    "description": "Updated template for Q3-2026",
    "template_text": "ABC Company kindly informs you of the service appointment on {{appointment_date}}, with a total amount of {{total_amount}}. ... Thank you.",
    "voice_provider": "tts_provider_01",
    "voice_id": "voice_id_premium_01",
    "tts_tier": "B",
    "audio_fixed_paths": null,
    "max_repeat_per_attempt": 2,
    "status": "active",
    "created_by": 1,
    "created_at": "2026-06-22T03:34:01.000000Z",
    "updated_at": "2026-06-25T04:49:00.000000Z",
    "deleted_at": null,
    "dtmf_actions": [
      {
        "id": 9,
        "tenant_id": 1,
        "script_id": 2,
        "digit": "1",
        "label": "Confirm appointment",
        "action_type": "playback_then_hangup",
        "target_audio_url": "/media/thank_you.wav",
        "target_script_id": null,
        "target_queue_name": null,
        "sort_order": 0,
        "created_at": "2026-06-25T04:49:00.000000Z",
        "updated_at": "2026-06-25T04:49:00.000000Z"
      },
      {
        "id": 10,
        "tenant_id": 1,
        "script_id": 2,
        "digit": "3",
        "label": "Transfer to hotline",
        "action_type": "queue",
        "target_audio_url": null,
        "target_script_id": null,
        "target_queue_name": "support@default",
        "sort_order": 1,
        "created_at": "2026-06-25T04:49:00.000000Z",
        "updated_at": "2026-06-25T04:49:00.000000Z"
      }
    ]
  }
}
```

::: warning PUT replaces DTMF
If the body includes `dtmf_actions[]`, the system deletes the script's existing DTMF entries and recreates them from the new array. If `dtmf_actions` is NOT sent → existing DTMF entries are preserved. → IDs of new DTMF entries will DIFFER from the old IDs (the old ones were deleted).
:::

### `DELETE /api/autocall/scripts/{id}`

```json
{ "data": { "deleted": true } }
```

**Response 422** (script is in use by an active campaign):
```json
{ "message": "Cannot delete a script in use by a campaign. Archive the campaign first." }
```

## Preview TTS — render a demo

```http
POST /api/autocall/scripts/{id}/preview
```

**Path params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `id` | integer | Yes | Script ID to preview | Positive integer existing in the account |

**Body** (optional):
```json
{
  "variables": {
    "salutation_name": "Mr. An",
    "amount": "500000",
    "callback_date": "2026-06-30"
  }
}
```

**Body fields**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `variables` | object | No | Map `{variable_code: value}` to substitute `{{xxx}}` placeholders in the template. Leave empty → the system uses default demo values according to each variable's `data_type` | Keys must match defined `variable_code` values |

**Response 200**:
```json
{
  "data": {
    "audio_url": "/api/autocall/scripts/12/preview-audio/preview_abc123.wav",
    "duration_sec": 12.4,
    "chars_used": 187
  }
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data.audio_url` | string | Internal path used to stream the preview WAV. A GET with the `Authorization` header returns binary `audio/wav` | Path relative to `app.zorio.vn` |
| `data.duration_sec` | number | Rendered audio duration (seconds) | > 0, rounded to 1 decimal |
| `data.chars_used` | integer | Characters consumed (billed for Tier A) | >= 0 |

::: tip Preview rate limit
TTS preview is capped at **10 req/min/token** (since it incurs TTS provider Tier A charges).
:::


---

# Voices + Media files

<!-- source: https://docs.zorio.vn/en/api/autocall/voices.md -->

# Voices + Media files

Two shared resource groups used in AutoCall:

- **Voices** — list of available TTS voices to set as `voice_id` when creating a script.
- **Media files** — audio files (`.wav`/`.mp3`/...) used as `target_audio_url` for the DTMF actions `playback` / `playback_then_hangup`.

## List voices available for AutoCall (RECOMMENDED for integration)

```http
GET /api/autocall/voices
```

**Purpose**: returns **only available voices**. These voices are **guaranteed to render preview/dial successfully** — they will NOT throw `Voice not available` as can happen with arbitrary voices from a provider.

**Response 200** (only the 5 fields the client needs):
```json
{
  "data": [
    {
      "id": "voice_id_premium_02",
      "name": "vi-VN-female-01",
      "preview_url": "https://app.zorio.vn/api/autocall/voices/preview",
      "gender": "female",
      "language": "vi"
    }
  ]
}
```

**Response fields**:

| Field | Type | Description |
|---|---|---|
| `id` | string | Voice ID — used as `voice_id` when calling `POST /api/autocall/scripts` |
| `name` | string | Friendly display name |
| `preview_url` | string \| null | MP3 sample URL for preview playback |
| `gender` | string \| null | `male` / `female` |
| `language` | string \| null | `vi` / `en` / ... |

::: tip Fallback when a provider fails
If a provider integration is temporarily unreachable (network/API key), the endpoint still returns the voice with only the `id` + `name=id` fields so the client does NOT error out — the UI can fall back to displaying the raw ID.
:::

::: tip Tier A vs Tier B
- **Tier A** = premium realtime via a premium TTS provider (per-character charge).
- **Tier B** = local pre-rendered vi-VN-female-01 (no fee, high throughput). Recommended default for high volume.

`tts_tier` is configured at the script level (see [Scripts](/en/api/autocall/scripts)). The system auto-routes by `voice_id` → matching provider.
:::

## Media Files (audio assets)

The standard Zorio Media Files module — upload audio files (`.wav`/`.mp3`/`.m4a`/...) and they are auto-converted to WAV 16-bit PCM 8 kHz mono. Inside AutoCall, use the `file_path` of a media file as `target_audio_url` for the DTMF actions `playback` / `playback_then_hangup`.

**Category enum**:
- `announcement` — announcement for DTMF actions (e.g. "Thank you", "Transferring you to an agent...")
- `ivr` — IVR prompts (greeting, menu...)
- `moh` — music on hold
- `library` — general

::: warning Permission
`manage_recordings` or `admin` is required to upload/edit/delete; viewers may list and fetch audio.
:::

### List media files

```http
GET /api/media-files?category=announcement
```

**Query**:

| Param | Type | Description |
|---|---|---|
| `category` | string, optional | Filter by the enum `ivr` / `moh` / `announcement` / `library`. Omit → return all |

**Response 200**:
```json
{
  "data": [
    {
      "id": 20,
      "tenant_id": 1,
      "name": "VNT v2",
      "file_path": "/media/ivr/studio-1776477792_1776477798_d939.wav",
      "file_size": 176718,
      "duration": 11,
      "format": "wav",
      "category": "ivr",
      "tts_text": null,
      "tts_voice": null,
      "tts_provider": null,
      "created_at": "2026-04-18 02:03:19"
    }
  ]
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data[].id` | integer | Media file ID | Positive integer |
| `data[].tenant_id` | integer | ID of the owning account | — |
| `data[].name` | string | Display name | Up to 255 characters |
| `data[].file_path` | string | File identifier (use as `target_audio_url`) for DTMF action `playback` | Internal identifier |
| `data[].file_size` | integer | File size (bytes) | > 0 |
| `data[].duration` | integer | Audio duration (seconds) | >= 0 |
| `data[].format` | string | Audio format (always `wav` after conversion) | `wav` |
| `data[].category` | string | File category | `ivr` / `moh` / `announcement` / `library` |
| `data[].tts_text` | string \| null | Source text (only != null if the file was synthesized via TTS) | — |
| `data[].tts_voice` | string \| null | Voice ID (only for TTS files) | — |
| `data[].tts_provider` | string \| null | TTS provider used | `tts_provider_01` / `local` / null |
| `data[].created_at` | datetime | Upload time (UTC, format `YYYY-MM-DD HH:mm:ss`) | — |

::: tip TTS metadata fields
`tts_text`, `tts_voice`, `tts_provider` are only != null when the file was synthesized via TTS (not relevant for manually uploaded files). Informational; integrators do not need to handle them.
:::

### Upload a media file

```http
POST /api/media-files
Content-Type: multipart/form-data
```

**Body (multipart)**:

| Field | Required | Type | Description |
|---|---|---|---|
| `file` | Yes | binary | Audio file (`.wav`, `.mp3`, `.m4a`, `.ogg`, `.aac`, `.flac`). Max 50 MB |
| `name` | Yes | string | Display name (e.g. "Thank you message") |
| `category` | No | enum | `ivr` / `moh` / `announcement` / `library`. Default `library` |

**Sample request (curl)**:
```bash
curl -X POST https://app.zorio.vn/api/media-files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -F "file=@thank-you.mp3" \
  -F "name=Thank you message" \
  -F "category=announcement"
```

**Response 201**:
```json
{
  "data": {
    "tenant_id": 1,
    "name": "Test",
    "file_path": "/media/library/test_1782374777.wav",
    "file_size": 43704,
    "duration": 3,
    "format": "wav",
    "category": "library",
    "id": 21
  },
  "message": "File uploaded and converted successfully."
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data.id` | integer | Newly created media file ID | Positive integer |
| `data.tenant_id` | integer | ID of the owning account | — |
| `data.name` | string | Display name | — |
| `data.file_path` | string | File identifier after conversion (WAV 16-bit PCM 8 kHz mono) | Internal identifier |
| `data.file_size` | integer | Converted file size (bytes) | > 0 |
| `data.duration` | integer | Audio duration (seconds) | >= 0 |
| `data.format` | string | Format after conversion | Always `wav` |
| `data.category` | string | File category | `ivr` / `moh` / `announcement` / `library` |
| `message` | string | Success confirmation message | — |

**Error 422** (wrong file format / too large):
```json
{
  "message": "The file must be a file of type: wav, mp3, m4a, ogg, aac, flac.",
  "errors": { "file": ["The file must be a file of type: wav, mp3, m4a, ogg, aac, flac."] }
}
```

**Error 500** (server missing audio conversion engine):
```json
{ "error": "audio conversion engine is not installed on the server" }
```

### Update media file metadata

```http
PATCH /api/media-files/{id}
```

Changes `name` / `category` only — the physical file is not touched.

**Path params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `id` | integer | Yes | ID of the media file to update | Positive integer |

**Body**:
```json
{
  "name": "Thank you — version 2",
  "category": "announcement"
}
```

**Body fields**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `name` | string | No | Change display name | Up to 255 characters |
| `category` | string | No | Change category | `ivr` / `moh` / `announcement` / `library` |

**Response 200**:
```json
{
  "data": {
    "id": 21,
    "tenant_id": 1,
    "name": "Thank you — version 2",
    "file_path": "/media/library/test_1782374777.wav",
    "file_size": 43704,
    "duration": 3,
    "format": "wav",
    "category": "announcement",
    "tts_text": null,
    "tts_voice": null,
    "tts_provider": null,
    "created_at": "2026-06-25 08:06:17"
  },
  "message": "Audio file updated."
}
```

**Response fields**: same shape as a `GET /api/media-files` item (see the table in [List media files](#list-media-files)) plus a `message` next to `data`.

### Replace the physical file (keep the same ID)

```http
POST /api/media-files/{id}/replace
Content-Type: multipart/form-data
```

The old file is backed up as `<path>.bak-<timestamp>` and the new content is written to the same `file_path` — IVR/DTMF actions referencing `target_audio_url` do not need to be updated because the path is unchanged.

**Path params**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `id` | integer | Yes | ID of the media file to replace | Positive integer |

**Body (multipart)**:

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `file` | binary | Yes | New audio file | `.wav`, `.mp3`, `.m4a`, `.ogg`, `.aac`, `.flac`, max 50 MB |

**Response 200**:
```json
{
  "data": {
    "id": 21,
    "tenant_id": 1,
    "name": "Thank you — version 2",
    "file_path": "/media/library/test_1782374777.wav",
    "file_size": 43704,
    "duration": 3,
    "format": "wav",
    "category": "announcement",
    "tts_text": null,
    "tts_voice": null,
    "tts_provider": null,
    "created_at": "2026-06-25 08:06:17"
  },
  "backup": "test_1782374777.wav.bak-20260625-080956",
  "message": "File replaced successfully. The previous version has been backed up."
}
```

**Response fields**:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `data` | object | Media file object (same shape as a `GET /api/media-files` item) | — |
| `backup` | string | Name of the backup file for the previous version. Full path = `dirname(file_path) + '/' + backup` | `<filename>.bak-<timestamp>` |
| `message` | string | Confirmation message | — |

::: tip `backup` field at top level
Not nested under `data` — it contains the backup file name. Full path = `dirname(file_path) + '/' + backup`.
:::

### Delete a media file

```http
DELETE /api/media-files/{id}
```

Deletes the DB record + physical file.

**Response 200**:
```json
{ "message": "Deleted." }
```

::: warning Audit before deleting
If a DTMF action's `target_audio_url` still references the file, dialing will fail with "file not found". Audit usage before deleting.
:::

### Stream audio (play preview)

```http
GET /api/media-files/{id}/audio
```

Returns a binary WAV stream with `Content-Type: audio/wav`. Use in an HTML5 `<audio>` tag or save via curl:

```bash
curl -s https://app.zorio.vn/api/media-files/5/audio \
  -H "Authorization: Bearer $TOKEN" \
  -o thank-you.wav
```


---

# AutoCall Webhook Events

<!-- source: https://docs.zorio.vn/en/api/autocall/webhooks.md -->

# AutoCall Webhook Events

When a call occurs, Zorio POSTs an event to the URL you registered (HMAC-signed).

## Events

| Event | When it fires |
|---|---|
| `autocall.lead.added` | A lead was successfully pushed into a campaign |
| `autocall.lead.audio_ready` | TTS audio rendering finished, the lead is ready to dial |
| `autocall.call.initiated` | The engine started originate |
| `autocall.call.answered` | B-leg answered |
| `autocall.dtmf.pressed` | The called party pressed a key (1 event per keypress) |
| `autocall.call.transferred` | DTMF action = queue → transferred to the queue successfully |
| `autocall.call.completed` | The call ended (any outcome) |
| `autocall.lead.completed` | The lead has finished every retry (final status) |
| `autocall.campaign.completed` | The campaign has no pending leads left |
| `autocall.tts.render_failed` | The TTS provider errored out and the lead was skipped |

## Common envelope

Every event uses the same envelope structure:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `event` | string | Full event name | `autocall.<entity>.<action>` |
| `timestamp` | datetime | When Zorio published the event (ISO 8601 UTC) | |
| `tenant_id` | integer | Account ID receiving the webhook | |
| `data` | object | Event-specific payload (see each event below) | |

## `data` fields per event

### `autocall.lead.added` / `autocall.lead.audio_ready` / `autocall.lead.completed`

| Field | Type | Description | Valid values |
|---|---|---|---|
| `lead_id` | integer | Lead ID in AutoCall | |
| `campaign_id` | integer | ID of the campaign containing the lead | |
| `phone` | string | Lead phone number | E.164 or Vietnamese domestic |
| `external_ref` | string\|null | External CRM reference (if you pushed one) | |
| `audio_url` | string\|null | TTS audio URL (only present on `audio_ready`) | |
| `final_status` | string | Final state (only present on `lead.completed`) | `completed` / `failed` / `dnc` / `max_attempts_reached` |
| `total_attempts` | integer | Total dial attempts (only on `lead.completed`) | >= 1 |

### `autocall.call.initiated`

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID | |
| `campaign_id` | integer | Campaign ID | |
| `lead_id` | integer | Lead ID | |
| `phone` | string | Number being dialed | |
| `attempt_number` | integer | Which attempt this is | >= 1 |
| `caller_id` | string | Caller-ID used for the call | |
| `started_at` | datetime | Originate time (ISO 8601 UTC) | |

### `autocall.call.answered`

Includes all fields of `call.initiated` plus:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `answered_at` | datetime | Time the B-leg answered (ISO 8601 UTC) | |

### `autocall.dtmf.pressed`

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID | |
| `campaign_id` | integer | Campaign ID | |
| `lead_id` | integer | Lead ID | |
| `phone` | string | Number being called | |
| `digit` | string | Key just pressed | `0`-`9`, `*`, `#` |
| `pressed_at` | datetime | DTMF receive time (ISO 8601 UTC) | |

### `autocall.call.transferred`

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID | |
| `campaign_id` | integer | Campaign ID | |
| `lead_id` | integer | Lead ID | |
| `transfer_target` | string | Transfer destination | `queue:<queue_name>` / `extension:<ext>` |
| `transferred_at` | datetime | Time the transfer succeeded (ISO 8601 UTC) | |

### `autocall.call.completed`

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID | |
| `campaign_id` | integer | Campaign ID | |
| `lead_id` | integer | Lead ID | |
| `phone` | string | Number that was called | |
| `attempt_number` | integer | Which attempt this is | >= 1 |
| `started_at` | datetime | Originate time (ISO 8601 UTC) | |
| `answered_at` | datetime\|null | Answer time (null if not answered) | |
| `ended_at` | datetime | Hangup time (ISO 8601 UTC) | |
| `duration_sec` | integer | Total call duration (seconds) | >= 0 |
| `result` | string | Outcome classification | `connected` / `no_answer` / `busy` / `failed` / `voicemail` / `dnc_blocked` |
| `hangup_cause` | string | Standard Q.850 hangup code from Zorio PBX | `NORMAL_CLEARING` / `NO_ANSWER` / `USER_BUSY` / `CALL_REJECTED` / ... |
| `dtmf_pressed` | string\|null | The last key the user pressed | |
| `final_action` | string\|null | Final action executed (per the DTMF script) | `queue:<name>` / `hangup` / `dnc_added` / null |

### `autocall.campaign.completed`

| Field | Type | Description | Valid values |
|---|---|---|---|
| `campaign_id` | integer | ID of the campaign that just finished | |
| `campaign_name` | string | Campaign name | |
| `total_leads` | integer | Total leads in the campaign | >= 0 |
| `total_connected` | integer | Leads that answered successfully | >= 0 |
| `completed_at` | datetime | Campaign completion time (ISO 8601 UTC) | |

### `autocall.tts.render_failed`

| Field | Type | Description | Valid values |
|---|---|---|---|
| `lead_id` | integer | ID of the skipped lead | |
| `campaign_id` | integer | Campaign ID | |
| `provider` | string | TTS provider that errored | `tts_provider_01` / `tts_provider_02` / `tts_provider_03` / `local` |
| `error_code` | string | Error code | `RATE_LIMIT` / `INVALID_VOICE` / `QUOTA_EXCEEDED` / `UNKNOWN` |
| `error_message` | string | Error description | |
| `failed_at` | datetime | TTS failure time (ISO 8601 UTC) | |

## Configuring webhooks (via Admin Console, NOT the Public API)

::: warning Webhooks are NOT registered via API
Per Zorio's security policy, webhook configuration is done manually through the **Admin Console**. The Public API only serves AutoCall business operations (campaign / lead / call lifecycle / reports).
:::

**Why**:
- Prevents abuse: if clients could self-register, a leaked token could redirect webhooks outside the account.
- Ensures auditability: every webhook config change is logged in admin activity.
- Separation of business vs config: the public API stays focused on call data.

**Onboarding workflow**:

1. **Contact your system administrator** (within your organization) or the Zorio support team.
2. Provide:
   - The webhook endpoint URL (HTTPS)
   - The list of events to subscribe to (see [Events](#events))
   - Optional: an IP allowlist for your infrastructure
3. The system administrator configures it in the Admin Console + selects the events → **saves**.
4. The system generates a **secret** (32 bytes, base64) → delivered to you over a secure channel.
5. You deploy the webhook receiver + use the secret to verify the HMAC signature (see [Headers](#headers)).

**Changing the configuration** (changing URL, adding events, rotating the secret) is also done through the Admin Console, not via the API.

## Sample delivery payload (event `autocall.call.completed`)

```json
{
  "event": "autocall.call.completed",
  "timestamp": "2026-06-24T08:32:47Z",
  "tenant_id": 1,
  "data": {
    "uuid": "093e1024-...",
    "campaign_id": 36,
    "lead_id": 78912,
    "phone": "84912345678",
    "attempt_number": 1,
    "started_at": "2026-06-24T08:32:00Z",
    "answered_at": "2026-06-24T08:32:05Z",
    "ended_at": "2026-06-24T08:32:47Z",
    "duration_sec": 42,
    "result": "connected",
    "hangup_cause": "NORMAL_CLEARING",
    "dtmf_pressed": "2",
    "final_action": "queue:support_queue"
  }
}
```

## Headers Zorio POSTs to your URL

| Header | Type | Description | Value |
|---|---|---|---|
| `X-Zorio-Signature` | string | HMAC-SHA256 of the raw body using the webhook secret | `sha256=<hex>` |
| `X-Zorio-Timestamp` | integer | Epoch seconds (UTC) — clients should reject if skew > 300s | |
| `X-Zorio-Event` | string | Convenience copy of the `event` field | `autocall.<entity>.<action>` |
| `X-Zorio-Delivery` | string | Delivery UUID — used for dedup on retry | UUID v4 |
| `Content-Type` | string | Content type | `application/json; charset=utf-8` |

::: tip Verify HMAC
Pseudo-code:
```
expected = "sha256=" + hex(hmac_sha256(secret, raw_request_body))
if expected != header["X-Zorio-Signature"]: reject
```
Do NOT verify against the parsed JSON — you must use the **raw body bytes**.
:::

## Retry policy

- 3 retries: 5s, 30s, 5 minutes
- After 3 failures → dead-lettered (admins view via the Admin Console)
- HTTP 2xx = success. 4xx/5xx = failure.

::: warning Client-side idempotency
The client MUST ensure the endpoint is idempotent (check the `X-Zorio-Delivery` UUID) because the webhook may be resent if HTTP timed out on Zorio's side after the client already executed it.
:::


---

# Call Detail Records (CDR)

<!-- source: https://docs.zorio.vn/en/api/pbx/cdr.md -->

# Call Detail Records (CDR)

Query CDRs with multiple filters and download recordings via signed URLs.

## GET `/api/pbx/cdr` — List

### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `from` | date | optional | Start date (YYYY-MM-DD) | If omitted → `now() - 30 days` |
| `to` | date | optional | End date (YYYY-MM-DD) | Must be ≥ `from`. If omitted → `now()` |
| `direction` | string | optional | Call direction | `inbound`, `outbound`, `internal`, `local` |
| `extension` | string | optional | Filter by extension (matches `extension_number` or `agent_extension`) | 3-20 chars |
| `phone` | string | optional | Filter by phone number (matches `caller_number` or `destination_number`) | max 50 chars |
| `page` | integer | optional | Page number | ≥ 1 |
| `per_page` | integer | optional | Records per page | 1-200 (default 50) |

::: warning Time-window limit
The `from..to` window is capped at **30 days** (configurable per account through `per-customer configuration limits`). Exceeding returns HTTP 422.
:::

### Response body fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID (Zorio PBX `call_uuid`) | 36-char UUID |
| `direction` | string | Call direction | `inbound` / `outbound` / `internal` / `local` |
| `source_type` | string | Call source | `inbound` / `outbound_manual` / `outbound_telesales` / `outbound_callback` / `outbound_webphone` / `internal` |
| `caller_number` | string | Originating number (caller ID) | |
| `destination_number` | string | Destination number | |
| `extension_number` | string\|null | Associated extension (caller or destination) | |
| `agent_extension` | string\|null | Agent extension that answered (for queue/IVR calls) | |
| `start_time` | datetime | When the call started | ISO 8601 |
| `answer_time` | datetime\|null | When the call was answered | ISO 8601 (null if never answered) |
| `end_time` | datetime | When the call ended | ISO 8601 |
| `duration` | integer | Total duration (seconds) | ≥ 0 |
| `billsec` | integer | Billable time (after pickup, seconds) | ≥ 0 |
| `queue_name` | string\|null | Queue name (if the call went through a queue) | |
| `queue_wait_time` | integer\|null | Time waited in queue (seconds) | |
| `trunk_name` | string\|null | Outbound trunk name (for outbound calls) | |
| `transfer_count` | integer | Number of transfers | ≥ 0 |
| `result` | string | Call outcome | `answered` / `busy` / `no_answer` / `failed` / `cancelled` / `rejected` / `voicemail` |
| `hangup_cause` | string | Hangup code from Zorio PBX | e.g. `NORMAL_CLEARING`, `NO_ANSWER`, `USER_BUSY`, `CALL_REJECTED`, ... |
| `sip_response_code` | string\|null | Final SIP response code (for outbound) | e.g. `200`, `486`, `487` |
| `recording_available` | bool | Whether a recording exists | `true` / `false` |
| `created_at` | datetime | CDR row creation timestamp | |

### Response Body (JSON) — 200

```json
{
  "current_page": 1,
  "data": [
    {
      "uuid": "65569ce0-0183-4f61-a3b2-0e433cfa4031",
      "direction": "outbound",
      "source_type": "outbound_telesales",
      "caller_number": "0900000021",
      "destination_number": "0987654321",
      "extension_number": "0900000021",
      "agent_extension": null,
      "start_time": "2026-06-27T08:15:42+00:00",
      "answer_time": "2026-06-27T08:15:42+00:00",
      "end_time": "2026-06-27T08:15:56+00:00",
      "duration": 14,
      "billsec": 14,
      "queue_name": null,
      "queue_wait_time": null,
      "trunk_name": null,
      "transfer_count": 0,
      "result": "answered",
      "hangup_cause": "NORMAL_CLEARING",
      "sip_response_code": null,
      "recording_available": true,
      "created_at": "2026-06-27 08:15:56"
    }
  ],
  "last_page": 5,
  "per_page": 20,
  "total": 87
}
```

## GET `/api/pbx/cdr/{uuid}` — Detail + signed recording URL

### Path parameter

`uuid` (string, Zorio PBX `call_uuid`).

Response = the 22 fields from the list + a `recording` object (if a recording exists).

### `recording` object fields

| Field | Type | Description |
|---|---|---|
| `duration` | integer | Recording length (seconds) |
| `file_size` | integer | File size (bytes) |
| `recorded_at` | datetime | When recording started (ISO 8601) |
| `url` | string | HMAC-signed URL to download the `.wav` — valid only within `expires_in_seconds` |
| `expires_in_seconds` | integer | URL TTL (default 1800 = 30 minutes) |

### Response Body (JSON) — 200

```json
{
  "data": {
    "uuid": "65569ce0-...",
    "direction": "outbound",
    "recording_available": true,
    "recording": {
      "duration": 14,
      "file_size": 56265,
      "recorded_at": "2026-06-27T08:15:57+00:00",
      "url": "https://app.zorio.vn/api/public/recordings/401/audio?expires=1782706011&signature=de93e86...",
      "expires_in_seconds": 1800
    }
  }
}
```

## GET `/api/pbx/cdr/{uuid}/recording` — 302 redirect to signed URL

### Path parameter

`uuid` (CDR `Unique-ID`).

### Response

HTTP 302 with header `Location: <signed URL>`. The client follows the redirect to download the `.wav` file. Signed URL TTL: **30 minutes** (HMAC SHA256).


---

# Click-to-Call

<!-- source: https://docs.zorio.vn/en/api/pbx/click-to-call.md -->

# Click-to-Call

Originate a two-leg call from the API: A-leg dials the agent extension → on pickup → B-leg dials the customer number → bridge.

## POST `/api/pbx/calls/click-to-call`

### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `from_extension` | string | ✅ | Agent extension (A-leg) | Must exist + `status=active`. Regex `^[0-9]{3,10}$` |
| `to_phone` | string | ✅ | Destination number (B-leg) | Regex `^[0-9+]+$`, 3-32 chars |
| `caller_id` | string | optional | Number to present when dialing out | Falls back to `extension.outbound_caller_id` or `from_extension`. Ideally pick a value from `/api/pbx/caller-ids` |
| `trunk_id` | integer | optional | Outbound trunk ID (takes priority over `trunk_name`) | Must exist + status=active. If omitted → falls back to the default dialplan (Zorio PBX picks a trunk via LCR/number-pool) |
| `trunk_name` | string | optional | Trunk name alternative to `trunk_id` | max 100 chars |
| `headers` | object | optional | Custom SIP headers — Zorio prefixes them with `X-` and attaches to the B-leg INVITE | Key regex `[A-Za-z0-9_-]`, value max 200 chars |

### Request Body (JSON) — Mode 1: auto routing (no trunk)

```json
{
  "from_extension": "1001",
  "to_phone": "0987654321"
}
```

### Request Body (JSON) — Mode 2: force trunk + caller-id + CRM tracking header

```json
{
  "from_extension": "1001",
  "to_phone": "0987654321",
  "caller_id": "0900000020",
  "trunk_id": 4,
  "headers": { "CRM-Lead-Id": "LEAD-42" }
}
```

### Response body fields — 202 (Accepted, call enqueued)

| Field | Type | Description |
|---|---|---|
| `call_uuid` | string | Logical UUID of the call (the CRM uses it to track across webhook events) |
| `a_leg_uuid` | string | A-leg UUID (channel to the agent extension) |
| `b_leg_uuid` | string | B-leg UUID (channel to the customer number) |
| `from_extension` | string | Echoed from the request |
| `to_phone` | string | Echoed from the request |
| `caller_id` | string | The caller ID that was actually resolved |
| `trunk_id` | integer\|null | Trunk ID chosen (null if the default dialplan was used) |
| `trunk_name` | string\|null | Trunk name chosen (null if the default dialplan was used) |
| `routing_mode` | string | `direct_gateway` (a trunk was chosen) or `dialplan_default` (default dialplan routing) |
| `status` | string | `queued` (not yet connected). The CRM then tracks progress via webhooks `pbx.call.ringing` / `pbx.call.answered` / `pbx.call.hangup` |

### Response Body (JSON) — 202

```json
{
  "data": {
    "call_uuid": "1ac30fff-0968-452f-9a9f-56c21fc8fe3f",
    "a_leg_uuid": "fc22be63-271d-4842-859d-0ebba9f13c8a",
    "b_leg_uuid": "64486cf6-0577-46a4-81e9-23ca31f46249",
    "from_extension": "1001",
    "to_phone": "0987654321",
    "caller_id": "1001",
    "trunk_id": 4,
    "trunk_name": "POC",
    "routing_mode": "direct_gateway",
    "status": "queued"
  }
}
```

::: warning Rate limit
**10 req / minute / token** (this group only — guards against spam-call abuse).
:::

## How it works

A-leg dials the agent extension → on pickup → B-leg dials the customer number → bridge. The customer CRM first receives `pbx.call.answered` for the A-leg, then `pbx.call.answered` for the B-leg.

```
1. Client calls   POST /api/pbx/calls/click-to-call → 202 with call_uuid
2. Zorio          Webhook pbx.call.ringing → agent extension rings
3. Agent picks up Webhook pbx.call.answered (A-leg)
4. Zorio          Bridges by dialing the B-leg to the customer number
5. Customer picks up Webhook pbx.call.answered (B-leg)
6. Conversation in progress
7. Hangup         Webhook pbx.call.hangup + pbx.cdr.created
```


---

# Extensions

<!-- source: https://docs.zorio.vn/en/api/pbx/extensions.md -->

# Extensions

Manage SIP extensions on the PBX: list, create, update, delete, fetch available numbers, and rotate the SIP password.

## GET `/api/pbx/extensions` — List

### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `search` | string | optional | Match against `extension_number` or `display_name` (LIKE) | |
| `status` | string | optional | Filter by admin status | `active`, `disabled` |
| `page` | integer | optional | Page number | ≥ 1 (default 1) |
| `per_page` | integer | optional | Records per page | 1-200 (default 50) |

### Response fields (each item in `data[]`)

| Field | Type | Description | Values |
|---|---|---|---|
| `extension_number` | string | Extension number — SIP register name | 3-10 digits |
| `display_name` | string\|null | Display name (caller ID name for internal calls) | max 100 chars |
| `voicemail_enabled` | bool | Whether voicemail is enabled | `true` / `false` |
| `outbound_caller_id` | string\|null | Default outbound caller ID | Must exist in `/caller-ids` |
| `recording_mode` | string | Recording mode | `none`, `inbound`, `outbound`, `all` |
| `status` | string | Admin configuration status | `active`, `disabled` |
| `team_id` | integer\|null | Team ID | |
| `department_id` | integer\|null | Department ID | |
| `max_concurrent` | integer | Maximum concurrent calls | 1-10 |
| `tls_enabled` | bool | Whether SIPS/TLS is enabled | `true` / `false` |
| `created_at` | datetime | Creation timestamp (ISO 8601 + offset) | |
| `updated_at` | datetime | Last update timestamp | |

### Response Body (JSON) — 200

```json
{
  "current_page": 1,
  "data": [
    {
      "extension_number": "1001",
      "display_name": "Mac I5",
      "voicemail_enabled": true,
      "outbound_caller_id": null,
      "recording_mode": "all",
      "status": "active",
      "team_id": 2,
      "department_id": null,
      "max_concurrent": 2,
      "tls_enabled": false,
      "created_at": "2026-04-06T12:19:13+00:00",
      "updated_at": "2026-06-18T11:01:47+00:00"
    }
  ],
  "last_page": 2,
  "per_page": 10,
  "total": 17
}
```

## GET `/api/pbx/extensions/{ext}` — Detail

### Path parameter

| Field | Type | Description |
|---|---|---|
| `ext` | string | `extension_number` (NOT `id`) |

Response = the 12 fields from the list + one extra realtime field `sip_registration`.

### Response Body (JSON) — 200

```json
{
  "data": {
    "extension_number": "1001",
    "display_name": "Mac I5",
    "voicemail_enabled": true,
    "outbound_caller_id": null,
    "recording_mode": "all",
    "status": "active",
    "team_id": 2,
    "department_id": null,
    "max_concurrent": 2,
    "tls_enabled": false,
    "created_at": "2026-04-06T12:19:13+00:00",
    "updated_at": "2026-06-18T11:01:47+00:00",
    "sip_registration": "registered"
  }
}
```

| Field | Type | Description | Valid values |
|---|---|---|---|
| `status` | string | Admin configuration | `active`, `disabled` |
| `sip_registration` | string | Realtime SIP registration status — the CRM uses this to know whether the softphone is online | `registered`, `unregistered`, `unknown` |

## POST `/api/pbx/extensions` — Create

### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `extension_number` | string | ✅ | Extension number — unique per account | Regex `^[0-9]{3,10}$` (3-10 digits) |
| `display_name` | string | optional | Display name | max 100 chars |
| `team_id` | integer | optional | Team ID | Must exist in `teams` |
| `sip_password` | string | optional | SIP register password — if omitted, a 24-character alphanumeric password is auto-generated | min 8, max 100 chars |
| `voicemail_enabled` | bool | optional | Enable voicemail | `true` / `false` (default `false`) |
| `voicemail_pin` | string | optional | Voicemail PIN | max 20 chars |
| `recording_mode` | string | optional | Recording mode | `none` / `inbound` / `outbound` / `all` (default `none`) |
| `max_concurrent` | integer | optional | Maximum concurrent calls | 1-10 (default 2) |
| `outbound_caller_id` | string | optional | Default outbound caller ID | Must exist in `/api/pbx/caller-ids` (active) |

### Request Body (JSON)

```json
{
  "extension_number": "9001",
  "display_name": "Sales 01",
  "voicemail_enabled": true,
  "recording_mode": "all",
  "max_concurrent": 2,
  "outbound_caller_id": "0900000020"
}
```

### Response body fields (12 fields from list + 2 extra fields on creation)

| Field | Type | Description |
|---|---|---|
| `sip_password` | string | SIP password — **returned only once**, copy into your softphone immediately |
| `generated_password` | bool | `true` if Zorio auto-generated, `false` if the client supplied it |

### Response Body (JSON) — 201

```json
{
  "data": {
    "extension_number": "9001",
    "display_name": "Sales 01",
    "voicemail_enabled": true,
    "recording_mode": "all",
    "status": "active",
    "max_concurrent": 2,
    "outbound_caller_id": "0900000020",
    "team_id": null,
    "department_id": null,
    "tls_enabled": false,
    "created_at": "2026-06-29T04:53:59+00:00",
    "updated_at": "2026-06-29T04:53:59+00:00",
    "sip_password": "<sip_password_shown_only_once>",
    "generated_password": true
  }
}
```

## PUT `/api/pbx/extensions/{ext}` — Update

### Request body fields (every field optional — send only what you want to change)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `display_name` | string\|null | Display name | max 100 chars |
| `team_id` | integer\|null | Team ID | |
| `voicemail_enabled` | bool | Enable voicemail | `true` / `false` |
| `voicemail_pin` | string\|null | Voicemail PIN | max 20 |
| `recording_mode` | string | Recording mode | `none` / `inbound` / `outbound` / `all` |
| `max_concurrent` | integer | Maximum concurrent calls | 1-10 |
| `outbound_caller_id` | string\|null | Outbound caller ID | Must exist in `/api/pbx/caller-ids` (active) |
| `status` | string | Configuration status | `active` / `disabled` |

::: tip Note
`extension_number` and `sip_password` cannot be changed through PUT. To rotate `sip_password`, use the `/change-password` endpoint.
:::

### Request Body (JSON)

```json
{
  "display_name": "Sales 01 (renamed)",
  "voicemail_enabled": false,
  "max_concurrent": 4,
  "recording_mode": "all",
  "outbound_caller_id": "0900000020"
}
```

### Response Body (JSON) — 200

```json
{
  "data": {
    "extension_number": "1001",
    "display_name": "Sales 01 (renamed)",
    "voicemail_enabled": false,
    "outbound_caller_id": "0900000020",
    "recording_mode": "all",
    "status": "active",
    "team_id": null,
    "department_id": null,
    "max_concurrent": 4,
    "tls_enabled": false,
    "created_at": "2026-04-06T12:19:13+00:00",
    "updated_at": "2026-06-29T07:55:12+00:00"
  }
}
```

## DELETE `/api/pbx/extensions/{ext}` — Delete

No request body.

### Response Body (JSON) — 200

```json
{
  "data": { "deleted": true }
}
```

Soft delete + flush FS directory cache.

## GET `/api/pbx/caller-ids` — List available numbers

Returns the outbound caller IDs with `status=active` for the customer — use this when picking `outbound_caller_id` for an extension or `caller_id` for a click-to-call.

### Query parameters

| Field | Type | Description | Values |
|---|---|---|---|
| `search` | string | Match `number` or `display_name` | |
| `page` | integer | Page number | ≥ 1 |
| `per_page` | integer | Records per page | 1-200 (default 50) |

### Response body fields

| Field | Type | Description | Values |
|---|---|---|---|
| `number` | string | Outbound number (E.164 or Vietnam domestic) | 8-15 digits |
| `display_name` | string\|null | Internal display name | |
| `carrier` | string | Telco | `viettel` / `mobifone` / `vinaphone` / `vietnamobile` / `landline` / `other` |
| `cli_type` | string | Number type | `mobile` / `fixed_02x` / `hotline_1900` / `hotline_1800` / `brandname` |
| `status` | string | Status | `active` (always, since the query filters this) |

### Response Body (JSON) — 200

```json
{
  "current_page": 1,
  "data": [
    { "number": "0900000020", "display_name": "POC", "carrier": "landline", "cli_type": "mobile", "status": "active" },
    { "number": "0900000021", "display_name": "POC", "carrier": "landline", "cli_type": "mobile", "status": "active" }
  ],
  "last_page": 1, "per_page": 50, "total": 7
}
```

When you POST/PUT an extension with an `outbound_caller_id` that is not in the list → **HTTP 422**:

```json
{ "errors": { "outbound_caller_id": ["The selected outbound caller id is invalid."] } }
```

## POST `/api/pbx/extensions/{ext}/change-password` — Rotate SIP password

### Request body fields

| Field | Type | Required | Description | Values |
|---|---|---|---|---|
| `new_password` | string | optional | New SIP password — if omitted, a 24-character alphanumeric password is auto-generated | min 8, max 100 |

### Request Body (JSON) — auto-generate (empty body)

```json
{}
```

### Request Body (JSON) — set password manually

```json
{
  "new_password": "MyNewStrongPwd123"
}
```

### Response body fields

| Field | Type | Description |
|---|---|---|
| `extension_number` | string | Extension number that was updated |
| `sip_password` | string | New password — returned only once |
| `generated_password` | bool | `true` if Zorio auto-generated, `false` if the client supplied it |

### Response Body (JSON) — 200

```json
{
  "data": {
    "extension_number": "1001",
    "sip_password": "AbC123...",
    "generated_password": true
  }
}
```


---

# PBX API — Overview

<!-- source: https://docs.zorio.vn/en/api/pbx/index.md -->

# PBX API — Overview

> Public REST API for the PBX Module (Extensions / CDR / Click-to-Call / Queue / Webhooks).
> **Authentication**: Bearer Token (user session). **Base URL**: provisioned per customer — see the [Base URL](#base-url) section.

## Scope

The PBX API lets a customer CRM:

- Manage SIP extensions: CRUD + change SIP password.
- Query call history (CDR) + download recordings.
- Trigger a two-leg Click-to-Call (agent → customer).
- Manage queues + agent tiers.
- Register webhooks to receive realtime events (`pbx.call.ringing` / `answered` / `hangup` / `cdr.created`).

## Glossary

| Term | Description |
|---|---|
| Extension | A SIP extension — registers to Zorio PBX using `extension_number` + `sip_password` |
| Account | Each customer has fully isolated data |
| CDR | Call Detail Record — one record per call (in/out/internal/local) |
| Click-to-Call | Originate a two-leg call from the API: A-leg dials the agent extension, B-leg dials the customer number |
| Queue | A queue — agents (Tier) answer based on a strategy (round-robin, longest-idle, ...) |
| Tier | Priority level within a queue (`tier_level` 1-9); `tier_position` orders agents within the same level |
| Webhook | An HTTPS URL where Zorio POSTs events to the customer CRM (`pbx.call.ringing` / `pbx.call.answered` / `pbx.call.hangup` / `pbx.cdr.created`) |
| HMAC | Header `X-Zorio-Signature: sha256=hex(hmac_sha256(secret, body))` for verification |
| Idempotency | Header `X-Zorio-Delivery: <UUID>` — clients use this to dedupe on retry |

## End-to-end workflow

```
1. Login                  POST /api/auth/login       → Bearer token
2. Create extension       POST /api/pbx/extensions   → returns sip_password once
3. Register webhook       Admin Console UI (NOT via API)
4. Click-to-call          POST /api/pbx/calls/click-to-call → 202 call_uuid
5. Receive events         Zorio POSTs to your URL: pbx.call.ringing → pbx.call.answered → pbx.call.hangup
6. Query CDR              GET  /api/pbx/cdr?from=&to=&extension=
7. Download recording     GET  /api/pbx/cdr/{uuid}/recording → 302 signed URL TTL 30 minutes
```

## Authentication

### Login

**Endpoint**: `POST /api/auth/login`

**Request Body** (JSON)

```json
{
  "username": "admin",
  "password": "<password>"
}
```

**Response Body** (JSON) — 200

```json
{
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "role": "admin",
      "tenant_id": 1
    }
  },
  "token": "1|abcdefghijklmnopqrstuvwxyz0123456789"
}
```

### Every request must include

```
Authorization: Bearer <token>
Accept: application/json
```

### Required permission

The user must have the `pbx_api_access` permission (built into the admin role).

## Endpoint groups

| Group | Documentation | Description |
|---|---|---|
| Extensions | [Go to page](/en/api/pbx/extensions) | CRUD + change SIP password + list available numbers |
| Call history (CDR) | [Go to page](/en/api/pbx/cdr) | Query CDR with filters + signed-URL recording download |
| Click-to-Call | [Go to page](/en/api/pbx/click-to-call) | Originate a two-leg call from the API |
| Queue | [Go to page](/en/api/pbx/queue) | CRUD queues + manage agent tiers |
| PBX webhook events | [Go to page](/en/api/pbx/webhooks) | Payload schema + HMAC verification + retry policy |

## Pagination & Response shape

### Pagination

Every list endpoint uses `?page=1&per_page=50` (max 200). Response:

```json
{
  "current_page": 1,
  "data": [],
  "last_page": 5,
  "per_page": 50,
  "total": 234
}
```

### Single resource / action

```json
{ "data": {} }
```

### Error

```json
{
  "message": "Short error description",
  "errors": { "field_name": ["Detailed description"] }
}
```

### Timezone

All datetimes are returned as ISO 8601 with offset (`+00:00` = UTC).

## Rate Limit

| Endpoint group | Limit |
|---|---|
| `/api/pbx/calls/click-to-call` | 10 req/min/token |
| `/api/pbx/*` (every other endpoint) | 60 req/min/token |

Exceeding the limit returns HTTP 429 with header `Retry-After: <seconds>`.

## HTTP Status Codes

| HTTP | When |
|---|---|
| 200 | OK |
| 201 | Created (new resource) |
| 202 | Accepted (click-to-call enqueued) |
| 401 | Token missing / invalid / expired — re-login |
| 403 | Token is valid but missing permission `pbx_api_access` |
| 404 | Resource does not exist within the token's account scope |
| 409 | Conflict (e.g. extension already in the queue) |
| 422 | Validation failure (see `errors` for field details) or business-rule violation |
| 429 | Rate limit hit |
| 500 | Server error (report to the Zorio team) |
| 502 | Click-to-call: Zorio PBX refused to originate |

## Base URL

| | URL |
|---|---|
| Production | `https://app.zorio.vn/api/pbx/` (provisioned per customer) |

## FAQ

**Q1: My webhook URL is temporarily blocked (e.g. CDN). How long does Zorio retry?**

A: 4 attempts, total ~36 minutes. After that the delivery moves to the deadletter queue — you must re-register the webhook after fixing the issue.

**Q2: Click-to-call failed — how do I distinguish "agent did not pick up" vs "customer did not answer"?**

A: After `pbx.call.hangup` fires, check `hangup_cause`:
- `NORMAL_CLEARING` + `billsec > 0`: both parties picked up; call succeeded.
- `NO_ANSWER`: one of the two parties did not pick up.
- `USER_BUSY`: the destination number was busy.

**Q3: I only want events for a specific extension, not the whole account.**

A: Webhook subscriptions are currently account-wide. Per-extension filtering is not yet supported.

**Q4: I need a test account before integrating with production.**

A: Contact Zorio to be provisioned a separate test account.


---

# Queue

<!-- source: https://docs.zorio.vn/en/api/pbx/queue.md -->

# Queue

Manage Zorio PBX queues: CRUD queues, add / update / remove agent tiers.

## GET `/api/pbx/queues` — List

**Query**: `search` (matches `name` or `queue_number`), `page`, `per_page` (1-200).

The response shape matches Extensions (5 keys: `current_page`, `data`, `last_page`, `per_page`, `total`).

## GET `/api/pbx/queues/{name}` — Detail

### Path parameter

`name` (user-facing string, NOT `id`).

### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `name` | string | User-facing queue name | unique per account |
| `queue_number` | string | Internal extension to dial into the queue | 3-10 digits |
| `team_id` | integer\|null | Owning team | |
| `strategy` | string | Agent-selection strategy | `ring-all` / `longest-idle-agent` / `round-robin` / `top-down` / `agent-with-least-talk-time` / `agent-with-fewest-calls` / `sequentially-by-agent-order` / `random` |
| `tier_rules_apply` | bool | Whether tier rules are applied | |
| `tier_rule_wait_second` | integer | Seconds to wait before escalating to the next tier | 0-3600 |
| `tier_rule_wait_multiply_level` | bool | Multiply wait seconds by the tier level | |
| `tier_rule_no_agent_no_wait` | bool | Skip waiting if no agent is online in the tier | |
| `abandoned_resume_allowed` | bool | Allow the caller to resume after hanging up | |
| `discard_abandoned_after` | integer | Seconds before discarding an abandoned record | |
| `max_wait_time_with_no_agent` | integer | Maximum wait while no agent is available (seconds) | ≥ 0 |
| `max_wait_time_with_no_agent_time_reached` | string | Action when the wait time expires | `hangup` / or another action name |
| `time_base_score` | string | Score by `system` (system-wide) or `queue` (within this queue only) | `system` / `queue` |
| `recording_template` | string\|null | Recording filename template (Zorio PBX variable interpolation) | |
| `status` | string | Status | `active` / `inactive` |
| `created_at` | datetime | | |
| `updated_at` | datetime | | |

### Response Body (JSON) — 200

```json
{
  "data": {
    "name": "Support01",
    "queue_number": "200",
    "team_id": 2,
    "strategy": "agent-with-fewest-calls",
    "tier_rules_apply": true,
    "tier_rule_wait_second": 15,
    "tier_rule_wait_multiply_level": true,
    "tier_rule_no_agent_no_wait": true,
    "abandoned_resume_allowed": false,
    "discard_abandoned_after": 14400,
    "max_wait_time_with_no_agent": 60,
    "max_wait_time_with_no_agent_time_reached": "hangup",
    "time_base_score": "queue",
    "recording_template": null,
    "status": "active"
  }
}
```

## POST `/api/pbx/queues` — Create

### Request body fields

| Field | Type | Required | Description | Values |
|---|---|---|---|---|
| `name` | string | ✅ | Queue name | max 100, unique per account |
| `queue_number` | string | ✅ | Number to dial into the queue | Regex `^[0-9]{3,10}$`, unique per account |
| `team_id` | integer | optional | Owning team | |
| `strategy` | string | optional | Agent-selection strategy | 8 enum values (see Detail) |
| `tier_rules_apply` | bool | optional | | |
| `tier_rule_wait_second` | integer | optional | | 0-3600 |
| `tier_rule_wait_multiply_level` | bool | optional | | |
| `tier_rule_no_agent_no_wait` | bool | optional | | |
| `abandoned_resume_allowed` | bool | optional | | |
| `discard_abandoned_after` | integer | optional | | ≥ 0 |
| `max_wait_time_with_no_agent` | integer | optional | | ≥ 0 |
| `max_wait_time_with_no_agent_time_reached` | string | optional | | |
| `time_base_score` | string | optional | | `system` / `queue` |

### Request Body (JSON)

```json
{
  "name": "Sales01",
  "queue_number": "300",
  "team_id": 2,
  "strategy": "agent-with-fewest-calls",
  "tier_rules_apply": true,
  "tier_rule_wait_second": 15,
  "tier_rule_no_agent_no_wait": true,
  "max_wait_time_with_no_agent": 60,
  "time_base_score": "queue"
}
```

### Response Body (JSON) — 201

```json
{
  "data": {
    "name": "Sales01",
    "queue_number": "300",
    "team_id": 2,
    "strategy": "agent-with-fewest-calls",
    "tier_rules_apply": true,
    "tier_rule_wait_second": 15,
    "tier_rule_wait_multiply_level": false,
    "tier_rule_no_agent_no_wait": true,
    "abandoned_resume_allowed": false,
    "discard_abandoned_after": 0,
    "max_wait_time_with_no_agent": 60,
    "max_wait_time_with_no_agent_time_reached": "hangup",
    "time_base_score": "queue",
    "recording_template": null,
    "status": "active"
  }
}
```

## PUT / DELETE `/api/pbx/queues/{name}`

### PUT

The body accepts every field from Create except `name` and `queue_number` (immutable).

```json
{
  "strategy": "longest-idle-agent",
  "tier_rule_wait_second": 20,
  "max_wait_time_with_no_agent": 90
}
```

Response 200 = `{ data: { ...17 queue fields } }`.

### DELETE

Soft delete + the observer detaches the queue at runtime.

```json
{ "data": { "deleted": true } }
```

## Tier-agent management

### GET `/api/pbx/queues/{name}/agents` — List tiers

#### Response body fields (each item in `data[]`)

| Field | Type | Description | Values |
|---|---|---|---|
| `extension_number` | string | Agent extension number | |
| `agent_name` | string | Agent name `<ext>@<sip-domain>` | |
| `status` | string | Agent presence status | `available` / `available_on_demand` / `on_break` / `logged_out` |
| `state` | string | Queue-runtime state | `idle` / `waiting` / `receiving` / `in_a_queue_call` |
| `tier_level` | integer | Priority level (1 = highest) | 1-9 |
| `tier_position` | integer | Order within the same level | 1-99 |
| `max_no_answer` | integer | Number of missed calls before auto-logout | |
| `wrap_up_time` | integer | Wrap-up time after each call (seconds) | |

```json
{
  "data": [
    {
      "extension_number": "2001",
      "agent_name": "2001@app.zorio.vn",
      "status": "available",
      "state": "idle",
      "tier_level": 1,
      "tier_position": 1,
      "max_no_answer": 3,
      "wrap_up_time": 5
    }
  ]
}
```

### POST `/api/pbx/queues/{name}/agents` — Add a tier

#### Request body fields

| Field | Type | Required | Description | Values |
|---|---|---|---|---|
| `extension` | string | ✅ | Extension number | Must exist. Regex `^[0-9]{3,10}$` |
| `tier_level` | integer | optional | Priority level | 1-9 (default 1) |
| `tier_position` | integer | optional | Position within the level | 1-99 (default 1) |

Automatically creates a tier-agent record if the agent does not exist. Returns 409 if the extension is already in this queue.

```json
{ "extension": "2001", "tier_level": 1, "tier_position": 1 }
```

Response 201: `{ "data": { "added": true } }`

### PATCH `/api/pbx/queues/{name}/agents/{ext}` — Update a tier

**Path**: `name` (queue), `ext` (extension_number).

#### Request body fields (every field optional)

| Field | Type | Description | Values |
|---|---|---|---|
| `tier_level` | integer | Priority level | 1-9 |
| `tier_position` | integer | Position within the level | 1-99 |
| `status` | string | Agent presence status | `available` / `available_on_demand` / `on_break` / `logged_out` |

```json
{ "tier_level": 2, "tier_position": 1, "status": "on_break" }
```

Response 200: `{ "data": { "updated": true } }`

### DELETE `/api/pbx/queues/{name}/agents/{ext}` — Remove a tier

No request body. Response 200: `{ "data": { "removed": true } }`

Does NOT delete the tier-agent record — only removes it from this queue (the agent can still belong to other queues).


---

# PBX Webhook Events

<!-- source: https://docs.zorio.vn/en/api/pbx/webhooks.md -->

# PBX Webhook Events

::: tip Webhook registration
Webhook subscriptions are a **per-customer configuration** — register / delete / rotate the secret through the **Admin UI** (`Admin Console`). The public API does not expose subscription CRUD.

This page documents the **payload schema** + **HMAC verification** so the customer CRM can process events itself.
:::

## Common envelope

Every event has the same envelope:

| Field | Type | Description |
|---|---|---|
| `event` | string | Event name (see below) |
| `timestamp` | datetime | When Zorio published the event (ISO 8601 UTC) |
| `data` | object | Event-specific payload |

## `pbx.call.ringing`

A call has arrived at an extension and the extension is ringing (not yet answered).

### `data` fields

| Field | Type | Description | Values |
|---|---|---|---|
| `call_uuid` | string | Call UUID | |
| `extension` | string | The extension that is ringing | |
| `direction` | string | Call direction | `inbound` / `outbound` / `internal` |
| `caller_number` | string | Originating number (caller ID) | |
| `destination_number` | string | Destination number (usually equals `extension`) | |
| `timestamp` | datetime | When ringing started | ISO 8601 |

### Sample payload

```json
{
  "event": "pbx.call.ringing",
  "timestamp": "2026-06-29T03:30:00Z",
  "data": {
    "call_uuid": "...",
    "extension": "1001",
    "direction": "inbound",
    "caller_number": "0987654321",
    "destination_number": "0900000020",
    "timestamp": "2026-06-29T03:30:00Z"
  }
}
```

## `pbx.call.answered`

The extension has picked up.

`data` fields = same as `pbx.call.ringing` plus:

| Field | Type | Description |
|---|---|---|
| `answered_at` | datetime | When the call was answered (ISO 8601) |

## `pbx.call.hangup`

The call has ended — fires immediately when Zorio PBX signals the end-of-call event.

### `data` fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `call_uuid` | string | Call UUID | |
| `extension` | string | Associated extension | |
| `direction` | string | Call direction | `inbound` / `outbound` / `internal` |
| `caller_number` | string | Caller ID | |
| `destination_number` | string | Destination number | |
| `started_at` | datetime\|null | When the call started | ISO 8601 |
| `answered_at` | datetime\|null | When the call was answered (null if never answered) | ISO 8601 |
| `ended_at` | datetime | When the call ended | ISO 8601 |
| `duration_sec` | integer | Total duration (seconds) | ≥ 0 |
| `billsec` | integer | Billable time (seconds) | ≥ 0 |
| `hangup_cause` | string | Q.850 hangup code from Zorio PBX | `NORMAL_CLEARING` / `NO_ANSWER` / `USER_BUSY` / `CALL_REJECTED` / `ORIGINATOR_CANCEL` / ... |
| `call_result` | string | Coarse classification | `answered` (billsec > 0) / `no_answer` (billsec = 0) |
| `recording_url` | string\|null | Recording download URL — `null` in the realtime event (sent immediately on hangup); populated in `pbx.cdr.created` after the recording pipeline finishes | |

### Sample payload

```json
{
  "event": "pbx.call.hangup",
  "timestamp": "2026-06-29T03:30:45Z",
  "data": {
    "call_uuid": "...",
    "extension": "1001",
    "direction": "inbound",
    "caller_number": "0987654321",
    "destination_number": "0900000020",
    "started_at": "2026-06-29T03:30:00Z",
    "answered_at": "2026-06-29T03:30:03Z",
    "ended_at": "2026-06-29T03:30:45Z",
    "duration_sec": 45,
    "billsec": 42,
    "hangup_cause": "NORMAL_CLEARING",
    "call_result": "answered",
    "recording_url": null
  }
}
```

## `pbx.cdr.created`

Fires AFTER the CDR pipeline inserts the row into the database — contains all fields from the processed A/B legs plus `recording_url`.

### `data` fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `call_uuid` | string | Call UUID (= the call UUID) | |
| `extension` | string\|null | Extension (`extension_number` preferred, otherwise `agent_extension`) | |
| `direction` | string | Direction | `inbound` / `outbound` / `internal` / `local` |
| `caller_number` | string | Caller ID | |
| `destination_number` | string | Destination number | |
| `started_at` | datetime\|null | When the call started | ISO 8601 |
| `answered_at` | datetime\|null | When the call was answered | ISO 8601 |
| `ended_at` | datetime\|null | When the call ended | ISO 8601 |
| `duration_sec` | integer | Total duration | ≥ 0 |
| `billsec` | integer | Billable time | ≥ 0 |
| `hangup_cause` | string | Hangup code | (same as `pbx.call.hangup`) |
| `result` | string | Full result classification | `answered` / `busy` / `no_answer` / `failed` / `cancelled` / `rejected` / `voicemail` |
| `recording_url` | string\|null | Internal URL pointing to the download endpoint (requires Bearer Token) | `https://app.zorio.vn/api/pbx/cdr/{uuid}/recording` or `null` |

### Differences vs `pbx.call.hangup`

- `pbx.call.hangup` fires directly from the realtime event — `result` is only coarse (answered / no_answer).
- `pbx.cdr.created` fires after the CDR pipeline has fully processed the call → `result` is more detailed and includes `recording_url`.

## Headers Zorio POSTs to your URL

| Header | Meaning |
|---|---|
| `X-Zorio-Event` | `pbx.call.hangup` |
| `X-Zorio-Timestamp` | Epoch seconds (UTC). The client should reject if skew is > 300s |
| `X-Zorio-Delivery` | Per-delivery UUID — use to dedupe on retry |
| `X-Zorio-Signature` | `sha256=<hex>` HMAC-SHA256(secret, raw_body) |
| `Content-Type` | `application/json; charset=utf-8` |

## Verifying HMAC on the client (Node.js sample)

```js
const crypto = require('crypto');

function verify(req, secret) {
  const ts = parseInt(req.headers['x-zorio-timestamp'], 10);
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const sig = req.headers['x-zorio-signature'];
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
```

## Retry policy

Zorio expects a 2xx response within **5 seconds**. If not:

- 2nd attempt: after 30 seconds
- 3rd attempt: after 5 minutes
- 4th attempt: after 30 minutes
- Maximum 4 attempts → marked `deadletter` in the webhook delivery log

The client should return 200 immediately on receipt and process asynchronously — avoid stacking retries.


---

# Caller-ID rotation groups

<!-- source: https://docs.zorio.vn/en/api/telesales/caller-id-groups.md -->

# Caller-ID rotation groups

::: tip Context
Outbound campaigns need to rotate across multiple caller IDs to avoid being marked as spam by carriers. The Zorio admin manages outbound numbers inside **rotation groups** through the admin UI; an integrator only needs to **read** the list of groups in order to assign them to a campaign (through the `caller_id_group_id` field when [creating a Campaign](/en/api/telesales/campaigns)).
:::

::: warning Read-only endpoints
Managing individual caller IDs, creating / updating / deleting groups (POST/PUT/DELETE), syncing members and clearing cooldowns all happen through the Zorio admin UI and are **not** exposed via the Integration API.
:::

## Endpoint summary

| Endpoint | Purpose |
|---|---|
| `GET /api/caller-id-groups` | List the customer's rotation groups |
| `GET /api/caller-id-groups/{id}` | Detail for one group + list of its caller-ID members |
| `GET /api/caller-id-groups/{id}/monitor` | Per-member runtime snapshot (eligibility, cooldown, health) — for monitoring dashboards |

## `GET /api/caller-id-groups` — list

### Query parameters

This endpoint only returns the groups owned by the customer (automatically scoped by authentication). No additional filters.

### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Rotation group ID | |
| `name` | string | Group name | max 150 chars |
| `description` | string\|null | Internal description | max 500 chars |
| `rotation_strategy` | string | Caller-ID selection strategy when dialing out | `round_robin` / `least_used` / `cap_based` / `weighted` / `sticky_lead` / `random` |
| `sticky_enabled` | bool | Whether the caller ID used for a lead is reused on subsequent calls | `true` / `false` |
| `status` | string | Group status — `disabled` groups are skipped by the engine | `active` / `disabled` |
| `caller_ids_count` | integer | Number of `active` caller-ID members | ≥ 0 |
| `created_at` | datetime | When the group was created (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "id":  3,
      "name": "Group A - Viettel Sales",
      "description": "Viettel outbound numbers for the summer campaign",
      "rotation_strategy": "round_robin",
      "sticky_enabled": true,
      "status": "active",
      "caller_ids_count": 12,
      "created_at": "2026-05-20T03:00:00Z"
    }
  ]
}
```

## `GET /api/caller-id-groups/{id}` — detail

### Path parameter

| Field | Type | Description |
|---|---|---|
| `id` | integer | Group ID (from the list above) |

### Response fields

Includes every field from the list plus a `caller_ids[]` array:

| Field | Type | Description | Valid values |
|---|---|---|---|
| `caller_ids[]` | array | List of caller-ID members | |
| `caller_ids[].id` | integer | Caller-ID record ID | |
| `caller_ids[].number` | string | Outbound phone number | E.164 or domestic |
| `caller_ids[].display_name` | string\|null | Internal display name | max 100 chars |
| `caller_ids[].carrier` | string | Telco | `viettel` / `mobifone` / `vinaphone` / `vietnamobile` / `landline` / `other` |
| `caller_ids[].carrier_label` | string | Carrier display label | |
| `caller_ids[].status` | string | Caller-ID status | `active` / `disabled` |
| `caller_ids[].trunk_name` | string\|null | SIP trunk bound to this caller ID | |
| `caller_ids[].weight` | integer | Weight when `rotation_strategy = weighted` | ≥ 1 (default 1) |

**Response 200**:
```json
{
  "data": {
    "id": 3,
    "name": "Group A - Viettel Sales",
    "description": "...",
    "rotation_strategy": "round_robin",
    "sticky_enabled": true,
    "status": "active",
    "caller_ids_count": 12,
    "created_at": "2026-05-20T03:00:00Z",
    "caller_ids": [
      {
        "id": 18,
        "number": "0900000010",
        "display_name": "Sales Line 1",
        "carrier": "viettel",
        "carrier_label": "Viettel",
        "status": "active",
        "trunk_name": "Trunk-Viettel-01",
        "weight": 2
      }
    ]
  }
}
```

## `GET /api/caller-id-groups/{id}/monitor` — runtime snapshot

For realtime monitoring dashboards — shows which caller IDs are currently eligible / in cooldown / over quota.

### Path parameter

| Field | Type | Description |
|---|---|---|
| `id` | integer | Group ID |

### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `group_id` | integer | Group ID | |
| `group_name` | string | Group name | |
| `total_members` | integer | Total caller-ID members | |
| `eligible_now` | integer | Caller IDs ready to be picked | |
| `in_cooldown` | integer | Caller IDs in temporary cooldown | |
| `disabled` | integer | Caller IDs disabled manually | |
| `members[]` | array | Per-caller-ID snapshot | |
| `members[].caller_id_id` | integer | Caller-ID ID | |
| `members[].number` | string | Phone number | |
| `members[].carrier` | string | Telco | `viettel` / `mobifone` / `vinaphone` / `vietnamobile` / `landline` / `other` |
| `members[].status` | string | Runtime status | `eligible` / `cooldown` / `disabled` / `quota_exceeded` |
| `members[].health_score` | integer | Health score — lower means more signs of carrier flagging | 0-100 |
| `members[].calls_today` | integer | Calls dialed today | ≥ 0 |
| `members[].daily_cap` | integer | Daily call cap | ≥ 1 |
| `members[].cooldown_until` | datetime\|null | When cooldown ends (null if not in cooldown) | ISO 8601 UTC |

**Response 200**:
```json
{
  "data": {
    "group_id": 3,
    "group_name": "Group A - Viettel Sales",
    "total_members": 12,
    "eligible_now": 9,
    "in_cooldown": 2,
    "disabled": 1,
    "members": [
      {
        "caller_id_id": 18,
        "number": "0900000010",
        "carrier": "viettel",
        "status": "eligible",
        "health_score": 82,
        "calls_today": 87,
        "daily_cap": 200,
        "cooldown_until": null
      },
      {
        "caller_id_id": 19,
        "number": "0900000011",
        "carrier": "mobifone",
        "status": "cooldown",
        "health_score": 14,
        "calls_today": 53,
        "daily_cap": 200,
        "cooldown_until": "2026-06-06T12:00:00Z"
      }
    ]
  }
}
```

**Response 404**: `{ "message": "Pool not found." }`.

## Assigning a group to a campaign

In the body when **[creating a Campaign](/en/api/telesales/campaigns)**, set `caller_id_group_id` to the `id` returned by `GET /api/caller-id-groups`:

```json
{
  "name": "Summer Promo",
  "caller_id_group_id": 3,
  ...
}
```

When the campaign transitions `draft → active` (`PUT /api/telesales/campaigns/{id}/status`), the `caller_id_group_id` field is **required** — missing it returns 422.


---

# Campaigns

<!-- source: https://docs.zorio.vn/en/api/telesales/campaigns.md -->

# Campaigns

This group covers outbound-campaign administration: creation, lifecycle control (launch/pause/resume/archive/clone), performance and time-series statistics, and managing the agents assigned to each campaign. The per-call lifecycle (initiate / status / hangup / disposition) is documented at the end of the page for partner integrations.

## 3.1 Create a campaign

```http
POST /api/telesales/campaigns
```

### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `name` | string | ✅ | Campaign name, unique within the account | max 150 chars |
| `description` | string | optional | Short description | max 500 chars |
| `dialer_mode` | string | ✅ | Dialer mode | `manual` / `preview` / `progressive` / `predictive` |
| `caller_id_group_id` | integer | ✅ | Caller-ID rotation group ID (see §Caller-ID rotation groups) | Must exist + `status=active` |
| `script_id` | integer | optional | ID of the call script assigned to the campaign | Must exist |
| `ring_timeout_sec` | integer | optional | Maximum ring time (seconds) | 5-120 (default 25) |
| `preview_window_sec` | integer | optional | Time the agent has to preview the lead when `dialer_mode=preview` | 0-60 (default 10) |
| `priority` | integer | optional | Priority — higher number = higher priority | 0-1000 (default 100) |
| `max_attempts` | integer | optional | Maximum retry attempts per lead | 1-20 (default 5) |
| `pdpl_enforce` | bool | optional | Enforce legal calling window (PDPL/TCPA) | `true` / `false` (default `true`) |
| `abandon_rate_limit_pct` | float | optional | Maximum abandon-rate threshold (% — predictive mode) | 0.0-10.0 (default 3.0) |
| `time_window` | object | optional | Allowed calling windows per day of week | Key: `mon`/`tue`/`wed`/`thu`/`fri`/`sat`/`sun` → array of `{from,to}` HH:MM |

**`dialer_mode` values**:
- `manual` — the agent dials each number themselves.
- `preview` — the system pushes the lead to the agent for preview, then dials.
- `progressive` — the system dials when an agent is free.
- `predictive` — the system dials before an agent is free (constrained by `abandon_rate_limit_pct`).

**Body**:
```json
{
  "name": "Outbound Sales Q3-2026",
  "description": "Q3 outbound campaign",
  "dialer_mode": "progressive",
  "caller_id_group_id": 3,
  "script_id": 12,
  "ring_timeout_sec": 25,
  "preview_window_sec": 10,
  "priority": 100,
  "max_attempts": 5,
  "pdpl_enforce": true,
  "abandon_rate_limit_pct": 3.0,
  "time_window": {
    "mon": [{"from": "08:00", "to": "17:30"}],
    "tue": [{"from": "08:00", "to": "17:30"}],
    "wed": [{"from": "08:00", "to": "17:30"}],
    "thu": [{"from": "08:00", "to": "17:30"}],
    "fri": [{"from": "08:00", "to": "17:30"}],
    "sat": [{"from": "08:00", "to": "12:00"}]
  }
}
```

### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Campaign ID | |
| `name` | string | Campaign name | |
| `description` | string\|null | Short description | |
| `status` | string | Lifecycle status | `draft` / `active` / `paused` / `archived` |
| `dialer_mode` | string | Dialer mode | `manual` / `preview` / `progressive` / `predictive` |
| `caller_id_group_id` | integer | Caller-ID rotation group ID | |
| `script_id` | integer\|null | Script ID | |
| `ring_timeout_sec` | integer | Maximum ring time | 5-120 |
| `preview_window_sec` | integer | Preview window | 0-60 |
| `priority` | integer | Priority | 0-1000 |
| `max_attempts` | integer | Maximum retry attempts | 1-20 |
| `pdpl_enforce` | bool | Enforce PDPL window | |
| `abandon_rate_limit_pct` | float | Abandon-rate threshold (predictive) | 0.0-10.0 |
| `time_window` | object | Calling window per day | |
| `total_leads` | integer | Number of leads imported into the campaign | |
| `created_by` | integer | User ID of the creator | |
| `created_at` | datetime | Creation timestamp (ISO 8601 UTC) | |
| `updated_at` | datetime | Last update timestamp | |

**Response 201**:
```json
{
  "data": {
    "id": 36,
    "name": "Outbound Sales Q3-2026",
    "description": "Q3 outbound campaign",
    "status": "draft",
    "dialer_mode": "progressive",
    "caller_id_group_id": 3,
    "script_id": 12,
    "ring_timeout_sec": 25,
    "preview_window_sec": 10,
    "priority": 100,
    "max_attempts": 5,
    "pdpl_enforce": true,
    "abandon_rate_limit_pct": 3.0,
    "time_window": { "mon": [{"from":"08:00","to":"17:30"}], "...": "..." },
    "total_leads": 0,
    "created_by": 7,
    "created_at": "2026-06-06T06:00:00Z",
    "updated_at": "2026-06-06T06:00:00Z"
  }
}
```

**Response 422** (validation failed):
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "dialer_mode": ["The selected dialer mode is invalid."],
    "caller_id_group_id": ["The selected caller id group id is invalid."]
  }
}
```

## 3.2 Campaign lifecycle control

| Endpoint | Action | Response |
|---|---|---|
| `POST /api/telesales/campaigns/{id}/launch` | draft → active | `{ "data": { "id":36, "status":"active", "launched_at":"...Z" } }` |
| `POST /api/telesales/campaigns/{id}/pause` | active → paused | `{ "data": { "id":36, "status":"paused" } }` |
| `POST /api/telesales/campaigns/{id}/resume` | paused → active | `{ "data": { "id":36, "status":"active" } }` |
| `POST /api/telesales/campaigns/{id}/archive` | → archived | `{ "data": { "id":36, "status":"archived" } }` |
| `POST /api/telesales/campaigns/{id}/clone` | → new draft | `{ "data": { "id":42, "status":"draft", "name":"... (clone)" } }` |
| `PUT  /api/telesales/campaigns/{id}` | Update fields | returns the full campaign object |
| `DELETE /api/telesales/campaigns/{id}` | Soft delete | `204 No Content` |

## 3.3 List / detail / statistics

### `GET /api/telesales/campaigns` — list

#### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `status` | string | optional | Filter by lifecycle status | `draft` / `active` / `paused` / `archived` |
| `dialer_mode` | string | optional | Filter by dialer mode | `manual` / `preview` / `progressive` / `predictive` |
| `q` | string | optional | Search by `name` (LIKE %keyword%) | |
| `page` | integer | optional | Page number | ≥ 1 (default 1) |
| `per_page` | integer | optional | Records per page | 1-200 (default 50) |

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Campaign ID | |
| `name` | string | Campaign name | |
| `status` | string | Lifecycle status | `draft` / `active` / `paused` / `archived` |
| `dialer_mode` | string | Dialer mode | `manual` / `preview` / `progressive` / `predictive` |
| `total_leads` | integer | Total leads imported | |
| `dialled` | integer | Total dial attempts | |
| `answered` | integer | Number of answered calls | |
| `converted` | integer | Number of successful conversions | |
| `asr_pct` | float | Answer-Seizure Ratio (%) = `answered/dialled*100` | 0-100 |

**Response 200**:
```json
{
  "data": [
    { "id": 36, "name": "Outbound Sales Q3-2026", "status": "active",
      "dialer_mode": "progressive", "total_leads": 487, "dialled": 312,
      "answered": 198, "converted": 47, "asr_pct": 63.5 }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }
}
```

### `GET /api/telesales/campaigns/{id}/stats` — aggregate statistics

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `dialled` | integer | Total dial attempts | |
| `answered` | integer | Total answered calls | |
| `talked_over_30s` | integer | Calls with `billsec ≥ 30` | |
| `converted` | integer | Converted calls (disposition `is_final=true` + successful outcome) | |
| `answer_rate_pct` | float | `answered/dialled*100` | 0-100 |
| `conversion_rate_pct` | float | `converted/answered*100` | 0-100 |
| `asr_pct` | float | Answer-Seizure Ratio (%) | 0-100 |
| `aht_seconds` | integer | Average Handle Time (seconds) — average per-call handling time | |
| `abandon_rate_pct` | float | Abandon rate (% — predictive mode only) | 0-100 |
| `callbacks_pending` | integer | Number of callbacks pending | |

**Response 200**:
```json
{
  "data": {
    "dialled": 312,
    "answered": 198,
    "talked_over_30s": 142,
    "converted": 47,
    "answer_rate_pct": 63.46,
    "conversion_rate_pct": 15.06,
    "asr_pct": 63.46,
    "aht_seconds": 184,
    "abandon_rate_pct": 1.8,
    "callbacks_pending": 23
  }
}
```

### `GET /api/telesales/campaigns/{id}/timeseries` — time series

#### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `group_by` | string | optional | Grouping unit | `hour` / `day` / `week` (default `day`) |
| `date_from` | datetime | optional | Start timestamp (UTC ISO 8601) | |
| `date_to` | datetime | optional | End timestamp (UTC ISO 8601) | |

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `bucket` | string | Time bucket — formatted by `group_by` | `YYYY-MM-DD` / `YYYY-Www` / `YYYY-MM-DD HH:00:00` |
| `dialled` | integer | Dial attempts in this bucket | |
| `answered` | integer | Answered calls in this bucket | |
| `converted` | integer | Converted calls in this bucket | |

**Response 200**:
```json
{
  "data": [
    { "bucket": "2026-06-01", "dialled": 80, "answered": 51, "converted": 12 },
    { "bucket": "2026-06-02", "dialled": 92, "answered": 60, "converted": 15 },
    { "bucket": "2026-06-03", "dialled": 75, "answered": 47, "converted":  9 }
  ],
  "meta": { "range": "7d" }
}
```

## 3.4 Managing agents in a campaign

| Endpoint | Purpose |
|---|---|
| `GET    /api/telesales/campaigns/{id}/agents` | List the agents currently assigned to the campaign |
| `GET    /api/telesales/campaigns/{id}/agents/available` | List users eligible to be assigned (not conflicting with another campaign, appropriate role) |
| `POST   /api/telesales/campaigns/{id}/agents` | Assign an agent to the campaign |
| `PATCH  /api/telesales/campaigns/{id}/agents/{userId}` | Update an agent's role or status |
| `DELETE /api/telesales/campaigns/{id}/agents/{userId}` | Remove an agent from the campaign |

### `GET /api/telesales/agents` — list the customer's agents

Integrators use this to pick a `user_id` for `POST /api/telesales/campaigns/{id}/agents`:

```http
GET /api/telesales/agents?per_page=50&page=1
```

#### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `q` | string | optional | Search by `name` / `username` / `email` (LIKE %keyword%) | |
| `role` | string | optional | Filter by role | `agent` / `supervisor` / `manager` / ... |
| `team_id` | integer | optional | Filter by team | |
| `page` | integer | optional | Page number | ≥ 1 (default 1) |
| `per_page` | integer | optional | Records per page | 1-200 (default 50) |

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | User ID | |
| `name` | string | Full name | |
| `username` | string | Login name | |
| `email` | string | Email | |
| `role` | string | System role | `agent` / `supervisor` / `manager` |
| `team_id` | integer\|null | Team ID the user belongs to | |
| `extension` | string\|null | Assigned SIP extension | |
| `is_active` | bool | Whether the user is still active | `true` / `false` |

**Response 200**:
```json
{
  "data": [
    {
      "id": 25,
      "name": "Nguyen Van A",
      "username": "nguyenvana",
      "email": "nguyenvana@company.com",
      "role": "agent",
      "team_id": 3,
      "extension": "1001",
      "is_active": true
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 50, "total": 142 }
}
```

Only returns users with `is_active=true`, sorted by `name`.

**Workflow to assign an agent to a campaign**:
```http
# Step 1: list available agents
GET /api/telesales/agents?role=agent

# Step 2: assign user_id=25 to the campaign
POST /api/telesales/campaigns/36/agents
{ "user_id": 25, "role": "agent" }
```

### `GET /api/telesales/campaigns/{id}/agents`

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `user_id` | integer | Agent user ID | |
| `username` | string | Login name | |
| `display_name` | string | Display name | |
| `campaign_id` | integer | Campaign ID | |
| `role` | string | Role in the campaign | `agent` / `supervisor` |
| `extension` | string\|null | SIP extension | |
| `team_id` | integer\|null | Team ID | |
| `team_name` | string\|null | Team name | |
| `is_active` | bool | Whether the user is still active | `true` / `false` |
| `assigned_at` | datetime | When the agent was assigned (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "user_id": 25,
      "username": "agent01",
      "display_name": "Nguyen Van A",
      "campaign_id": 36,
      "role": "agent",
      "extension": "2001",
      "team_id": 3,
      "team_name": "Sales A",
      "is_active": true,
      "assigned_at": "2026-06-06T06:10:00Z"
    }
  ]
}
```

### `GET /api/telesales/campaigns/{id}/agents/available`

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `user_id` | integer | User ID eligible for assignment | |
| `username` | string | Login name | |
| `display_name` | string | Display name | |
| `extension` | string\|null | SIP extension | |
| `team_id` | integer\|null | Team ID | |
| `team_name` | string\|null | Team name | |
| `role` | string | System role | `agent` / `supervisor` |
| `is_active` | bool | Whether the user is still active | `true` / `false` |

**Response 200**:
```json
{
  "data": [
    {
      "user_id": 30,
      "username": "agent06",
      "display_name": "Tran Thi B",
      "extension": "2006",
      "team_id": 3,
      "team_name": "Sales A",
      "role": "agent",
      "is_active": true
    }
  ]
}
```

### `POST /api/telesales/campaigns/{id}/agents` — assign an agent

#### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `user_id` | integer | ✅ | User ID to assign | Must exist + `is_active=true` + have a SIP extension |
| `role` | string | optional | Role in the campaign | `agent` (default) / `supervisor` |

**Body**:
```json
{ "user_id": 25, "role": "agent" }
```

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `user_id` | integer | The user ID just assigned | |
| `campaign_id` | integer | Campaign ID | |
| `role` | string | Role in the campaign | `agent` / `supervisor` |
| `assigned_at` | datetime | When the assignment happened (ISO 8601 UTC) | |

**Response 201**:
```json
{
  "data": {
    "user_id": 25,
    "campaign_id": 36,
    "role": "agent",
    "assigned_at": "2026-06-06T06:10:00Z"
  }
}
```

**Response 422 — validation / conflict cases**:

```json
// User does not exist or is inactive
{
  "message": "The given data was invalid.",
  "errors": { "user_id": ["The selected user id is invalid."] }
}

// User is already assigned to another campaign (a user can only belong to one campaign at a time)
{
  "message": "Agent is already attached to another active campaign.",
  "errors": { "user_id": ["User 25 already assigned to campaign 38."] }
}

// User has no SIP extension (cannot receive calls)
{
  "message": "User has no SIP extension assigned — cannot be assigned as an agent.",
  "errors": { "user_id": ["User 25 has no extension assigned."] }
}

// Invalid role (only agent / supervisor are accepted)
{
  "message": "The given data was invalid.",
  "errors": { "role": ["The selected role is invalid."] }
}
```

### `PATCH /api/telesales/campaigns/{id}/agents/{userId}` — update role

#### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `role` | string | ✅ | New role in the campaign | `agent` / `supervisor` |

**Body**:
```json
{ "role": "supervisor" }
```

**Response 200**:
```json
{ "data": { "user_id": 25, "campaign_id": 36, "role": "supervisor", "assigned_at": "2026-06-06T06:10:00Z" } }
```

**Response 404** — the agent is not assigned to this campaign:
```json
{ "message": "Agent is not attached to this campaign." }
```

### `DELETE /api/telesales/campaigns/{id}/agents/{userId}`

**Response 204 No Content** (success).

**Response 422 — agent is currently on a call**:
```json
{
  "message": "Cannot unassign an agent who is currently on a call.",
  "errors": { "user_id": ["Agent 25 is currently on call UUID xxx — wait for it to end or force-hangup first."] }
}
```

::: tip Note
After a successful `DELETE`, the agent will no longer receive new calls from the campaign, but any in-flight call will run to completion. Realtime presence state syncs within 5 seconds.
:::

---

## 7. Call Lifecycle

Each call goes through four main steps initiated by the agent (or the system) within a campaign.

::: tip Tip
If you use the Webphone SDK, all four steps are bundled into `phone.call(number, options)` — you do not need to call the endpoints below directly. See the Webphone SDK docs.
:::

### 7.1 Initiate a call
```http
POST /api/telesales/calls/initiate
```

The agent's extension is taken from the authenticated user's profile — no need to pass it manually.

#### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `campaign_id` | integer | ✅ | ID of the campaign the agent is running | Must exist + `status=active` + agent assigned |
| `lead_id` | integer | ✅ | ID of the lead to dial | Must belong to `campaign_id` + `status` not in `dnc`/`exhausted`/`converted` |

**Body**:
```json
{
  "campaign_id": 36,
  "lead_id": 78912
}
```

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID — used by every sub-endpoint (`/status`, `/hangup`, `/disposition`) | UUID v4 |
| `status` | string | Initial state | `originating` |
| `caller_id_used` | string | Outbound caller ID picked by the rotation group | E.164 |
| `lead_id` | integer | Lead ID | |
| `campaign_id` | integer | Campaign ID | |

**Response 200**:
```json
{
  "uuid": "093e1024-82c6-49b3-8775-99edeb221898",
  "status": "originating",
  "caller_id_used": "0900000010",
  "lead_id": 78912,
  "campaign_id": 36
}
```

**Response 422** (PDPL window violation):
```json
{
  "error": "pdpl_blocked",
  "message": "Outside the campaign calling window (08:00-17:30, Mon-Sat).",
  "next_eligible_at": "2026-06-07T01:00:00Z"
}
```

**Response 422** (other reasons):
```json
{
  "error": "lead_dnc",
  "message": "Lead phone is on the DNC list."
}
```
Other error codes: `lead_blocked`, `no_caller_id_available`, `max_attempts_reached`.

### 7.2 Track call status
```http
GET /api/telesales/calls/{uuid}/status
```

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID | UUID v4 |
| `state` | string | Current state | `originating` / `ringing` / `answered` / `wrap_up` / `closed` |
| `start_time` | datetime | When the call was initiated (ISO 8601 UTC) | |
| `answer_time` | datetime\|null | When the customer answered | `null` if not yet answered |
| `end_time` | datetime\|null | When the call ended | `null` if still running |
| `duration` | integer\|null | Total time from originate to hangup (seconds) | |
| `billsec` | integer\|null | Talk time (seconds) — from `answer_time` to `end_time` | |
| `result` | string\|null | Final result — derived from the hangup cause | `answered` / `no_answer` / `busy` / `failed` / `cancelled` |
| `hangup_cause` | string\|null | Hangup reason from Zorio PBX | e.g. `NORMAL_CLEARING` / `USER_BUSY` |
| `caller_id_used` | string | Outbound number used | E.164 |
| `agent_extension` | string | Agent's SIP extension | |
| `destination_number` | string | Destination phone (lead) | |

### 7.3 Manual hangup

```http
POST /api/telesales/calls/{uuid}/hangup
```

#### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `cause` | string | optional | Custom hangup reason — stored in CDR for reporting | free text, max 64 chars (default `MANUAL_HANGUP`) |

**Body** (optional):
```json
{ "cause": "MANUAL_HANGUP" }
```

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID | UUID v4 |
| `state` | string | State after hangup | `wrap_up` (waiting for the agent to dispose the call) |
| `end_time` | datetime | When hangup happened (ISO 8601 UTC) | |
| `duration` | integer | Total call duration (seconds) | |
| `billsec` | integer | Talk time (seconds) | |
| `hangup_cause` | string | Hangup cause (echoed from request or auto-generated) | |

**Response 200**:
```json
{
  "data": {
    "uuid": "093e1024-82c6-49b3-8775-99edeb221898",
    "state": "wrap_up",
    "end_time": "2026-06-06T06:35:42Z",
    "duration": 222,
    "billsec": 213,
    "hangup_cause": "MANUAL_HANGUP"
  }
}
```

**Response 404** — UUID does not exist or does not belong to the account:
```json
{ "message": "Call not found." }
```

**Response 422** — the call has already ended:
```json
{
  "message": "Call has already ended, hangup is not possible.",
  "errors": { "uuid": ["Call already in state 'closed' since 2026-06-06T06:34:00Z."] }
}
```

**Response 403** — an ordinary agent tries to hang up someone else's call without supervisor privilege:
```json
{ "message": "You are not allowed to hang up this call. Supervisor role is required to force hangup." }
```

### 7.4 Submit disposition
```http
POST /api/telesales/calls/{uuid}/disposition
```

#### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `disposition_id` | integer | ✅ | Disposition ID (mapped from `code`, e.g. `SALE-OK`) | Must exist + `is_active=true` |
| `note` | string | optional | Agent's free-text note | max 1000 chars |
| `callback_at` | datetime | optional | Callback schedule (ISO 8601 UTC) — only when the disposition has `trigger_callback=true` | Must be in the future |
| `callback_agent_id` | integer | optional | Sticky agent for the callback | User ID; must be an agent of the campaign |

**Body**:
```json
{
  "disposition_id": 5,
  "note": "Customer committed, follow-up email scheduled",
  "callback_at": null,
  "callback_agent_id": null
}
```

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID | UUID v4 |
| `state` | string | State after disposition | `closed` |
| `disposition` | object | Details of the applied disposition | `{id, code, label, category}` |
| `disposition.id` | integer | Disposition ID | |
| `disposition.code` | string | Immutable code (e.g. `SALE-OK`) | |
| `disposition.label` | string | Display label | |
| `disposition.category` | string | Category | `contact` / `no_contact` / `callback` / `remove` |
| `lead_id` | integer | Lead ID | |
| `lead_status_after` | string | Lead status after applying the disposition | `pending` / `contacted` / `converted` / `dnc` / `exhausted` |
| `callback_scheduled` | object\|null | Callback info (if any) | `{callback_at, agent_id}` or `null` |

**Response 200**:
```json
{
  "data": {
    "uuid": "093e1024-82c6-49b3-8775-99edeb221898",
    "state": "closed",
    "disposition": { "id": 5, "code": "SALE-OK", "label": "Sale Success", "category": "contact" },
    "lead_id": 78912,
    "lead_status_after": "converted",
    "callback_scheduled": null
  }
}
```

::: tip Industry-specific outcome fields
Industry-specific outcome fields (Payment Method, Appointment Date, Survey Result, Lead Score, Notes, ...) are declared as **custom fields** on each disposition, configured by the customer's admin. Detailed schemas per industry (customer care, service appointments, satisfaction surveys, ...) are shipped in a **separate per-customer configuration package**.
:::


---

# DNC list

<!-- source: https://docs.zorio.vn/en/api/telesales/dnc.md -->

# DNC list

Manage the customer's Do-Not-Call (DNC) list: query, add/remove individual numbers, CSV bulk import, and CSV export. Every phone number is automatically normalised to E.164 (`+84...`) on the server.

## Endpoint summary

| Endpoint | Purpose |
|---|---|
| `GET    /api/telesales/dnc` | List phone numbers on the DNC |
| `POST   /api/telesales/dnc` | Add one number to the DNC |
| `DELETE /api/telesales/dnc/{phone}` | Remove one number from the DNC |
| `POST   /api/telesales/dnc/import` | Bulk import from CSV (multipart) |
| `GET    /api/telesales/dnc/export` | Export the full DNC as CSV |

## `GET /api/telesales/dnc` — list

### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `q` | string | optional | Search by phone number (LIKE %keyword%) | |
| `source` | string | optional | Filter by source | `manual` / `import` / `disposition` / `webhook` |
| `date_from` | datetime | optional | Filter by `added_at ≥` (ISO 8601 UTC) | |
| `date_to` | datetime | optional | Filter by `added_at ≤` (ISO 8601 UTC) | |
| `page` | integer | optional | Page number | ≥ 1 (default 1) |
| `per_page` | integer | optional | Records per page | 1-200 (default 50) |

### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `phone` | string | Original phone number (format used on insert) | |
| `phone_e164` | string | Normalised E.164 number | `+84...` |
| `reason` | string\|null | DNC reason | max 500 chars |
| `source` | string | Source | `manual` / `import` / `disposition` / `webhook` |
| `added_by` | integer\|null | User ID who added (null if from webhook/system) | |
| `added_by_name` | string\|null | Display name of the adder | |
| `added_at` | datetime | When it was added (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "phone": "0900000000",
      "phone_e164": "+84900000000",
      "reason": "Customer opt-out",
      "source": "manual",
      "added_by": 7,
      "added_by_name": "Nguyen Van A",
      "added_at": "2026-04-01T03:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 50, "total": 124 }
}
```

## `POST /api/telesales/dnc` — add one number

### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `phone` | string | ✅ | Phone number — the server normalises to `+84...` | `0xxxxxxxxx` or `+84xxxxxxxxx` |
| `reason` | string | optional | DNC reason | max 500 chars |

**Body**:
```json
{
  "phone": "0912345678",
  "reason": "Customer opt-out via inbound IVR"
}
```

### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `phone` | string | Original number from the POST | |
| `phone_e164` | string | Normalised number | `+84...` |
| `reason` | string\|null | Reason | |
| `source` | string | Source — always `manual` when created through this endpoint | `manual` |
| `added_by` | integer | User ID of the creator | |
| `added_at` | datetime | When it was added (ISO 8601 UTC) | |

**Response 201**:
```json
{
  "data": {
    "phone": "0912345678",
    "phone_e164": "+84912345678",
    "reason": "Customer opt-out via inbound IVR",
    "source": "manual",
    "added_by": 7,
    "added_at": "2026-06-06T07:00:00Z"
  }
}
```

**Response 422 — validation cases**:
```json
// Invalid phone format
{
  "message": "The given data was invalid.",
  "errors": { "phone": ["The phone format is invalid. Expected 0xxxxxxxxx or +84xxxxxxxxx."] }
}

// Already on DNC
{
  "message": "Phone number is already on the DNC list.",
  "errors": { "phone": ["Phone +84912345678 already in DNC since 2026-05-01."] }
}
```

## `DELETE /api/telesales/dnc/{phone}`

`{phone}` accepts both `0xxxxxxxxx` and `+84xxxxxxxxx` (the server normalises).

**Response 204 No Content** (success).

**Response 404** — number not in the DNC:
```json
{ "message": "Phone +84912345678 not found in DNC." }
```

## `POST /api/telesales/dnc/import` — bulk CSV

**Request**: `multipart/form-data`

| Field | Description |
|---|---|
| `file` | CSV file (UTF-8). Required column: `phone`. Optional column: `reason`. |
| `dedupe` | `skip` (default — skip rows that already exist) \| `update` (overwrite `reason`) |

**Sample file**:
```csv
phone,reason
0912345678,Customer opt-out
0987654321,Wrong number
```

**Response 200**:
```json
{
  "data": {
    "total_rows":   1500,
    "created":      1342,
    "skipped":      147,
    "errors":       11,
    "error_samples": [
      { "row": 23, "phone": "12345",       "error": "Invalid phone format" },
      { "row": 47, "phone": "0999999999",  "error": "Already exists" }
    ]
  }
}
```

**Response 422** — cannot read the file:
```json
{
  "message": "Unable to read the CSV file.",
  "errors": { "file": ["Missing required column: phone."] }
}
```

## `GET /api/telesales/dnc/export`

**Query params**: same filter set as `GET /api/telesales/dnc` (`q`, `source`, `date_from`, `date_to`).

**Response 200**: `text/csv` — a streamed file with header `Content-Disposition: attachment; filename="dnc-export-YYYYMMDD.csv"`. Columns: `phone, phone_e164, reason, source, added_by_name, added_at`.


---

# Telesales API — Overview

<!-- source: https://docs.zorio.vn/en/api/telesales/index.md -->

# Telesales API — Overview

> Public REST API for the Telesales Module. Lets a customer CRM integrate dialer + campaigns + leads + caller-ID rotation + recording + reports.
>
> **Authentication**: Bearer Token (user session). **Base URL**: `https://app.zorio.vn/api/telesales/` (provisioned per customer).

## Scope

The Telesales API contains **11 endpoint groups**:

- Campaign management — CRUD + lifecycle (launch/pause/resume/archive/clone).
- Lead management — CRUD + bulk PATCH/DELETE/DNC.
- DNC (Do Not Call) — blocked-call list with CSV import.
- Caller-ID rotation groups — 6 strategies (round_robin, least_used, cap_based, weighted, sticky_lead, random).
- Script + Outcome — call scripts + disposition codes.
- Recording — playback + bulk export.
- 9 reports: dashboard / agent-performance / funnel / disposition-breakdown / caller-id-health / hour-dow-heatmap / lead-source-attribution / time-series / abandon-rate.

## Endpoint groups

| Group | Documentation |
|---|---|
| Campaigns | [Go to page](/en/api/telesales/campaigns) |
| Leads | [Go to page](/en/api/telesales/leads) |
| DNC list | [Go to page](/en/api/telesales/dnc) |
| Caller-ID rotation groups | [Go to page](/en/api/telesales/caller-id-groups) |
| Script + Outcome | [Go to page](/en/api/telesales/scripts) |
| Recording | [Go to page](/en/api/telesales/recording) |
| Reports (9 reports) | [Go to page](/en/api/telesales/reports) |


---

# Leads

<!-- source: https://docs.zorio.vn/en/api/telesales/leads.md -->

# Leads

Endpoints to manage leads within each campaign: 3-step import (preview → dry-run → commit), single CRUD, bulk update / delete / mark DNC, plus a flexible JSON-based custom-field mechanism.

## 4.1 Importing leads

::: tip File format
CSV (UTF-8) or XLSX. There is a generic template `CallList_Template.xlsx`; industry-specific templates ship in the separate per-customer configuration package.
:::

The flow has three steps:

### Step 1 — Preview (inspect column structure)
```http
POST /api/telesales/campaigns/{id}/leads/preview
Content-Type: multipart/form-data

file=@call_list.csv
```

#### Request form fields (multipart)

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `file` | file | ✅ | CSV (UTF-8) or XLSX file to preview | max 10MB |

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `headers` | string[] | Detected header row | |
| `sample` | array[] | Up to 5 sample data rows | |
| `mapping_suggestions` | object[] | Suggested column → system-field mapping | |
| `mapping_suggestions[].index` | integer | Column position (0-based) | |
| `mapping_suggestions[].header` | string | Column name | |
| `mapping_suggestions[].sample` | string | Sample data | |
| `mapping_suggestions[].suggested` | string\|null | Suggested system field | `full_name` / `phone` / `email` / `null` |
| `row_count` | integer | Total rows (excluding header) | |

**Response 200**:
```json
{
  "headers": ["Customer Name","Primary Phone","Alt. Phone","Reference Code","Note"],
  "sample": [
    ["Nguyen Mai","0912345678","0988111222","REF-001","High-value prospect"],
    ["Tran Hoa","0987654321","","REF-002",""]
  ],
  "mapping_suggestions": [
    { "index": 0, "header": "Customer Name",  "sample": "Nguyen Mai",  "suggested": "full_name" },
    { "index": 1, "header": "Primary Phone",  "sample": "0912345678",  "suggested": "phone" },
    { "index": 2, "header": "Alt. Phone",     "sample": "0988111222",  "suggested": null },
    { "index": 3, "header": "Reference Code", "sample": "REF-001",     "suggested": null },
    { "index": 4, "header": "Note",           "sample": "High-value",  "suggested": null }
  ],
  "row_count": 487
}
```

### Step 2 — Dry-run (detect duplicates / DNC / errors)
```http
POST /api/telesales/campaigns/{id}/leads/dry-run
Content-Type: multipart/form-data

file=@call_list.csv
mapping={"phone":1,"full_name":0,"custom_fields":{"reference_code":3,"alt_phone":2,"note":4}}
```

**`mapping` format**: each value is the **0-based column index** in the CSV header row. `phone` is mandatory (integer). Any additional column can be mapped into `custom_fields.*` — the key here MUST match a custom-field code registered for `entity=Lead`.

#### Request form fields (multipart)

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `file` | file | ✅ | CSV/XLSX file to dry-run | max 10MB |
| `mapping` | string (JSON) | ✅ | Column → system-field mapping | JSON object `{phone, full_name?, email?, custom_fields?}` |

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `file_token` | string | Temporary token identifying the uploaded file — pass back in the commit step | Format `telesales/imports/{campaign_id}/{uuid}.csv` |
| `summary` | object | Summary of validation results | |
| `summary.total` | integer | Total rows | |
| `summary.valid` | integer | Valid rows | |
| `summary.duplicate` | integer | Duplicate rows (phone already in the campaign) | |
| `summary.dnc` | integer | Rows whose phone is on the DNC list | |
| `summary.errors` | array | List of format errors | |
| `sample_rows` | array | Up to 50 sample rows with classification | |
| `sample_rows[].row` | integer | Row number in the file (1-based) | |
| `sample_rows[].phone` | string | Phone number | |
| `sample_rows[].full_name` | string | Full name (if mapped) | |
| `sample_rows[].status` | string | Row classification | `valid` / `duplicate` / `dnc` / `error` |
| `sample_rows[].reason` | string | Reason (only when `status` is not `valid`) | |

**Response 200**:
```json
{
  "file_token": "telesales/imports/36/abc123.csv",
  "summary": {
    "total": 487,
    "valid": 462,
    "duplicate": 18,
    "dnc": 7,
    "errors": []
  },
  "sample_rows": [
    { "row": 1, "phone": "0912345678", "full_name": "Nguyen Mai", "status": "valid" },
    { "row": 5, "phone": "0900000000", "full_name": "Le Linh",    "status": "dnc",
      "reason": "Phone on DNC since 2026-04-01" }
  ]
}
```

### Step 3 — Commit (write to the database)
```http
POST /api/telesales/campaigns/{id}/leads/import
Content-Type: multipart/form-data

file_token=telesales/imports/36/abc123.csv
mapping={...same as step 2...}
```

#### Request form fields (multipart)

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `file_token` | string | ✅ | Token returned by the dry-run step | Still valid (TTL 24h) |
| `mapping` | string (JSON) | ✅ | Column → field mapping — must match the dry-run | Same format as step 2 |

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `campaign_id` | integer | Campaign ID | |
| `inserted` | integer | Number of leads inserted | |
| `skipped_duplicate` | integer | Skipped due to duplication | |
| `skipped_dnc` | integer | Skipped due to DNC | |
| `skipped_invalid` | integer | Skipped due to invalid format | |
| `took_ms` | integer | Processing time (ms) | |

**Response 201**:
```json
{
  "data": {
    "campaign_id": 36,
    "inserted": 462,
    "skipped_duplicate": 18,
    "skipped_dnc": 7,
    "skipped_invalid": 0,
    "took_ms": 1840
  }
}
```

### Declaring custom fields

The system stores extended lead data in the lead's custom-field JSON column. Before importing, the customer's admin must declare valid keys via:

```http
GET    /api/custom-fields?entity=Lead
POST   /api/custom-fields
PATCH  /api/custom-fields/{id}
DELETE /api/custom-fields/{id}
```

Each definition includes `entity`, `code`, `type` (string / integer / decimal / date / datetime / boolean / enum), validation rules, display order, and (optionally) `is_encrypted=true` to enable the Layer-2 encryption pipeline. Adding a new field requires **no** schema migration.

## 4.2 Lead CRUD

| Endpoint | Purpose |
|---|---|
| `GET    /api/telesales/campaigns/{id}/leads` | List leads (with pagination + filters: `?status=pending&assigned_agent_id=25`) |
| `GET    /api/telesales/leads/{id}` | Detail (includes the `custom_fields` JSON) |
| `PATCH  /api/telesales/leads/{id}` | Update |
| `DELETE /api/telesales/leads/{id}` | Delete |
| `PATCH  /api/telesales/leads/bulk` | Bulk update |
| `DELETE /api/telesales/leads/bulk` | Bulk delete |
| `POST   /api/telesales/leads/bulk-dnc` | Bulk-push to DNC |

### `GET /api/telesales/campaigns/{id}/leads` — list leads

```http
GET /api/telesales/campaigns/36/leads?page=1&per_page=50&status=pending&sort=priority_score&dir=desc
```

#### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `status` | string | optional | Filter by lead status | `pending` / `queued` / `contacted` / `converted` / `dnc` / `exhausted` |
| `assigned_agent_id` | integer | optional | Filter by sticky agent | User ID |
| `search` | string | optional | Search by `phone` / `phone_normalized` / `full_name` / `email` (LIKE %keyword%) | |
| `sort` | string | optional | Sort column | `priority_score` (default) / `imported_at` / `last_attempt_at` |
| `dir` | string | optional | Sort direction | `asc` / `desc` (default `desc`) |
| `page` | integer | optional | Page number | ≥ 1 (default 1) |
| `per_page` | integer | optional | Records per page | 1-200 (default 50) |

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Lead ID | |
| `campaign_id` | integer | Campaign ID | |
| `full_name` | string\|null | Lead full name | |
| `phone` | string | Phone number (raw — as entered) | |
| `status` | string | Lead status | `pending` / `queued` / `contacted` / `converted` / `dnc` / `exhausted` |
| `priority_score` | integer | Call priority — higher = called first | 0-100 |
| `assigned_agent_id` | integer\|null | Sticky agent ID | |
| `attempts_count` | integer | Number of dial attempts | |
| `next_attempt_at` | datetime\|null | Scheduled next attempt (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "id": 78912,
      "campaign_id": 36,
      "full_name": "Nguyen Thi Mai",
      "phone": "0912345678",
      "status": "pending",
      "priority_score": 85,
      "assigned_agent_id": 25,
      "attempts_count": 0,
      "next_attempt_at": "2026-06-07T08:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 10, "per_page": 50, "total": 487 }
}
```

::: tip Payload optimization
The list response does **not include `custom_fields`** to keep the payload compact (487 leads × 5–10 custom fields is huge). Call `GET /api/telesales/leads/{id}` when you need full details.
:::

### `GET /api/telesales/leads/{id}` — detail

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Lead ID | |
| `campaign_id` | integer | Campaign ID | |
| `full_name` | string\|null | Lead full name | |
| `phone` | string | Raw phone number | |
| `status` | string | Lead status | `pending` / `queued` / `contacted` / `converted` / `dnc` / `exhausted` |
| `priority_score` | integer | Priority | 0-100 |
| `next_attempt_at` | datetime\|null | Scheduled next attempt | |
| `assigned_agent_id` | integer\|null | Sticky agent | |
| `attempts_count` | integer | Attempts made | |
| `custom_fields` | object | Extended fields — keys match the custom-field definitions (entity `Lead`) | |
| `created_at` | datetime | Creation timestamp (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": {
    "id": 78912,
    "campaign_id": 36,
    "full_name": "Nguyen Thi Mai",
    "phone": "0912345678",
    "status": "pending",
    "priority_score": 85,
    "next_attempt_at": "2026-06-07T08:00:00Z",
    "assigned_agent_id": 25,
    "attempts_count": 0,
    "custom_fields": {
      "reference_code": "REF-2026-001",
      "alt_phone": "0988111222",
      "note": "Returning customer, prefers Vietnamese"
    },
    "created_at": "2026-06-06T06:30:00Z"
  }
}
```

The set of keys inside `custom_fields` depends on the customer's custom-field definitions for the `Lead` entity.

**Response 404**:
```json
{ "message": "Lead not found." }
```

### `PATCH /api/telesales/leads/{id}` — update one lead

#### Request body fields (every field optional — send only what you want to change)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `full_name` | string | Full name | max 150 chars |
| `email` | string | Email | Must be a valid email address |
| `custom_fields` | object | Extended fields — keys match custom-field definitions | JSON object |
| `priority_score` | integer | Priority | 0-100 |
| `next_attempt_at` | datetime | Scheduled next attempt (ISO 8601 UTC) | |
| `consent_status` | string | Consent status | `granted` / `withdrawn` / `unknown` |
| `consent_source` | string | Consent capture source | max 100 chars |

::: warning Forbidden fields
The following fields **cannot** be updated through this endpoint: `phone`, `campaign_id`, `status`, `assigned_agent_id` (use the dedicated re-assignment API).
:::

**Body**:
```json
{
  "full_name": "Nguyen Thi Mai Anh",
  "email": "mai.anh@example.com",
  "custom_fields": {
    "reference_code": "REF-2026-001-UPDATED",
    "note": "Customer requested callback Monday morning"
  },
  "priority_score": 92,
  "next_attempt_at": "2026-06-09T09:00:00Z",
  "consent_status": "granted",
  "consent_source": "phone_call_2026-06-08"
}
```

**Response 200**: returns the full lead object (same shape as `GET /api/telesales/leads/{id}`).

**Response 422 — validation cases**:

```json
// priority_score outside the allowed range
{
  "message": "The given data was invalid.",
  "errors": { "priority_score": ["The priority score must be between 0 and 100."] }
}

// next_attempt_at has invalid format
{
  "message": "The given data was invalid.",
  "errors": { "next_attempt_at": ["The next attempt at is not a valid date."] }
}

// custom_fields is not an array/object
{
  "message": "The given data was invalid.",
  "errors": { "custom_fields": ["The custom fields must be an array."] }
}

// consent_status not in the allowed enum
{
  "message": "The given data was invalid.",
  "errors": { "consent_status": ["The selected consent status is invalid."] }
}

// email is invalid
{
  "message": "The given data was invalid.",
  "errors": { "email": ["The email must be a valid email address."] }
}
```

### `DELETE /api/telesales/leads/{id}` — delete one lead

**Response 204 No Content** (success).

**Response 404**: lead does not exist or does not belong to the account.

**Response 422 — lead has an active call**:
```json
{
  "message": "Cannot delete a lead with an active call.",
  "errors": { "lead_id": ["Lead 78912 is currently on call UUID xxx — wait for it to end first."] }
}
```

::: tip Soft delete
This is a soft delete — the lead's `deleted_at` is set, but its dial history is preserved. Bulk delete behaves the same way.
:::

### `PATCH /api/telesales/leads/bulk` — bulk update

#### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `lead_ids` | integer[] | ✅ | Lead IDs to update | 1-1000 items |
| `patch` | object | ✅ | Fields to apply to all leads in the list | See `patch.*` |
| `patch.status` | string | optional | New status | `pending` / `queued` / `contacted` / `converted` / `dnc` / `exhausted` |
| `patch.assigned_agent_id` | integer\|null | optional | Sticky agent | User ID or `null` to unassign |
| `patch.priority_score` | integer | optional | Priority | 0-100 |
| `patch.next_attempt_at` | datetime | optional | Scheduled callback time | ISO 8601 UTC |

**Body**:
```json
{
  "lead_ids": [78912, 78913, 78920, 78921],
  "patch": {
    "status": "queued",
    "assigned_agent_id": 25,
    "priority_score": 100
  }
}
```

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `success` | bool | Overall success | `true` / `false` |
| `updated` | integer | Leads actually updated | |
| `skipped` | integer | Leads skipped (not in account, or validation failed) | |

**Response 200**:
```json
{
  "success": true,
  "updated": 4,
  "skipped": 0
}
```

**Response 422 — `lead_ids` empty or too large**:
```json
{
  "message": "The given data was invalid.",
  "errors": { "lead_ids": ["The lead ids must have at least 1 item.", "The lead ids may not have more than 1000 items."] }
}
```

::: warning Bulk limits
Maximum **1000 lead_ids per request**. Leads not in the account are silently skipped (counted as `skipped`).
:::

### `DELETE /api/telesales/leads/bulk` — bulk delete

**Body**:
```json
{ "lead_ids": [78912, 78913, 78920] }
```

**Response 200**:
```json
{ "success": true, "deleted": 3 }
```

**Response 422**: validation behaves like `PATCH /api/telesales/leads/bulk`.

### `POST /api/telesales/leads/bulk-dnc` — bulk-mark DNC

Push many leads onto the DNC list in a single request.

#### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `lead_ids` | integer[] | ✅ | Lead IDs to push to DNC | 1-1000 items |
| `reason` | string | ✅ | DNC reason — required for the audit trail | max 500 chars |

**Body**:
```json
{
  "lead_ids": [78912, 78913],
  "reason": "Customer requested opt-out"
}
```

#### Response body fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `success` | bool | Overall success | `true` / `false` |
| `added_to_dnc` | integer | Phones newly added to DNC | |
| `skipped_already_dnc` | integer | Phones already on DNC | |
| `audit_trail_id` | string | Audit record ID (DNC audit log) | Format `audit_dnc_*` |

**Response 200**:
```json
{
  "success": true,
  "added_to_dnc": 2,
  "skipped_already_dnc": 0,
  "audit_trail_id": "audit_dnc_abc123"
}
```

After marking DNC:
- The lead's phone number is inserted into the DNC list (`source: 'customer_request'`).
- The lead's `status` changes to `dnc`.
- Any pending callbacks for the lead are cancelled.
- An audit record is created in the DNC audit log with `actor_id`, `lead_ids`, `reason`, `audit_trail_id`.

**Response 422 — missing `reason`**:
```json
{
  "message": "The given data was invalid.",
  "errors": { "reason": ["The reason field is required."] }
}
```


---

# Recording

<!-- source: https://docs.zorio.vn/en/api/telesales/recording.md -->

# Recording

Endpoints to play / download a single call recording, create bulk export jobs (ZIP), control jobs, and pause/resume recording in real time for PCI compliance.

## Pause / resume recording (PCI compliance)

```http
POST /api/telesales/calls/{uuid}/recording/pause
POST /api/telesales/calls/{uuid}/recording/resume
```

### Path parameter

| Field | Type | Description |
|---|---|---|
| `uuid` | string | UUID of the call in progress |

### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `uuid` | string | Call UUID | |
| `recording` | string | Recording state after the call | `paused` / `recording` |

**Response 200**: `{ "data": { "uuid": "...", "recording": "paused" } }`

::: tip Use case
The agent can pause recording while the customer reads out sensitive information (credit card number, CVV, ...) to remain PCI-DSS compliant, then resume recording once the sensitive segment is over.
:::

## Endpoint summary

| Endpoint | Purpose |
|---|---|
| `GET /api/telesales/recordings/{uuid}` | Stream audio for playback (returns `audio/wav`, supports Range requests) |
| `GET /api/telesales/recordings/{uuid}/download` | Download the `.wav` file with a filename header |
| `POST /api/telesales/recordings/export-bulk` | Create an async ZIP export job |
| `GET /api/telesales/recordings/export-bulk/{jobId}` | Check job status |
| `GET /api/telesales/recordings/export-bulk/{jobId}/download` | Download the ZIP when the job is done |
| `DELETE /api/telesales/recordings/export-bulk/{jobId}` | Cancel a job / clean up the ZIP early |

## `GET /api/telesales/recordings/{uuid}` — stream

### Path parameter

| Field | Type | Description |
|---|---|---|
| `uuid` | string | Call UUID |

### Response headers

| Header | Description | Value |
|---|---|---|
| `Content-Type` | MIME type | `audio/wav` |
| `Accept-Ranges` | Range requests supported | `bytes` |
| `Content-Length` | File size (bytes) | |
| `Cache-Control` | Cache policy | `private, max-age=3600` |

**Response 200**:
- `Content-Type: audio/wav`
- `Accept-Ranges: bytes` (for HTML5 audio scrubbing)
- `Content-Length: <bytes>`
- `Cache-Control: private, max-age=3600`

**Response 206 Partial Content** (HTTP Range request) — used by the audio player for scrubbing.

**Response 404** — no recording:
```json
{ "message": "Recording not found.", "error_code": "RECORDING_NOT_FOUND" }
```

**Response 410 Gone** — the recording exceeded the retention window configured by the admin:
```json
{ "message": "Recording has exceeded the retention window.", "expired_at": "2026-03-01T00:00:00Z" }
```

## `GET /api/telesales/recordings/{uuid}/download`

### Path parameter

| Field | Type | Description |
|---|---|---|
| `uuid` | string | Call UUID |

### Response headers

| Header | Description | Value |
|---|---|---|
| `Content-Type` | MIME type | `audio/wav` |
| `Content-Disposition` | Suggested filename for the browser | `attachment; filename="call-{uuid}-{date}.wav"` |

**Response 200**:
- `Content-Type: audio/wav`
- `Content-Disposition: attachment; filename="call-093e1024-2026-06-06.wav"`

Errors 404/410 are identical to the stream endpoint.

## `POST /api/telesales/recordings/export-bulk` — create ZIP job

### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `campaign_id` | integer | optional | Filter by campaign | |
| `date_from` | datetime | ✅ | Start timestamp (ISO 8601 UTC) | |
| `date_to` | datetime | ✅ | End timestamp (ISO 8601 UTC) | `date_from..date_to` ≤ 31 days |
| `agent_ids[]` | `array<integer>` | optional | Filter by agent | |
| `disposition_codes[]` | `array<string>` | optional | Only export calls with these dispositions | disposition codes belonging to the account |

**Body**:
```json
{
  "campaign_id": 36,
  "date_from": "2026-06-01T00:00:00Z",
  "date_to":   "2026-06-05T23:59:59Z",
  "agent_ids": [25, 26],
  "disposition_codes": ["SALE-OK", "CALLBACK_REQ"]
}
```

### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `job_id` | string | Export job ID | `exp_<hex>` |
| `status` | string | Initial state | `queued` |
| `estimated_files` | integer | Estimated recordings to be packaged | ≥ 1 |
| `estimated_size_mb` | integer | Estimated ZIP size (MB) | ≥ 0 |
| `created_at` | datetime | Job creation (ISO 8601 UTC) | |
| `expires_at` | datetime | When the ZIP is auto-deleted (default +30 days) | ISO 8601 UTC |

**Response 201**:
```json
{
  "data": {
    "job_id": "exp_abc123",
    "status": "queued",
    "estimated_files": 215,
    "estimated_size_mb": 480,
    "created_at": "2026-06-06T07:00:00Z",
    "expires_at": "2026-07-06T07:00:00Z"
  }
}
```

**Response 422 — validation cases**:
```json
// Time range exceeds 31 days
{
  "message": "The given data was invalid.",
  "errors": { "date_to": ["The date_from..date_to range may not exceed 31 days."] }
}

// 0 files match the filter → no job is created
{
  "message": "No recordings match the filter.",
  "errors": { "filter": ["Estimated 0 files. Adjust date range or filters."] }
}
```

**Response 403** — caller lacks the supervisor / admin role:
```json
{ "message": "You are not allowed to bulk-export recordings. Supervisor or admin role is required." }
```

## `GET /api/telesales/recordings/export-bulk/{jobId}` — check status

### Path parameter

| Field | Type | Description |
|---|---|---|
| `jobId` | string | Job ID returned by the create endpoint |

### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `job_id` | string | Export job ID | |
| `status` | string | Job state | `queued` / `running` / `ready` / `failed` / `expired` / `cancelled` |
| `progress_pct` | integer | Percent complete | 0-100 |
| `files` | integer | Files packaged (only when `ready`) | ≥ 0 |
| `files_processed` | integer | Files processed so far (only when `running`) | ≥ 0 |
| `size_mb` | integer | Actual ZIP size (MB) | |
| `download_url` | string | URL to download the ZIP (when `status=ready`) | |
| `created_at` | datetime | Job creation (ISO 8601 UTC) | |
| `completed_at` | datetime\|null | When packaging finished | |
| `expires_at` | datetime | When the ZIP is auto-deleted | |
| `error_code` | string | Error code when `status=failed` | e.g. `STORAGE_ERROR` |
| `error_message` | string | Error description when `status=failed` | |
| `failed_at` | datetime | When the job failed | |

**Response 200**:
```json
{
  "data": {
    "job_id":        "exp_abc123",
    "status":        "ready",
    "progress_pct":  100,
    "files":         215,
    "size_mb":       478,
    "download_url":  "/api/telesales/recordings/export-bulk/exp_abc123/download",
    "created_at":    "2026-06-06T07:00:00Z",
    "completed_at":  "2026-06-06T07:08:42Z",
    "expires_at":    "2026-07-06T07:00:00Z"
  }
}
```

Enum `status`: `queued` | `running` | `ready` | `failed` | `expired` | `cancelled`.

**State `running`** also returns `progress_pct` (0..99) + `files_processed`.

**State `failed`** also returns:
```json
{
  "data": {
    "job_id": "exp_abc123",
    "status": "failed",
    "error_code": "STORAGE_ERROR",
    "error_message": "Storage unavailable during ZIP packaging.",
    "failed_at": "2026-06-06T07:05:00Z"
  }
}
```

**Response 404** — job does not exist or does not belong to the account.

## `GET /api/telesales/recordings/export-bulk/{jobId}/download`

### Path parameter

| Field | Type | Description |
|---|---|---|
| `jobId` | string | Job ID (status must be `ready`) |

### Response headers

| Header | Description | Value |
|---|---|---|
| `Content-Type` | MIME type | `application/zip` |
| `Content-Disposition` | ZIP filename | `attachment; filename="recordings-{jobId}.zip"` |

**Response 200**:
- `Content-Type: application/zip`
- `Content-Disposition: attachment; filename="recordings-exp_abc123.zip"`

The ZIP contains the `.wav` files plus a `manifest.csv` (call UUID, agent extension, agent name, disposition code, start_time, duration, lead phone number).

**Response 410 Gone** — ZIP has expired (30 days):
```json
{ "message": "Export ZIP has expired. Please create a new job." }
```

**Response 409 Conflict** — job is not yet ready:
```json
{ "message": "Job exp_abc123 is currently in state 'running' (38%). Wait until ready before downloading." }
```

## `DELETE /api/telesales/recordings/export-bulk/{jobId}` — cancel / clean up

### Path parameter

| Field | Type | Description |
|---|---|---|
| `jobId` | string | Job ID to cancel or clean up |

**Response 204 No Content** — `queued`/`running` → cancelled; `ready` → ZIP is deleted early to free storage.


---

# Reports

<!-- source: https://docs.zorio.vn/en/api/telesales/reports.md -->

# Reports

A group of 9 reports for the Telesales module: dashboard overview, disposition breakdown, agent performance, funnel, caller-ID health, hour x day-of-week heatmap, lead-source attribution, time series and abandon rate. All support CSV/Excel export.

## Common query params

Every endpoint shares the following parameters (UTC ISO 8601):

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `campaign_id` | integer | optional | Filter by campaign | |
| `date_from` | datetime | YES | Start timestamp (ISO 8601 UTC) | |
| `date_to` | datetime | YES | End timestamp (ISO 8601 UTC) | `date_from..date_to` <= 90 days |
| `agent_ids[]` | `array<integer>` | optional | Multi-select agent filter (`?agent_ids[]=25&agent_ids[]=26`) | |
| `team_id` | integer | optional | Filter by team | |
| `timezone` | string | optional | Group by day/hour using this timezone | TZDB name (`UTC`, `Asia/Ho_Chi_Minh`, ...) - default `UTC` |
| `format` | string | optional | Response format | `json` (default) / `csv` / `xlsx` (see 9.2) |

**Common 422 error** - range exceeds 90 days:
```json
{
  "message": "The given data was invalid.",
  "errors": { "date_to": ["The date_from..date_to range may not exceed 90 days."] }
}
```

## Summary of the 9 endpoints

| Endpoint | Content |
|---|---|
| `GET /api/telesales/reports/dashboard` | Overall KPIs: dials, answer rate, AHT, conversion |
| `GET /api/telesales/reports/disposition-breakdown` | Percentage breakdown per disposition code |
| `GET /api/telesales/reports/agent-performance` | Per-agent KPIs: calls, conversions, AHT, talk time |
| `GET /api/telesales/reports/funnel` | Funnel: Lead -> Dialed -> Connected -> Talked > 30 s -> Converted |
| `GET /api/telesales/reports/caller-id-health` | Caller-ID rotation health (ASR, short-call ratio, carrier) |
| `GET /api/telesales/reports/hour-dow-heatmap` | 24-hour x 7-day matrix (best calling windows) |
| `GET /api/telesales/reports/lead-source-attribution` | Conversion by lead source |
| `GET /api/telesales/reports/time-series` | Time series by `?group_by=day\|week\|hour` |
| `GET /api/telesales/reports/abandon-rate` | Realtime abandon rate (PDPL/TCPA gate) |

## 9.1 Sample responses

### `GET /api/telesales/reports/dashboard?campaign_id=43&date_from=2026-06-01&date_to=2026-06-10`

#### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `total_dials` | integer | Total dial attempts in the time window | >= 0 |
| `total_answers` | integer | Total calls answered by the customer | >= 0 |
| `answer_rate_pct` | string | Decimal string (2 digits) - `total_answers / total_dials x 100` | "0.00"-"100.00" |
| `avg_talk_time_sec` | string | Average talk time (seconds) | |
| `total_talk_time_sec` | string | Total talk time (seconds) | |
| `unique_agents` | integer | Distinct agents that dialed in the window | >= 0 |
| `pdpl_blocked_count` | integer | Calls blocked by PDPL (outside allowed window) | >= 0 |

```json
{
  "data": {
    "total_dials":        487,
    "total_answers":      312,
    "answer_rate_pct":   "64.07",
    "avg_talk_time_sec": "184.5",
    "total_talk_time_sec": "57563",
    "unique_agents":       12,
    "pdpl_blocked_count":   5
  }
}
```

### `GET /api/telesales/reports/agent-performance?campaign_id=43&date_from=...&date_to=...`

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `agent_id` | integer | Agent user ID | |
| `name` | string | Agent full name | |
| `username` | string | Login name | |
| `dials` | integer | Dial attempts in the window | >= 0 |
| `answers` | integer | Answered calls | >= 0 |
| `avg_aht_sec` | integer | AHT (Average Handle Time) - average per-call handling time (seconds) | >= 0 |
| `conversions` | integer | Successful conversions | >= 0 |
| `conv_rate` | number | `conversions / answers x 100` (float, NOT string) | 0-100 |

```json
{
  "data": [
    {
      "agent_id":     3,
      "name":         "Nguyen Van A",
      "username":     "agent01",
      "dials":        152,
      "answers":       98,
      "avg_aht_sec":  191,
      "conversions":   28,
      "conv_rate":   18.42
    },
    {
      "agent_id":     4,
      "name":         "Tran Thi B",
      "username":     "agent02",
      "dials":        140,
      "answers":       86,
      "avg_aht_sec":  176,
      "conversions":   22,
      "conv_rate":   15.71
    }
  ]
}
```

### `GET /api/telesales/reports/funnel?campaign_id=43&date_from=...&date_to=...`

Returns a flat array (not a nested object `{stages, conversion_overall_pct}`).

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `stage` | string | Funnel stage name | `Total leads` / `Dialed` / `Connected` / `Talked > 30s` / `Disposed` / `Converted` |
| `count` | integer | Number of leads/calls at this stage | >= 0 |

```json
{
  "data": [
    { "stage": "Total leads",  "count":  487 },
    { "stage": "Dialed",       "count":  312 },
    { "stage": "Connected",    "count":  248 },
    { "stage": "Talked > 30s", "count":  198 },
    { "stage": "Disposed",     "count":  290 },
    { "stage": "Converted",    "count":   78 }
  ]
}
```

**There are 6 stages** - including `Disposed`. The client computes `conversion_overall_pct = Converted / Total_leads x 100` from the first and last stages.

### `GET /api/telesales/reports/disposition-breakdown?campaign_id=43&date_from=...&date_to=...`

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `code` | string | Disposition code | |
| `label` | string | Display label | |
| `category` | string | Outcome group | `contact` / `no_contact` / `callback` / `remove` |
| `color` | string | UI badge color | `#RRGGBB` |
| `count` | integer | Calls with this disposition | >= 0 |
| `pct` | string | Decimal string (2 digits) - percentage of total calls | "0.00"-"100.00" |

```json
{
  "data": [
    {
      "code":     "no_answer",
      "label":    "No Answer",
      "category": "no_contact",
      "color":    "#6B7280",
      "count":     95,
      "pct":      "30.45"
    },
    {
      "code":     "sale",
      "label":    "Sale Success",
      "category": "contact",
      "color":    "#10B981",
      "count":     78,
      "pct":      "25.00"
    }
  ]
}
```

Each item includes `category` + `color` (the UI uses these to render badges). `pct` is a decimal string. There is no `meta: {total_calls}` wrapper - the client computes `total = sum(count)`.

### `GET /api/telesales/reports/caller-id-health?date_from=...&date_to=...`

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `cid` | string | Caller-ID number | |
| `display_name` | string\|null | Internal name | |
| `carrier` | string | Telco | `viettel` / `mobifone` / `vinaphone` / `vietnamobile` / `landline` / `other` |
| `cli_type` | string | Number type | `mobile` / `fixed_02x` / `hotline_1900` / `hotline_1800` / `brandname` |
| `pool_status` | string | Status inside the rotation pool | `active` / `cooldown` / `paused` / `disabled` |
| `cooldown_until` | datetime\|null | When cooldown ends | ISO 8601 UTC |
| `daily_cap` | integer | Daily call cap | >= 1 |
| `total_calls` | integer | Total calls dialed in the window | >= 0 |
| `answered_calls` | integer | Answered calls | >= 0 |
| `asr_pct` | number | Answer-Seizure Ratio (%) - `answered/total x 100` | 0-100 |
| `acd_sec` | integer | Average Call Duration - average talk time (seconds) | >= 0 |
| `short_calls` | integer | Calls shorter than the "meaningful conversation" threshold | >= 0 |
| `short_call_ratio_pct` | number | Ratio of short calls / total | 0-100 |
| `rejected_calls` | integer | Rejected calls | >= 0 |
| `health_status` | string | Health classification | `healthy` / `warning` / `suspected_block` / `no_data` |
| `health_calls_today` | integer | Calls today (used for cooldown evaluation) | >= 0 |

```json
{
  "data": [
    {
      "cid":                  "0900000012",
      "display_name":         "Sales Line 1",
      "carrier":              "viettel",
      "cli_type":             "fixed_02x",
      "pool_status":          "active",
      "cooldown_until":        null,
      "daily_cap":             200,
      "total_calls":           152,
      "answered_calls":         98,
      "asr_pct":                64.5,
      "acd_sec":                121,
      "short_calls":             28,
      "short_call_ratio_pct":   18.4,
      "rejected_calls":           2,
      "health_status":         "healthy",
      "health_calls_today":      87
    }
  ]
}
```

### `GET /api/telesales/reports/hour-dow-heatmap?campaign_id=43&date_from=...&date_to=...`

Returns a **flat array of 168 items** (7 days x 24 hours), not nested by day-of-week.

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `day_of_week` | integer | Day of the week | 0 = Sun, 1 = Mon, ..., 6 = Sat |
| `hour` | integer | Hour of the day (per the `timezone` query param) | 0-23 |
| `dials` | integer | Dial attempts in the slot | >= 0 |
| `answered` | integer | Answered calls | >= 0 |
| `answer_rate_pct` | number | Answer rate `answered/dials x 100` | 0-100 |

```json
{
  "data": [
    { "day_of_week": 1, "hour": 0, "dials": 0,  "answered": 0,  "answer_rate_pct":  0 },
    { "day_of_week": 1, "hour": 1, "dials": 0,  "answered": 0,  "answer_rate_pct":  0 },
    { "day_of_week": 1, "hour": 9, "dials": 87, "answered": 56, "answer_rate_pct": 64.4 }
  ]
}
```

The client pivots into a 7 x 24 matrix to render the heatmap.

### `GET /api/telesales/reports/lead-source-attribution?date_from=...&date_to=...`

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `source` | string | Lead source - leads without a source are grouped under `"(unknown)"` | |
| `total_leads` | integer | Total leads from this source in the window | >= 0 |
| `dialed_count` | integer | Leads that have been dialed | >= 0 |
| `contacted_count` | integer | Leads that picked up | >= 0 |
| `conv_count` | integer | Successful conversions | >= 0 |
| `conv_rate_pct` | string | Conversion rate `conv_count/total_leads x 100` (decimal, 2 digits) | "0.00"-"100.00" |

```json
{
  "data": [
    {
      "source":           "facebook_lead_ads",
      "total_leads":       240,
      "dialed_count":      230,
      "contacted_count":   152,
      "conv_count":         62,
      "conv_rate_pct":    "25.83"
    },
    {
      "source":           "(unknown)",
      "total_leads":         5,
      "dialed_count":        3,
      "contacted_count":     2,
      "conv_count":          0,
      "conv_rate_pct":     "0.00"
    }
  ]
}
```

### `GET /api/telesales/reports/time-series?campaign_id=43&group_by=day&date_from=...&date_to=...`

Returns a **flat array** - no `{group_by, metrics, series}` wrapper.

#### Additional query parameter

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `group_by` | string | optional | Time grouping unit | `day` (default) / `week` / `hour` |

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `bucket` | string | Time bucket - format depends on `group_by` | `day` -> `YYYY-MM-DD`; `week` -> `YYYY-Www` (ISO 8601); `hour` -> `YYYY-MM-DD HH:00:00` |
| `dials` | integer | Dial attempts in the bucket | >= 0 |
| `answers` | integer | Answered calls | >= 0 |
| `talk_sec` | integer | Total talk time (seconds) | >= 0 |
| `conversions` | integer | Successful conversions | >= 0 |

```json
{
  "data": [
    { "bucket": "2026-06-01", "dials": 110, "answers": 68, "talk_sec":  9180, "conversions": 18 },
    { "bucket": "2026-06-02", "dials": 105, "answers": 71, "talk_sec": 10260, "conversions": 16 },
    { "bucket": "2026-06-05", "dials":  82, "answers": 55, "talk_sec":  6720, "conversions": 15 }
  ]
}
```

### `GET /api/telesales/reports/abandon-rate?campaign_id=43` (realtime)

This endpoint's response is richer than other reports - it contains `current` (live snapshot) + `breaches` (history of recent threshold breaches).

#### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `current.campaign_id` | integer | Campaign ID | |
| `current.attempts_total` | integer | Total attempts in the measurement window | >= 0 |
| `current.attempts_abandoned` | integer | Attempts abandoned before the agent could speak | >= 0 |
| `current.abandon_rate_pct` | number | Abandon rate (%) | 0-100 |
| `current.window_minutes` | integer | Measurement window length (minutes, default 30 days = 43,200) | >= 1 |
| `current.window_from` | datetime | Window start | ISO 8601 |
| `current.window_to` | datetime | Window end | ISO 8601 |
| `current.campaign_name` | string | Campaign name | |
| `current.campaign_status` | string | Campaign status | `draft` / `active` / `paused` / `completed` |
| `current.limit_pct` | number | Allowed PDPL/TCPA threshold | default 3 |
| `current.breached` | bool | Whether the threshold is being breached now | |
| `breaches[]` | array | History of snapshots that breached the threshold (empty if never) | |

```json
{
  "data": {
    "current": {
      "campaign_id":           43,
      "attempts_total":         1,
      "attempts_abandoned":     0,
      "abandon_rate_pct":       0,
      "window_minutes":     43200,
      "window_from":      "2026-05-10 02:31:14",
      "window_to":        "2026-06-09 02:31:14",
      "tenant_id":              1,
      "campaign_name":     "Outbound Sales Q3-2026 03",
      "campaign_status":   "active",
      "limit_pct":              3,
      "breached":           false
    },
    "breaches": []
  }
}
```

When `breached=true`, the `breaches` array contains the history of breaching snapshots (time windows that exceeded the limit). The client uses this to render a warning banner and trend chart.

## 9.2 Export CSV / Excel

```http
GET /api/telesales/reports/{report}/export?format=csv|xlsx
```

`{report}` in {dashboard, disposition-breakdown, agent-performance, funnel, caller-id-health, hour-dow-heatmap, lead-source-attribution, time-series}.

Response: a file stream (`Content-Type: text/csv` or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`).

The default export layout is the generic one. Per-customer Excel templates (column order, header labels, conditional formatting) are configured inside the separate per-customer configuration package.


---

# Script + Outcome

<!-- source: https://docs.zorio.vn/en/api/telesales/scripts.md -->

# Script + Outcome

This group covers Call Scripts and Disposition Codes — two core building blocks the agent uses on every call: the script tells them what to say; the disposition classifies the result when the call ends.

## 5. Call Scripts

| Endpoint | Purpose |
|---|---|
| `GET    /api/telesales/scripts` | List the customer's scripts |
| `GET    /api/telesales/scripts/{id}` | Detail for one script (with detected placeholders) |
| `POST   /api/telesales/scripts` | Create a script |
| `PUT    /api/telesales/scripts/{id}` | Update a script |
| `DELETE /api/telesales/scripts/{id}` | Delete a script |
| `POST   /api/telesales/scripts/{id}/preview` | Render a preview using a real lead + agent |

Scripts use Markdown syntax. `{{placeholder}}` variables are **auto-detected** from the content — no separate declaration needed. When the agent opens a lead, each variable is replaced with the live value from the lead's `custom_fields` plus the agent's profile. Industry-specific placeholders (contract number, account ID, order code, ...) are declared as `custom_fields` per customer.

### `GET /api/telesales/scripts` — list

#### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `q` | string | optional | Search by `name` (LIKE %keyword%) | |
| `campaign_id` | integer | optional | Filter scripts in use by a given campaign | |
| `page` | integer | optional | Page number | ≥ 1 (default 1) |
| `per_page` | integer | optional | Records per page | 1-200 (default 50) |

#### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Script ID | |
| `name` | string | Script name (unique per account) | max 150 chars |
| `content_preview` | string | Markdown content — first 200 chars | |
| `placeholders_detected[]` | `array<string>` | `{{var_name}}` variables detected in the content | |
| `used_by_campaigns[]` | `array<integer>` | Campaign IDs currently using this script | |
| `created_at` | datetime | Creation timestamp (ISO 8601 UTC) | |
| `updated_at` | datetime | Last update timestamp (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "id": 12,
      "name": "Default Outbound Script",
      "content_preview": "## Opening\nHello {{customer_name}}...",
      "placeholders_detected": ["customer_name", "agent_name", "brand_name"],
      "used_by_campaigns": [36, 42],
      "created_at": "2026-06-06T06:00:00Z",
      "updated_at": "2026-06-06T06:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 3 }
}
```

`content_preview` is truncated to the first 200 chars. Use `GET /api/telesales/scripts/{id}` to fetch the full content.

### `GET /api/telesales/scripts/{id}` — detail

#### Path parameter

| Field | Type | Description |
|---|---|---|
| `id` | integer | Script ID |

#### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Script ID | |
| `name` | string | Script name | max 150 chars |
| `content` | string | Full Markdown content | max 32 KB |
| `placeholders_detected[]` | `array<string>` | `{{var_name}}` variables parsed from `content` | |
| `used_by_campaigns[]` | `array<object>` | Array of `{id, name}` for campaigns using this script | |
| `created_at` | datetime | Creation timestamp (ISO 8601 UTC) | |
| `updated_at` | datetime | Last update timestamp (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": {
    "id": 12,
    "name": "Default Outbound Script",
    "content": "## Opening\nHello {{customer_name}}, this is {{agent_name}} from {{brand_name}}...\n\n## Body\n... talk track ...\n\n## Closing\nThank you.",
    "placeholders_detected": ["customer_name", "agent_name", "brand_name"],
    "used_by_campaigns": [
      { "id": 36, "name": "Summer Promo" },
      { "id": 42, "name": "Retention Q3" }
    ],
    "created_at": "2026-06-06T06:00:00Z",
    "updated_at": "2026-06-06T06:00:00Z"
  }
}
```

**Response 404**: `{ "message": "Script not found." }`

### `POST /api/telesales/scripts` — create

#### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `name` | string | ✅ | Script name — unique per account | max 150 chars |
| `content` | string | ✅ | Markdown content; `{{placeholder}}` variables are auto-detected | max 32 KB |

**Body**:
```json
{
  "name": "Default Outbound Script",
  "content": "## Opening\nHello {{customer_name}}, this is {{agent_name}} from {{brand_name}}...\n\n## Body\n... talk track for the campaign ...\n\n## Closing\nThank you for your time."
}
```

#### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Newly created script ID | |
| `name` | string | Script name | |
| `content` | string | Markdown content | |
| `placeholders_detected[]` | `array<string>` | `{{var_name}}` variables parsed from `content` | |
| `created_at` | datetime | Creation timestamp (ISO 8601 UTC) | |

**Response 201**:
```json
{
  "data": {
    "id": 12,
    "name": "Default Outbound Script",
    "content": "## Opening\nHello {{customer_name}}...",
    "placeholders_detected": ["customer_name", "agent_name", "brand_name"],
    "created_at": "2026-06-06T06:00:00Z"
  }
}
```

**Response 422 — validation cases**:
```json
// Duplicate script name
{
  "message": "The given data was invalid.",
  "errors": { "name": ["The name has already been taken."] }
}

// Content too long
{
  "message": "The given data was invalid.",
  "errors": { "content": ["The content may not be greater than 32768 characters."] }
}
```

### `PUT /api/telesales/scripts/{id}` — update

**Body**: same as POST.

**Response 200**: the updated script object, with `placeholders_detected` re-computed from the new content.

**Response 422 — conflict**:
```json
// Script is in use by active campaigns — update is allowed with a warning
{
  "data": { "id": 12, ... },
  "warnings": ["Script is currently used by 2 active campaigns. Agents will see new content on next call."]
}
```

### `DELETE /api/telesales/scripts/{id}`

**Response 204 No Content** (success).

**Response 422** — script is in use by an active campaign:
```json
{
  "message": "Cannot delete a script that is in use by a campaign.",
  "errors": { "id": ["Script 12 is bound to campaign(s): 36, 42. Detach from campaign first."] }
}
```

### `POST /api/telesales/scripts/{id}/preview` — render preview

#### Path parameter

| Field | Type | Description |
|---|---|---|
| `id` | integer | Script ID to render |

#### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `lead_id` | integer | ✅ | Lead ID — supplies `{{customer_name}}` from `custom_fields` | Must exist |
| `agent_id` | integer | ✅ | Agent user ID — supplies `{{agent_name}}` from profile | Must exist |

**Body**:
```json
{
  "lead_id":   78912,
  "agent_id":  25
}
```

Renders the content with each `{{placeholder}}` replaced by the live value from `lead.custom_fields` + the agent's profile + the customer's brand.

#### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Script ID | |
| `rendered_content` | string | Markdown content with placeholders substituted | |
| `missing_placeholders[]` | `array<string>` | Variables that could not be resolved from `custom_fields` / profile — the UI can warn the agent | |

**Response 200**:
```json
{
  "data": {
    "id": 12,
    "rendered_content": "## Opening\nHello Anh Hung, this is Nguyen Van A from Zorio...\n\n## Body\n...",
    "missing_placeholders": ["policy_number"]
  }
}
```

---

## 6. Call Outcomes (Disposition Codes)

### 6.1 Disposition catalog management

| Endpoint | Purpose |
|---|---|
| `GET    /api/telesales/dispositions` | List the customer's dispositions |
| `GET    /api/telesales/dispositions/{id}` | Detail for one disposition |
| `POST   /api/telesales/dispositions` | Create a disposition (admin) |
| `PUT    /api/telesales/dispositions/{id}` | Update a disposition (admin) |
| `DELETE /api/telesales/dispositions/{id}` | Delete a disposition (admin) |

#### `GET /api/telesales/dispositions` — list

##### Query parameters

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `category` | string | optional | Filter by outcome group | `contact` / `no_contact` / `callback` / `remove` |
| `is_active` | bool | optional | Whether to include hidden dispositions | `true` (default) / `false` |

##### Response fields (each item in `data[]`)

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Disposition ID | |
| `code` | string | Immutable code — agents / API use this to tag calls | `[A-Za-z0-9_-]`, max 32 chars |
| `label` | string | Display label | max 100 chars |
| `description` | string\|null | Detailed description | max 500 chars |
| `category` | string | Outcome group | `contact` / `no_contact` / `callback` / `remove` |
| `is_final` | bool | Is this a final outcome or still retryable | `true` / `false` |
| `trigger_callback` | bool | Auto-create a callback when the agent picks this code | `true` / `false` (true only when `category=callback`) |
| `trigger_dnc` | bool | Auto-add the number to DNC when picked | `true` / `false` |
| `default_retry_delay_minutes` | integer\|null | Minutes to wait before retrying the lead if not final | 1-43200 (minutes) |
| `color` | string | Hex color for UI badge | `#RRGGBB` |
| `is_active` | bool | Whether it appears in the agent dropdown | `true` / `false` |
| `usage_count_30d` | integer | Calls that used this code in the last 30 days | ≥ 0 |
| `created_at` | datetime | Creation timestamp (ISO 8601 UTC) | |

**Response 200**:
```json
{
  "data": [
    {
      "id": 5,
      "code": "SALE-OK",
      "label": "Sale Success",
      "description": "Customer agreed and committed",
      "category": "contact",
      "is_final": true,
      "trigger_callback": false,
      "trigger_dnc": false,
      "default_retry_delay_minutes": null,
      "color": "#10b981",
      "is_active": true,
      "usage_count_30d": 78,
      "created_at": "2026-06-01T06:00:00Z"
    }
  ]
}
```

#### `GET /api/telesales/dispositions/{id}` — detail

##### Path parameter

| Field | Type | Description |
|---|---|---|
| `id` | integer | Disposition ID |

**Response 200**: disposition object (same shape as one element of the list).

**Response 404**: `{ "message": "Disposition not found." }`

#### `POST /api/telesales/dispositions` — create (admin)

##### Request body fields

| Field | Type | Required | Description | Valid values |
|---|---|---|---|---|
| `code` | string | ✅ | Immutable code — unique per account | `[A-Za-z0-9_-]`, max 32 chars |
| `label` | string | ✅ | Display label | max 100 chars |
| `description` | string | optional | Detailed description | max 500 chars |
| `category` | string | ✅ | Outcome group | `contact` / `no_contact` / `callback` / `remove` |
| `is_final` | bool | optional | Final outcome (no retry) | `true` / `false` (default `false`) |
| `trigger_callback` | bool | optional | Auto-create callback — requires `category=callback` | `true` / `false` (default `false`) |
| `trigger_dnc` | bool | optional | Auto-add number to DNC | `true` / `false` (default `false`) |
| `default_retry_delay_minutes` | integer | optional | Minutes before retrying the lead | 1-43200 |
| `color` | string | optional | UI color | `#RRGGBB` |

**Body**:
```json
{
  "code": "SALE-OK",
  "label": "Sale Success",
  "description": "Customer agreed and committed",
  "category": "contact",
  "is_final": true,
  "trigger_callback": false,
  "trigger_dnc": false,
  "default_retry_delay_minutes": null,
  "color": "#10b981"
}
```

##### Response fields

| Field | Type | Description | Valid values |
|---|---|---|---|
| `id` | integer | Newly created disposition ID | |
| `code` | string | Immutable code | |
| `label` | string | Display label | |
| `category` | string | Outcome group | `contact` / `no_contact` / `callback` / `remove` |
| `is_final` | bool | Final outcome | |
| `trigger_callback` | bool | Auto-create callback | |
| `trigger_dnc` | bool | Auto-add DNC | |
| `color` | string | Color | `#RRGGBB` |
| `is_active` | bool | Visible in the agent dropdown (default `true`) | |
| `created_at` | datetime | Creation timestamp (ISO 8601 UTC) | |

**Response 201**:
```json
{
  "data": {
    "id": 5,
    "code": "SALE-OK",
    "label": "Sale Success",
    "category": "contact",
    "is_final": true,
    "trigger_callback": false,
    "trigger_dnc": false,
    "color": "#10b981",
    "is_active": true,
    "created_at": "2026-06-06T06:00:00Z"
  }
}
```

**Response 422 — validation cases**:
```json
// Duplicate code
{
  "message": "The given data was invalid.",
  "errors": { "code": ["The code has already been taken."] }
}

// Invalid category
{
  "message": "The given data was invalid.",
  "errors": { "category": ["The selected category is invalid."] }
}

// trigger_callback=true but category is not 'callback'
{
  "message": "The given data was invalid.",
  "errors": { "trigger_callback": ["trigger_callback only applies when category='callback'."] }
}
```

**Response 403** — caller is not an admin:
```json
{ "message": "You are not allowed to create dispositions. The admin role is required." }
```

#### `PUT /api/telesales/dispositions/{id}` — update (admin)

##### Path parameter

| Field | Type | Description |
|---|---|---|
| `id` | integer | Disposition ID |

##### Request body fields

Same as POST but every field is optional — send only what you want to change. `code` **cannot be changed** after creation (immutable identifier); sending a new `code` returns 422.

| Field | Type | Description | Valid values |
|---|---|---|---|
| `label` | string | Display label | max 100 chars |
| `description` | string\|null | Detailed description | max 500 chars |
| `category` | string | Outcome group | `contact` / `no_contact` / `callback` / `remove` |
| `is_final` | bool | Final outcome | |
| `trigger_callback` | bool | Auto-create callback (true only when `category=callback`) | |
| `trigger_dnc` | bool | Auto-add DNC | |
| `default_retry_delay_minutes` | integer\|null | Retry delay in minutes | 1-43200 |
| `color` | string | Color | `#RRGGBB` |
| `is_active` | bool | Show/hide in dropdown | `true` / `false` |

**Response 200**: the updated object.

**Response 422**:
```json
// Attempt to change code
{
  "message": "The given data was invalid.",
  "errors": { "code": ["Code is immutable. Create a new disposition if a different code is needed."] }
}
```

#### `DELETE /api/telesales/dispositions/{id}` — delete (admin)

##### Path parameter

| Field | Type | Description |
|---|---|---|
| `id` | integer | Disposition ID to delete |

**Response 204 No Content** (success — soft delete; sets `is_active=false`).

**Response 422** — disposition is in use:
```json
{
  "message": "Cannot delete a disposition with associated call history.",
  "errors": { "id": ["Disposition 5 has 78 calls in last 30 days. Hide instead of deleting (set is_active=false)."] }
}
```

::: tip Hide vs Delete
To preserve reporting history, delete defaults to soft delete (set `is_active=false`). Old dispositions still appear in reports but are hidden from the agent dropdown. Hard delete is only allowed when `usage_count = 0`.
:::

### 6.2 Suggested seed catalog (8 common codes)

Each new account is seeded with a generic catalog that is not tied to any industry. Customers can extend or replace it through the API or the admin UI.

| Code | Label | Category | is_final | trigger_callback | trigger_dnc |
|---|---|---|---|---|---|
| `SUCCESS` | Successful Contact | contact | x | | |
| `CALLBACK_REQ` | Customer Asked for Callback | callback | | x | |
| `REFUSED` | Customer Refused | contact | x | | |
| `NO_ANSWER` | No Answer | no_contact | | | |
| `BUSY` | Busy | no_contact | | | |
| `VOICEMAIL` | Voicemail Left | no_contact | | | |
| `WRONG_NUMBER` | Wrong Number | remove | x | | |
| `DNC_REQUEST` | DNC Request | remove | x | | x |

For **industry-specific catalogs** (customer care, service appointments, surveys, medical appointments, ...), see the **separate per-customer configuration package** — it will pre-seed an extended code set tailored to the business workflow.


---

# API Token (machine-to-machine)

<!-- source: https://docs.zorio.vn/en/auth/api-token.md -->

# API Token (machine-to-machine)

API tokens are issued to **machine clients** (CRM backends, dialer engines, integration services) that call the Zorio API **without being tied to a user session**. They suit server-to-server traffic, cron jobs, and integration microservices.

## How they differ from Bearer (user session) tokens

| Property | Bearer (user session) | API Token (machine) |
|---|---|---|
| Tied to | One specific user | One app / service |
| When the user logs out | Token is invalidated | Still alive |
| When the user changes their password | Still alive | Still alive |
| Audit log entries | Use `user.username` | Use the application name |
| Best for | Apps with users (frontend, mobile) | Server-to-server / cron |

::: tip
Both schemes use the same `Authorization: Bearer <token>` header — they're distinguished by **how they're issued** and **how they show up in audit logs**, not by token format.
:::

## Create an API token

::: warning Admins only
API tokens can only be created by an account admin through the **Admin Console**. There is no public API to self-issue tokens (this prevents a CRM from cloning its own tokens).
:::

### Steps

1. Go to **Admin Console → Settings → API Tokens**.
2. Pick the **Machine Tokens** tab (different from "User Tokens").
3. Click **Create Machine Token**:
   - **Name** — e.g. "CRM Salesforce Production", "Dialer Engine v2".
   - **Permission scope** — pick specific permissions (e.g. `pbx_api_access`, `telesales_create_lead`).
   - **IP whitelist** (optional) — only accept requests from listed IPs.
   - **Expiration** (optional) — auto-expire after N days.
4. The system generates the token → **copy it once, immediately**.

## Use an API token

Same as Bearer (user session) — just add `Authorization: Bearer <token>` to every request.

```bash
curl -X POST 'https://app.zorio.vn/api/pbx/calls/click-to-call' \
  -H 'Authorization: Bearer <YOUR_MACHINE_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"from_extension":"1001","to_phone":"0987654321"}'
```

## Permission scope

An API token has a **narrower scope than a user** — it can only perform actions listed in the permissions selected at creation time.

Common scopes:

| Scope | Allows |
|---|---|
| `pbx_api_access` | Every `/api/pbx/*` endpoint |
| `manage_caller_ids` | CRUD on caller IDs and groups |
| `telesales_api_access` | Read/write Telesales campaigns and leads |
| `autocall_api_access` | Read/write AutoCall campaigns and leads |
| `view_all_cdr` | Read CDR for the entire account |
| `view_team_cdr` | Read CDR only within a team |

To inspect the current token's permissions:

```
GET /api/auth/me
Authorization: Bearer <token>
```

Response 200 returns a `permissions[]` array.

## IP whitelist

When a token is created with an IP whitelist:

- Requests from any IP **not in the list** → HTTP 403 with body `{ "message": "Forbidden: IP not whitelisted." }`.
- `0.0.0.0/0` = accept every IP (the default).
- CIDR ranges are supported (e.g. `203.0.113.0/24`).

::: tip Load balancer note
If your app sits behind a load balancer / nginx proxy — Zorio reads the IP from the `X-Forwarded-For` header (the `client, proxy1, proxy2` chain). Your LB must forward the real client IP correctly.
:::

## Audit log

Every request made with an API token is logged with:

| Field | Description |
|---|---|
| `token_name` | Token name (e.g. "CRM Salesforce Production") |
| `ip` | Source IP |
| `endpoint` | Method + path |
| `status` | HTTP response status |
| `at` | Timestamp |

Browse at **Admin Console → Audit Log → API Token Activity**.

## Rotate tokens

For security, rotate tokens regularly (every **90 days** is the recommended cadence):

1. Go to Admin Console → API Tokens → click **Rotate** next to the token.
2. The system mints a new token — copy it.
3. **Deploy the new token to your app**.
4. Verify the app is healthy with the new token.
5. **Revoke** the old token after you've confirmed.

::: warning Don't rotate two tokens at once
If your app uses several tokens (e.g. LB → N replicas), rotate them one at a time, not simultaneously, so you keep a rollback path if something breaks.
:::

## Revoke

When a token is compromised or no longer needed — **Admin Console → API Tokens → Revoke**. Any request with the token after revocation → HTTP 401.

::: danger Revoke immediately on suspected leak
- Code with the token accidentally committed to a public git repo.
- A server holding the token was hacked.
- A staff member with token-creation rights left the company.

Revoke now, don't wait for an investigation. Mint a new token and redeploy.
:::

## Add the token to CI/CD

| Tool | How to store the token |
|---|---|
| GitHub Actions | Repository secret → `ZORIO_API_TOKEN` |
| GitLab CI | CI/CD Variables (Masked + Protected) |
| Jenkins | Credentials → Secret Text |
| Vault | Path `secret/zorio/api-token` → fetch at deploy time |
| Kubernetes | Secret → mount as env var on the pod |

DO NOT echo tokens to build logs. Most CI tools have a "masked output" flag — enable it.

## Sample server-to-server (cron lead import)

```js
// cron-job.js — runs every 5 minutes
const axios = require('axios');

const api = axios.create({
  baseURL: 'https://app.zorio.vn/api',
  headers: {
    Authorization: 'Bearer ' + process.env.ZORIO_TOKEN,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  timeout: 30_000,
});

async function syncLeads() {
  const crmLeads = await fetchFromCRM();
  for (const lead of crmLeads) {
    try {
      await api.post(`/telesales/campaigns/${lead.campaign_id}/leads`, {
        phone: lead.phone,
        custom_fields: lead.fields,
      });
    } catch (err) {
      if (err.response?.status === 422) {
        console.error('Lead invalid:', lead, err.response.data.errors);
      } else {
        throw err;
      }
    }
  }
}

syncLeads().catch(console.error);
```

## Related docs

- [Obtain an API token](/en/getting-started/obtain-token)
- [Bearer (user session)](/en/auth/sanctum-bearer)
- [Rate limit & Idempotency](/en/auth/rate-limit)
- [Webhook HMAC-SHA256 signing](/en/auth/webhook-hmac)


---

# Rate limit & Idempotency

<!-- source: https://docs.zorio.vn/en/auth/rate-limit.md -->

# Rate limit & Idempotency

Two mechanisms Zorio uses to protect the API and to help your CRM retry safely.

## Rate limit

### Goals

- Protect the Zorio platform from request floods (accidental or DDoS).
- Keep things fair between customer accounts — no single account should monopolize resources.
- Encourage CRMs to cache and batch instead of hammering endpoints.

### Default limits

Counted **per token** (each token has its own bucket):

| Endpoint group | Limit | Window |
|---|---|---|
| `/api/pbx/calls/click-to-call` | **10 req/min** | 60-second sliding window |
| `/api/pbx/*` (every other endpoint) | **60 req/min** | 60-second sliding window |
| `/api/telesales/*` | **120 req/min** | 60-second sliding window |
| `/api/autocall/*` | **120 req/min** | 60-second sliding window |
| `/api/auth/login` | **5 req/min** | 60-second sliding window (brute-force protection) |
| `/api/auth/*` (other endpoints) | **30 req/min** | 60-second sliding window |

::: tip Need higher limits?
Enterprise customers can request higher limits through their SLA. Reach out to the Zorio team.
:::

### Response headers

Every response includes:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1782706011
```

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Total allowed requests in the window |
| `X-RateLimit-Remaining` | Requests still available in the window |
| `X-RateLimit-Reset` | UTC epoch seconds when the quota resets to `Limit` |

### When you exceed the limit

HTTP 429 with body:

```json
{ "message": "Too many requests. Retry after 25 seconds." }
```

Headers:

```
Retry-After: 25
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782706036
```

### CRM best practices

#### 1. Respect `Retry-After`

```js
const response = await fetch(url, options);
if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After'), 10) || 60;
  await sleep(retryAfter * 1000);
  return retry();
}
```

#### 2. Exponential backoff + jitter

Avoid the thundering herd when many clients retry at once:

```js
async function callWithBackoff(fn, attempt = 0) {
  try {
    return await fn();
  } catch (err) {
    if (err.status !== 429 && err.status < 500) throw err;
    if (attempt >= 5) throw err;

    const baseDelay = Math.min(1000 * Math.pow(2, attempt), 30_000);
    const jitter = Math.random() * 1000;
    await sleep(baseDelay + jitter);
    return callWithBackoff(fn, attempt + 1);
  }
}
```

#### 3. Use batch endpoints where available

Several endpoints support batching:

- `POST /api/telesales/campaigns/{id}/leads/bulk-import` — import N leads at once
- `PATCH /api/telesales/leads/bulk` — update N leads at once
- `DELETE /api/telesales/leads/bulk` — delete N leads at once

Batching saves rate-limit budget and runs faster than looping single calls.

#### 4. Cache responses

Slow-changing resources (e.g. `caller-ids`, `queues`, `users`) — cache for 1-5 minutes on the CRM side. Don't poll every second.

#### 5. Monitor `X-RateLimit-Remaining`

When `Remaining < 5` — slow down proactively, don't wait until you hit 0.

## Idempotency

### Problem

When a client retries a POST/PATCH/DELETE due to a timeout, how do you guarantee:

- No **duplicate** resources (e.g. two leads with the same phone).
- No **double charge** (e.g. two calls fired from one click).
- No **double action** (e.g. disposition recorded twice for the same call).

### Zorio's solution: Idempotency-Key

Clients send an `Idempotency-Key: <UUID v4>` header on each retry-able request.

```bash
curl -X POST 'https://app.zorio.vn/api/pbx/calls/click-to-call' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -d '{"from_extension":"1001","to_phone":"0987654321"}'
```

### How Zorio handles it

1. **First time** Zorio sees the `Idempotency-Key` → processes the request normally and caches the response under that key (TTL 24h).
2. **Subsequent requests** with the same key → return the cached response immediately, no reprocessing.

### Endpoints that support Idempotency-Key

| Method + endpoint | Why you need it |
|---|---|
| `POST /api/pbx/calls/click-to-call` | Avoid firing two calls on a network glitch |
| `POST /api/telesales/campaigns` | Avoid creating two campaigns with the same name |
| `POST /api/telesales/campaigns/{id}/leads` | Avoid duplicate leads |
| `POST /api/autocall/campaigns` | Avoid creating two campaigns with the same name |
| `POST /api/integrations/sms` | Avoid sending the same SMS twice (double charge) |

### Idempotency-Key requirements

- **Format**: UUID v4 (`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`).
- **Unique per request**: DO NOT reuse a key for a different request — you'll get the old response back.
- **TTL 24 hours**: after 24h the key expires; a retry with the same key may then create a new resource.

### Node.js integration sample

```js
const { v4: uuidv4 } = require('uuid');

async function clickToCall(fromExt, toPhone) {
  const key = uuidv4();

  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      const res = await api.post('/pbx/calls/click-to-call', {
        from_extension: fromExt,
        to_phone: toPhone,
      }, {
        headers: { 'Idempotency-Key': key },
      });
      return res.data;
    } catch (err) {
      if (attempt === 2) throw err;
      await sleep(1000 * (attempt + 1));
    }
  }
}
```

→ Even with 3 retries, only **one call** is created.

### Notes

- The request body must be **identical** across retries (with the same `Idempotency-Key`). A different body → HTTP 422 with `"message": "Idempotency-Key was used with a different body."`.
- Endpoints that **do not support** Idempotency-Key silently ignore the header — no error.

## Concurrency control

### Optimistic locking with `If-Match`

Some update endpoints support `If-Match` to prevent races:

```
PUT /api/pbx/extensions/1001
If-Match: "etag-abc123"
```

If the resource has changed between the client's GET and PUT → ETag mismatch → HTTP 412 `{ "message": "Resource has changed, please GET again." }`. Your CRM must re-fetch and re-apply changes.

### Connection limit

- Max **20 concurrent connections** per token.
- Exceed → HTTP 429 with body `{ "message": "Too many concurrent connections." }`.

## Related docs

- [Bearer (user session)](/en/auth/sanctum-bearer)
- [API Token](/en/auth/api-token)
- [HTTP status codes](/en/reference/http-codes) — details on 429
- [Webhook retry policy](/en/webhooks/retry) — receiver-side idempotency


---

# Bearer (user session)

<!-- source: https://docs.zorio.vn/en/auth/sanctum-bearer.md -->

# Bearer (user session)

Bearer (user session) tokens are an authentication scheme **tied to a user's login session** in the Admin Console. They fit integrations that **have an end user** (frontends, internal dashboards, in-house mobile apps).

## When to use Bearer (user session)

| Use case | Recommended scheme |
|---|---|
| Vue / React / Mobile frontend calling the API on behalf of a user | **Bearer (user session)** ✅ |
| CRM acting under user context (e.g. "Sales A click-to-call") | **Bearer (user session)** ✅ |
| Server-to-server background jobs (no user involved) | [API Token](/en/auth/api-token) |
| Webhook receiver verifying events pushed by Zorio | [HMAC-SHA256 signing](/en/auth/webhook-hmac) |

## Get a token

### Option 1 — Log in via API

**Endpoint**: `POST /api/auth/login`

#### Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | string | ✅ | User's login name |
| `password` | string | ✅ | Password |
| `device_name` | string | optional | Device / app label to distinguish tokens (e.g. `CRM-Salesforce`, `iPhone-Sales-01`) |

```json
{
  "username": "sales01",
  "password": "...",
  "device_name": "CRM-Salesforce"
}
```

#### Response 200

```json
{
  "data": {
    "user": {
      "id": 7,
      "username": "sales01",
      "email": "sales01@example.com",
      "role": "agent",
      "team_id": 2
    }
  },
  "token": "12|abcdefghijklmnopqrstuvwxyz0123456789"
}
```

**Store the token** immediately in secure storage (httpOnly cookie or mobile keychain). The token is a `<id>|<random>` string.

#### Response 401

```json
{ "message": "Invalid username or password." }
```

#### Response 422

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "username": ["The username field is required."]
  }
}
```

### Option 2 — Create a token from the Admin Console

Go to **Settings → API Tokens** → click **Create new token** → name it and pick a permission scope. The token is shown only once — copy it right away.

## Use the token in requests

Every request must include two headers:

```
Authorization: Bearer <token>
Accept: application/json
```

### cURL example

```bash
curl -X GET 'https://app.zorio.vn/api/pbx/extensions' \
  -H 'Authorization: Bearer 12|abcdefghijklmnopqrstuvwxyz' \
  -H 'Accept: application/json'
```

### Node.js example (axios)

```js
const axios = require('axios');

const api = axios.create({
  baseURL: 'https://app.zorio.vn/api',
  headers: {
    Authorization: 'Bearer ' + process.env.ZORIO_TOKEN,
    Accept: 'application/json',
  },
});

const res = await api.get('/pbx/extensions');
console.log(res.data);
```

### PHP example (Guzzle)

```php
$client = new GuzzleHttp\Client([
    'base_uri' => 'https://app.zorio.vn/api/',
    'headers'  => [
        'Authorization' => 'Bearer ' . getenv('ZORIO_TOKEN'),
        'Accept'        => 'application/json',
    ],
]);
$res = $client->get('pbx/extensions');
```

## Logout / Revoke

### Logout current session

```
POST /api/auth/logout
Authorization: Bearer <token>
```

Returns 200 `{ "data": { "logged_out": true } }`. The token is invalidated immediately — any later request with it → 401.

### Revoke a specific token (admin)

Go to **Admin Console → API Tokens** → click **Revoke** next to the token you want to remove.

### Revoke all of a user's tokens (logout-all)

```
POST /api/auth/logout-all
Authorization: Bearer <token>
```

All of the user's live tokens are invalidated — use this when an account is suspected to be compromised.

## Token lifetime

- By default tokens **do not auto-expire** — only manual revoke removes them.
- An **expiration policy** can be configured in the Admin Console: 30 / 60 / 90 / 180 days.
- Once expired or revoked → the API returns **HTTP 401** with body `{ "message": "Unauthenticated." }`.

## Whoami (check the current token)

```
GET /api/auth/me
Authorization: Bearer <token>
```

Response 200:

```json
{
  "data": {
    "id": 7,
    "username": "sales01",
    "email": "sales01@example.com",
    "role": "agent",
    "team_id": 2,
    "permissions": ["pbx_api_access", "telesales_make_call", "view_my_cdr"]
  }
}
```

Your CRM can call this on startup to learn the current user and check their permissions.

## Change password

```
POST /api/auth/change-password
Authorization: Bearer <token>

{
  "current_password": "...",
  "new_password": "...",
  "new_password_confirmation": "..."
}
```

Response 200 `{ "data": { "changed": true } }`. The **current token is NOT invalidated** — the user keeps their session.

## Best practice

- DO NOT hardcode tokens in frontend code (they leak through DevTools).
- DO NOT commit tokens to git.
- Long-lived tokens → store in a vault (1Password, AWS Secrets Manager, HashiCorp Vault).
- Rotate tokens every 90 days.
- One token per app / device (`device_name`) so you can revoke them in a targeted way.
- Catch 401 gracefully → redirect the user to login, don't crash the app.

## Related docs

- [Obtain an API token](/en/getting-started/obtain-token)
- [API Token (machine-to-machine)](/en/auth/api-token)
- [Rate limit & Idempotency](/en/auth/rate-limit)


---

# Webhook HMAC-SHA256 signing

<!-- source: https://docs.zorio.vn/en/auth/webhook-hmac.md -->

# Webhook HMAC-SHA256 signing

For deeper coverage and full sample receivers see [Webhooks → HMAC-SHA256 signing](/en/webhooks/hmac). This page is a quick summary so a new technical CRM team can grasp the signing and verification model.

## Why HMAC

Your CRM receives webhooks pushed by Zorio to your URL. Without signing:

- An attacker can **impersonate Zorio** → POST fake events to your URL → your CRM mishandles them.
- Payloads can be **modified in transit** (man-in-the-middle).
- An attacker can **replay** a captured valid event.

HMAC-SHA256 signing solves all three.

## Mechanics

### When you create the webhook

When you register a webhook through the Admin Console, the system generates a **secret** (32 alphanumeric chars). You:

1. Copy the secret immediately (shown only once).
2. Store it in your receiver's environment (`ZORIO_WEBHOOK_SECRET`).
3. DO NOT hardcode it, DO NOT commit it to git.

### On every event Zorio delivers

Zorio sends a POST with these headers:

```
X-Zorio-Event: pbx.call.hangup
X-Zorio-Timestamp: 1782706011
X-Zorio-Delivery: 7c9e6679-7425-40de-944b-e07fc1f90ae7
X-Zorio-Signature: sha256=ab9d7f4...
Content-Type: application/json; charset=utf-8
```

### How Zorio computes the signature

```
signature = "sha256=" + lowercase(hex(HMAC-SHA256(secret, raw_body)))
```

- `secret`: the secret you stored when creating the webhook.
- `raw_body`: the raw bytes of the request body (DO NOT parse JSON first).

## How a receiver verifies

### Four steps

1. **Reject stale timestamps** — if `X-Zorio-Timestamp` is more than **300 seconds** off from now → reject with 400.
2. **Recompute the signature** using your secret and the raw body.
3. **Constant-time compare** against `X-Zorio-Signature` — use your language's timing-safe API.
4. **Dedupe** by `X-Zorio-Delivery` UUID — use a distributed NX lock with 24h TTL.

### Node.js sample (minimal)

```js
const crypto = require('crypto');

function verifyZorioWebhook(req, secret) {
  // 1. Timestamp window
  const ts = parseInt(req.headers['x-zorio-timestamp'], 10);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) {
    throw new Error('Stale timestamp');
  }

  // 2. Recompute
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(req.rawBody).digest('hex');

  // 3. Timing-safe compare
  const sig = req.headers['x-zorio-signature'] || '';
  if (sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    throw new Error('Invalid signature');
  }
}
```

### PHP / Python / Go samples

See [Sample receivers in 4 languages](/en/webhooks/sample-receivers).

## Common pitfalls

### Parsing JSON before computing the HMAC

```js
// WRONG — body was already mutated by the parser
app.use(express.json());
app.post('/webhook', (req, res) => {
  const expected = createHmac(secret, JSON.stringify(req.body)).digest('hex');
  // → never matches because JSON.stringify differs from the bytes Zorio sent
});

// RIGHT — use the raw bytes
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = createHmac(secret, req.body).digest('hex');
});
```

### Using `==` instead of timing-safe compare

```js
// WRONG — leaks signature byte-by-byte through timing attacks
if (sig === expected) { ... }

// RIGHT
if (crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) { ... }
```

### Not checking the timestamp

Skipping the timestamp check enables replay attacks. An attacker who captures one valid event can replay it a thousand times, even years later, and the signature still verifies.

### Reverse proxy modifying the body

Some reverse proxies (nginx + a compression module) or Cloudflare can re-compress the body → the bytes change. Disable compression for the webhook route:

```nginx
location /webhook {
    gzip off;
    proxy_pass http://app;
}
```

### Wrong TLS setup

Zorio only delivers to HTTPS URLs. If your TLS cert is:

- Self-signed → Zorio rejects immediately.
- Expired → Zorio rejects.
- Hostname mismatch → Zorio rejects.

Test: `curl https://your-webhook-url/` from the public internet, with no cert errors.

## Optional second-layer replay protection

For stronger security, dedupe by `(timestamp + body hash)` on top of `Delivery UUID`:

```js
const fingerprint = ts + ':' + sha256(rawBody);
const isNew = await redis.set(`zorio:fp:${fingerprint}`, '1', 'NX', 'EX', 600);
if (!isNew) return res.status(200).send('Duplicate fingerprint');
```

Why: even if an attacker captures a valid request within the 300s window, they can't replay it because the fingerprint has already been seen.

## Related docs

- [Webhook → Register](/en/webhooks/register)
- [Webhook → HMAC signing in detail](/en/webhooks/hmac)
- [Webhook → Retry policy](/en/webhooks/retry)
- [Webhook → Sample receivers in Node/PHP/Python/Go](/en/webhooks/sample-receivers)


---

# Core concepts

<!-- source: https://docs.zorio.vn/en/getting-started/concepts.md -->

# Core concepts

## Customer account

Each Zorio customer gets an isolated system with:

- A dedicated access domain (e.g. `app.zorio.vn` or a custom domain configured by the customer).
- A dedicated API token for each system.

## Domain & Base URL

| Type | Format | Example |
|---|---|---|
| Admin console | customer's domain | `app.zorio.vn` |
| API endpoint | `<domain>/api/...` | `app.zorio.vn/api/pbx/extensions` |
| SIP/WebRTC | `<domain>:5061` (TLS) | `app.zorio.vn:5061` |
| Webhook delivered by Zorio | your receiver URL | (you configure it) |

## Roles & Permission tiers

Users in an account have a role:

- **admin**: full power within the account.
- **supervisor**: manages teams / campaigns.
- **agent**: makes/answers calls and updates leads.
- **read_only**: read-only.

Permission tiers apply to modules (e.g. `crm`, `pbx`, `autocall`):

- **viewer**: read-only.
- **operator**: basic CRUD operations.
- **admin**: full module rights.

::: tip Note
The `pbx_api_access` permission is a prerequisite for calling the PBX API. Same for `telesales_api_access`, `autocall_api_access`.
:::

## Data isolation

Every resource is enforced per account at the backend layer. A token used against the wrong customer → HTTP 404 (to avoid leaking existence).


---

# Conventions

<!-- source: https://docs.zorio.vn/en/getting-started/conventions.md -->

# Conventions

## Base URL

| Type | URL |
|---|---|
| REST API | `https://app.zorio.vn/api/` |
| Webhook receiver (you host) | your URL |

The access domain is provisioned during onboarding.

## Standard headers

Every request:

```
Authorization: Bearer <token>
Accept: application/json
```

Every request with a body:

```
Content-Type: application/json; charset=utf-8
```

## Response shape

### Single resource / action

```json
{ "data": {} }
```

### List (paginated)

```json
{
  "current_page": 1,
  "data": [],
  "last_page": 5,
  "per_page": 50,
  "total": 234
}
```

### Error

```json
{
  "message": "Short error description",
  "errors": { "field_name": ["Detailed message"] }
}
```

## Pagination

Query `?page=1&per_page=50` (default 50, max 200).

## Timestamps & timezone

All datetimes are **ISO 8601** with offset:

- UTC: `2026-06-30T03:30:45+00:00`
- VN: `2026-06-30T10:30:45+07:00`

When sending requests, formats with or without microseconds (`.000000Z`) are both accepted.

## Common status codes

| HTTP | When |
|---|---|
| 200 | OK |
| 201 | Created |
| 202 | Accepted (async) |
| 400 | Bad request |
| 401 | Token missing / invalid / expired |
| 403 | Missing permission |
| 404 | Resource not found |
| 409 | Conflict (duplicate / state machine violation) |
| 422 | Validation error |
| 429 | Rate limit hit (with `Retry-After`) |
| 500 | Server error |

## Phone number format

- **Stored in DB**: E.164 without the leading `+` (e.g. `84987654321`).
- **Request body accepts**: both `0987654321` and `84987654321` — the backend normalizes.
- **Response returns**: the original format sent by the client (preserved).

## Recording URL

Recordings are served through a **signed URL** with a **30-minute** TTL (HMAC SHA256). Download within 30 minutes — past that, request a fresh URL through the `/recording` endpoint.


---

# Introduction

<!-- source: https://docs.zorio.vn/en/getting-started/introduction.md -->

# Introduction

Zorio is a Contact Center platform for businesses, consisting of:

- **PBX**: SIP/WebRTC switchboard with internal extensions, queues, IVR, recording, and click-to-call.
- **Telesales**: dialer + campaigns + leads + caller-ID rotation + reports + audit log.
- **AutoCall TTS**: voice bot for outbound automation with DTMF actions and a voice library.
- **Webphone SDK**: WebRTC SDK to embed a webphone inside customer CRMs or custom apps.
- **Outbound webhooks**: real-time events delivered with industry-standard HMAC-SHA256 signing.

This documentation is for:

| Audience | Purpose |
|---|---|
| **CRM partners** | Integrate Zorio into a custom CRM (Salesforce, HubSpot, Odoo, in-house...) |
| **Enterprise engineering teams** | Build custom apps around a provisioned Zorio system |
| **AI agents** (Claude Code, Codex, GPT...) | Read docs automatically, generate integration code, debug requests |
| **Any developer** | Reference the public REST API and SDKs of Zorio |

## Typical integration steps

1. **Obtain access credentials**: log in to your provisioned Zorio account → go to Settings → API Tokens → create a new token.
2. **Pick the module to integrate**: PBX (basic calls), Telesales (dialer), AutoCall (TTS bot), Webphone (call UI).
3. **Read the corresponding module docs** in this portal.
4. **Test an endpoint** with cURL or Postman.
5. **Set up webhooks** if you need real-time events.
6. **Deploy to production**.

## Integration architecture

```
┌──────────────────────────┐
│ Your system / CRM        │
└──────────┬───────────────┘
           │
   REST API (Bearer token)  +  Webhook (HMAC-SHA256)  +  Webphone SDK
           │
┌──────────▼───────────────┐
│ app.zorio.vn    │  ← main REST API endpoint
│  ├─ /api/pbx/...         │
│  ├─ /api/telesales/...   │
│  ├─ /api/autocall/...    │
│  └─ /api/integrations/   │
└──────────┬───────────────┘
           │
┌──────────▼───────────────┐
│ Zorio PBX (SIP/WebRTC)  │
└──────────────────────────┘
```

## Next

- [Core concepts](/en/getting-started/concepts) — Customer accounts, domains, roles, permission tiers.
- [Obtain an API token](/en/getting-started/obtain-token) — Issue a token from your provisioned account.
- [Conventions](/en/getting-started/conventions) — Base URL, pagination, error format, timestamps.


---

# Obtain an API token

<!-- source: https://docs.zorio.vn/en/getting-started/obtain-token.md -->

# Obtain an API token

## Overview

An API token is a **Bearer (user session) token** issued to a customer's user. Each user manages their own tokens — admins can revoke any user's tokens.

## Get a token from your provisioned account

1. **Log in** to the admin console: `https://app.zorio.vn`
2. Go to **Settings** → **API Tokens**.
3. Click **Create new token** → name it and pick a permission scope.
4. **Copy the token immediately** — it's only shown once. If lost → revoke and create a new one.

::: warning Token security
- DO NOT commit tokens to git.
- DO NOT embed tokens in frontend code.
- Store tokens in a vault / secret manager (1Password, AWS Secrets Manager, ...).
- A token can be **revoked** at any time → your CRM must handle 401 gracefully.
:::

## Use the token in requests

Every HTTP request to the API must include two headers:

```
Authorization: Bearer <YOUR_TOKEN>
Accept: application/json
```

### cURL example

```bash
curl -X GET 'https://app.zorio.vn/api/pbx/extensions' \
  -H 'Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz0123456789' \
  -H 'Accept: application/json'
```

### Node.js example

```js
const response = await fetch('https://app.zorio.vn/api/pbx/extensions', {
  headers: {
    Authorization: 'Bearer ' + process.env.ZORIO_TOKEN,
    Accept: 'application/json',
  },
});
const json = await response.json();
```

## Token rotation

Rotate every 90 days — industry standard.

## When a token is revoked

The API returns **HTTP 401** with body:

```json
{ "message": "Unauthenticated." }
```

Your CRM should catch 401 → show a "Token expired" message and direct the user to the admin console to get a fresh token.


---

# FAQ

<!-- source: https://docs.zorio.vn/en/reference/faq.md -->

# FAQ

The most frequent integration questions. If yours isn't here, reach out to Zorio support.

## Auth & API Tokens

### What if I lose my token?

A token is shown only once at creation; it can't be retrieved. Go to Admin Console → API Tokens → **Revoke** the old token → create a new one. Update your CRM with the fresh token.

### Do tokens expire?

User-session tokens **don't auto-expire** by default — they only go away on manual revoke by an admin. The industry-standard advice is to **rotate every 90 days**. You can rotate yourself: create a new token → update the CRM → revoke the old one.

### Can I use OAuth2 instead of Bearer tokens?

OAuth2 is not supported yet. Currently only Bearer (user session) is available.

### Is there a sandbox to test before production integration?

Each customer is provisioned their own account. Use the provisioned account for testing — there's no shared sandbox.

## PBX

### Click-to-call isn't working?

Check in this order:

1. Does the token have `pbx_api_access` permission?
2. Does `from_extension` exist and have `status=active` in the account?
3. Is `to_phone` formatted as `^[0-9+]+$`?
4. If you passed `trunk_id` — does the trunk have `status=active`?
5. If no trunk was passed — has the admin configured outbound routing?
6. Is the webhook receiver online (to receive `ringing` / `answered` / `hangup` events)?

### How do I click-to-call with a per-customer caller ID?

Pass the `caller_id` field in the body. The number must belong to the account's `active` caller-IDs — fetch them with `GET /api/pbx/caller-ids`.

### Recording URL expires in 30 minutes — what if a customer needs to download it later?

Call `GET /api/pbx/cdr/{uuid}` again to receive a new signed URL (TTL 30' from the request time). The old URL is expired; a new request mints a different URL.

### When to use `pbx.call.hangup` vs `pbx.cdr.created`?

- `pbx.call.hangup`: fires in real time as the call ends, **before** `recording_url` is available.
- `pbx.cdr.created`: fires after the CDR pipeline finishes, **with** `recording_url` and a more detailed `result` classification.

CRMs that need real-time → subscribe to `pbx.call.hangup`. CRMs that need full data + recording → subscribe to `pbx.cdr.created`.

### Can I filter a webhook to a specific extension?

Not yet. The webhook receives ALL PBX events for the account. Filter on the receiver side with `data.extension`.

## Telesales

### How many leads can a single campaign hold?

No hard cap. Recommendation: ≤ **100,000 leads** per campaign to keep dashboard reports snappy.

### Can leads be duplicated?

Not by default — the system dedupes by `(campaign_id, phone)`. If you need duplicates (e.g. same campaign, different strategy), create two separate campaigns.

### What disposition values are available?

There's a **default catalog** seeded for every new account ("Scheduled callback" / "No answer" / "Busy" / "Rejected" / ...). Customers can add new dispositions via the API or Admin Console.

### Do I get a webhook when an agent scores a call?

Subscribe to `telesales.call.disposed` — it fires immediately after the agent sets the outcome.

## AutoCall TTS

### Tier A vs Tier B — which to pick?

- **Tier A**: higher voice quality, real-time (each call is rendered fresh), charged per character. Good for dynamic text (e.g. announcing a customer-specific amount).
- **Tier B**: uses a pre-rendered audio library, no per-character charge, high throughput. Good for fixed text or high volume.

Recommended default: `B` for > 1,000 calls/day.

### Which voices support Vietnamese?

Tier B ships a pre-rendered `vi-VN-female-01` for Vietnamese. Tier A has more voices through the premium TTS vendor — list them with `GET /api/autocall/voices`.

### Where do I get DTMF input?

Subscribe to `autocall.lead.dtmf_pressed` — it fires every time the caller presses a key. The payload includes `digit`, `lead_id`, and `script_id`.

## Webhook

### My receiver sometimes doesn't get events?

Check in this order:

1. In Admin Console → Webhook deliveries — are any entries marked `failed` / `deadletter`?
2. Is the receiver verifying HMAC correctly (using the RAW body, not parsed JSON)?
3. Does the receiver return 200 within < 5s (check your server metrics)?
4. Is the URL's TLS cert valid (test with `curl https://your-url/`)?

### The same event arrives multiple times — is this a bug?

No. Zorio retries when the receiver returns non-2xx or times out. The receiver MUST dedupe by `X-Zorio-Delivery` (UUID).

### I switched the webhook URL mid-stream — where do queued events go?

Events still in the retry queue go to the **new** URL after the update. Events already in `deadletter` are not retried automatically — an admin needs to replay them manually.

## Webphone SDK

### Which browsers does the SDK support?

Chrome 88+, Edge 88+, Firefox 78+, Safari 14+. IE11 is NOT supported.

### My iframe won't load — Mixed Content?

The page hosting the iframe MUST be HTTPS. The webphone iframe must also be HTTPS. If an HTTP page embeds an HTTPS iframe — the browser blocks it for security.

### The webphone loses registration after a few minutes?

SDK v7+ has auto-reconnect + re-register supervisor. If you still lose registration:

- Check the `events` log for an `auto_reconnect` emission.
- Is there a network proxy blocking WebSocket (ws://)?
- Is your TLS wildcard cert still valid?

### How do I customize the webphone UI?

The SDK ships with a default vanilla-DOM UI. To customize:

- **Level 1**: override CSS via `:root` variables.
- **Level 2**: use `renderer: 'headless'` — the SDK only emits events and you render your own UI.

## Misc

### Is there a portal-wide rate limit?

Yes. Default 60 req/min/token across endpoints, with `click-to-call` capped at 10 req/min. Exceed → HTTP 429 with a `Retry-After` header.

### Is the API versioned?

Currently there's only `v1` (the current URLs). When a breaking change ships, `/api/v2/...` will run alongside it. The roadmap announces breaking changes at least 6 months in advance.

### Is there an OpenAPI spec / Postman collection to import?

The OpenAPI spec is in preparation — it will be published at `/openapi/` in Phase 2.

### I want to deploy a receiver in Vietnam — where are the Zorio servers?

Zorio servers are hosted in Vietnam (HCMC + Hanoi). Deploying a receiver in the same Vietnam region keeps webhook latency under 50ms.

### Bug reports / integration support?

- Email: contact your admin for the official support channel.
- When reporting a bug — always include `X-Request-Id` (if available) or `call_uuid` + timestamp.


---

# Glossary

<!-- source: https://docs.zorio.vn/en/reference/glossary.md -->

# Glossary

A consolidated glossary of Zorio terms used across the API modules.

## Account & access

| Term | Definition |
|---|---|
| **Account** | Each Zorio customer has an independent system with its own data, access domain, and API tokens |
| **API Token** | A Bearer (user session) token issued to a user, used in the `Authorization: Bearer <token>` header |
| **Permission** | A specific right on a single action (e.g. `pbx_api_access`, `manage_caller_ids`) |
| **Role** | A bundle of permissions attached to a user (`admin`, `supervisor`, `agent`, `read_only`) |
| **Permission tier** | Module-level access (`viewer`, `operator`, `admin`) |

## PBX

| Term | Definition |
|---|---|
| **Extension** | Internal SIP extension, registered to Zorio PBX with `extension_number` + `sip_password` |
| **Trunk** | Outbound route via a carrier / SBC / SIP trunking provider |
| **Caller ID** | The number shown to the callee when dialing out |
| **CDR (Call Detail Record)** | A record of one call with full metadata |
| **Hangup cause** | Q.850 standard code indicating why the call ended — see [Hangup codes](/en/reference/hangup-codes) |
| **Queue** | Call queue with agents answering according to a strategy (round-robin, longest-idle, ...) |
| **Tier** | Agent priority level within a queue (`tier_level` 1-9 + `tier_position`) |
| **A-leg / B-leg** | Click-to-call pattern: A-leg dials the agent, B-leg dials the customer, bridged when both answer |
| **SIP registration** | Status of a softphone registered against the PBX (`registered`, `unregistered`, `unknown`) |
| **TLS / SIPS** | SIP over TLS encryption (port 5061) instead of plain UDP (5060) |
| **WebRTC** | Browser-based call protocol used by the Webphone SDK |

## Telesales / Contact Center

| Term | Definition |
|---|---|
| **Campaign** | Outbound calling campaign with a lead list, script, agents, and a caller-ID group |
| **Lead** | A prospect — phone number plus industry-specific custom fields |
| **Disposition / Outcome** | Call result tagged by the agent (e.g. "Callback scheduled", "Not interested", "Purchased") |
| **Dialer mode** | How the dialer makes calls: `manual` (agent clicks), `preview` (agent reviews the lead first), `progressive` (auto-dials when agent is free), `predictive` (overdials by prediction) |
| **Caller-ID rotation** | Rotating across multiple caller IDs to avoid carrier spam flags — 6 strategies (`round_robin`, `least_used`, `cap_based`, `weighted`, `sticky_lead`, `random`) |
| **DNC (Do Not Call)** | List of numbers blocked from being called (PDPL compliance) |
| **Recording** | `.wav` recording of a call, downloaded via a signed URL with 30-minute TTL |
| **Wrap-up time** | Time after hangup for the agent to fill in disposition (e.g. 5 seconds) |
| **ASR (Answer-Seizure Ratio)** | Percentage of answered calls over total dialed calls (number-quality metric) |
| **ACD (Average Call Duration)** | Average length of answered calls |
| **Abandon rate** | Percentage of customers who answered but couldn't be connected to an agent (dropped in queue) |

## AutoCall TTS

| Term | Definition |
|---|---|
| **TTS (Text-to-Speech)** | Synthesizing voice from text |
| **Voice** | A specific voice (e.g. "vi-VN-female-01", "Linh Dan") |
| **Tier A** | Premium real-time TTS through a provider (premium TTS vendor) — charged per character |
| **Tier B** | Local TTS using a pre-rendered audio library — no charge, high throughput |
| **Script** | TTS script with `{{placeholder}}` variables substituted at runtime |
| **DTMF** | Phone keypad tones (0-9, *, #) |
| **DTMF action** | What happens when a caller presses a key: `playback`, `playback_then_hangup`, `switch_script`, `queue`, `repeat_script`, `hangup` |
| **Variable** | Customer-defined variable bound into a script (e.g. `customer_name`, `appointment_date`) |
| **Media file** | Pre-uploaded audio file for playback (no TTS) |

## Webphone SDK

| Term | Definition |
|---|---|
| **SDK (Software Development Kit)** | Library bundle installed into an app to use webphone features |
| **UMD** | Universal Module Definition — bundle format that runs in both browsers and Node.js via `<script>` tags |
| **npm tarball** | A `.tgz` package installed with `npm install ./file.tgz` for air-gapped environments |
| **iframe SSO** | Embedding the webphone in an iframe + exchanging an SSO token so the user doesn't have to log in again |
| **postMessage** | Browser API to pass messages between a parent page and an iframe |
| **SIP.js** | SIP-over-WebSocket library used as the SDK core (`sip.js@0.21.x`) |
| **Early media** | Audio (ringback / IVR announcement) played BEFORE the callee accepts |
| **Auto-reconnect** | The SDK reconnects automatically when the network drops, using exponential backoff |
| **Pagehide cleanup** | The SDK unregisters automatically when the user closes the tab → avoids stale registrations at the PBX |

## Webhook

| Term | Definition |
|---|---|
| **Webhook** | HTTPS URL where Zorio POSTs events to a CRM / customer app in real time |
| **HMAC** | Hash-based Message Authentication Code — verifies the payload signature with a shared secret |
| **Idempotency** | Property: calling once or many times yields the same result |
| **Replay attack** | Attacker captures one valid request and replays it many times — defeated by a timestamp window |
| **Deadletter** | Event that could not be delivered after N retries — kept in the audit log for manual replay |

## HTTP / API

| Term | Definition |
|---|---|
| **REST** | REpresentational State Transfer — standard for APIs over HTTP |
| **Bearer Token** | Token carried in the `Authorization: Bearer <token>` header |
| **Bearer (user session)** | Zorio's authentication scheme — tokens are tied to a user's login session |
| **Pagination** | Splitting results across pages via `?page=N&per_page=M` |
| **Soft delete** | Marking `deleted_at` instead of dropping the row — can be restored |
| **Rate limit** | Cap on requests per time window; exceeding → HTTP 429 |
| **ISO 8601** | Datetime standard `2026-06-30T03:30:45+00:00` |
| **E.164** | International phone-number standard `+84xxxxxxxxx` |
| **UUID** | Universally Unique Identifier, 36 chars (e.g. `65569ce0-0183-4f61-a3b2-0e433cfa4031`) |

## Vietnam telco

| Term | Definition |
|---|---|
| **Carrier** | Mobile/landline operator: Viettel, Mobifone, Vinaphone, Vietnamobile |
| **CLI type** | Number type: `mobile` (mobile), `fixed_02x` (fixed line), `hotline_1900` / `hotline_1800` (service hotline), `brandname` (branded sender ID) |
| **PDPL** | Personal Data Protection Law — Vietnam's personal data protection regulation |
| **DNC list** | List of numbers not to be called (PDPL compliance) |


---

# Hangup cause codes

<!-- source: https://docs.zorio.vn/en/reference/hangup-codes.md -->

# Hangup cause codes

The `hangup_cause` value appears in CDR responses and webhook payloads (`pbx.call.hangup`, `pbx.cdr.created`). Codes follow ITU-T **Q.850**, mapped from SIP responses by Zorio PBX.

## Most common codes

| `hangup_cause` | Meaning | Real-world scenario |
|---|---|---|
| `NORMAL_CLEARING` | Call ended normally | One of the two parties hung up after talking |
| `NO_ANSWER` | Ring timeout, nobody picked up | The customer didn't pick up or was away from the phone |
| `USER_BUSY` | Destination busy | The customer was on another call |
| `CALL_REJECTED` | Destination rejected the call | The customer pressed "decline" on their phone |
| `ORIGINATOR_CANCEL` | Agent / system cancelled before answer | The agent changed their mind and hung up while it was still ringing |
| `RECOVERY_ON_TIMER_EXPIRE` | Call hung due to SIP timeout | Network or PBX technical issue |

## Routing-related codes

| `hangup_cause` | Meaning |
|---|---|
| `UNALLOCATED_NUMBER` | The number doesn't exist in the network (e.g. 1XX, fake prefixes) |
| `NO_ROUTE_DESTINATION` | No route to destination (e.g. trunk not configured) |
| `NO_ROUTE_TRANSIT_NET` | The trunk refused the call |
| `DESTINATION_OUT_OF_ORDER` | The destination is offline |
| `INVALID_NUMBER_FORMAT` | Bad number format (e.g. extra chars, wrong prefix) |
| `FACILITY_REJECTED` | The carrier refused the route |

## Call quality codes

| `hangup_cause` | Meaning |
|---|---|
| `MEDIA_TIMEOUT` | RTP packets stopped arriving for N seconds (network dropped) |
| `BEARERCAPABILITY_NOTAVAIL` | Codec mismatch between the two parties |
| `INCOMPATIBLE_DESTINATION` | Different standards (e.g. analog ↔ SIP can't bridge) |
| `EXCHANGE_ROUTING_ERROR` | Carrier routing error |

## Policy-related codes

| `hangup_cause` | Meaning |
|---|---|
| `CALL_REJECTED` | Hard reject (e.g. DNC list, blacklist) |
| `INTERWORKING` | Protocol incompatibility (e.g. ISDN ↔ SIP) |
| `BEARERCAPABILITY_NOTAUTH` | Not authorized to use this service |
| `CHANNEL_UNACCEPTABLE` | Channel not ready |

## Overload-related codes

| `hangup_cause` | Meaning |
|---|---|
| `NORMAL_TEMPORARY_FAILURE` | Temporary failure, retry later |
| `SWITCH_CONGESTION` | Platform overloaded, can't accept more |
| `REQUESTED_CHAN_UNAVAIL` | No free channels on the trunk |
| `RESOURCE_UNAVAILABLE` | Out of resources (e.g. SBC) |

## Internal-system codes

| `hangup_cause` | Meaning |
|---|---|
| `LOSE_RACE` | Lost the race when two calls hit the same number (only one wins) |
| `MANAGER_REQUEST` | Admin / supervisor hung up the call manually via API |
| `SYSTEM_SHUTDOWN` | System is shutting down |
| `BLIND_TRANSFER` | Call was blind-transferred to another number |
| `ATTENDED_TRANSFER` | Call was attended-transferred to another number |
| `PICKED_OFF` | Call was picked off the queue by another extension |

## Mapping to the `result` field

The `result` field in the CDR is a simpler classification so CRMs can aggregate easily. Mapping rules:

| Condition | `result` |
|---|---|
| `hangup_cause = NORMAL_CLEARING` + `billsec > 0` | `answered` |
| `hangup_cause = NORMAL_CLEARING` + `billsec = 0` | `no_answer` (special case: agent hung up immediately after answering) |
| `hangup_cause = NO_ANSWER` | `no_answer` |
| `hangup_cause = USER_BUSY` | `busy` |
| `hangup_cause = CALL_REJECTED` | `rejected` |
| `hangup_cause = ORIGINATOR_CANCEL` | `cancelled` |
| Call went to voicemail | `voicemail` |
| Anything else (network, routing, system errors) | `failed` |

## When you see an unknown `hangup_cause`

If you see a code that isn't listed above (e.g. `BIB_NA`, `XXX_ZZZ`), it could be:

- A carrier-specific extended code (Viettel, Mobifone, ...).
- A rare infrastructure issue — report it to Zorio support with the `call_uuid` for tracing.

Full Q.850 reference: [ITU-T Q.850](https://www.itu.int/rec/T-REC-Q.850).


---

# HTTP status codes

<!-- source: https://docs.zorio.vn/en/reference/http-codes.md -->

# HTTP status codes

Complete reference for HTTP status codes the Zorio API returns and how your CRM should handle them.

## 2xx — Success

| HTTP | When | Body |
|---|---|---|
| **200 OK** | Most GET / PUT / DELETE successes | `{ "data": {} }` or a paginated list |
| **201 Created** | POST creating a new resource | `{ "data": { "id": ..., "..." } }` |
| **202 Accepted** | Async action enqueued (e.g. `click-to-call`, lead import) | `{ "data": { "call_uuid": "...", "status": "queued" } }` |

## 3xx — Redirect

| HTTP | When | Body |
|---|---|---|
| **302 Found** | `/api/pbx/cdr/{uuid}/recording` redirecting to a signed URL | Empty body, header `Location: <signed URL>` |

## 4xx — Client errors

### 400 Bad Request

The request is invalid at the HTTP level (malformed JSON, missing required header, ...).

```json
{ "message": "Malformed request body" }
```

**Handling**: check the JSON is correct and the `Content-Type: application/json` header is present.

### 401 Unauthorized

Token missing / invalid / expired.

```json
{ "message": "Unauthenticated." }
```

**Handling**: redirect the user to login for a fresh token. DO NOT hardcode tokens in the frontend.

### 403 Forbidden

Token is valid but missing the required permission.

```json
{ "message": "This action is unauthorized." }
```

**Handling**: log it and ask an admin to grant the missing permission to the user (e.g. `pbx_api_access`, `telesales_api_access`).

### 404 Not Found

The resource doesn't exist in your account's data.

```json
{ "message": "Resource not found" }
```

::: warning Security note
When a token is used against the wrong account (e.g. account A asks for data from account B), Zorio also returns **404** rather than 403 so it **does not leak existence**. Your CRM can't distinguish the two cases.
:::

### 409 Conflict

State-machine violation or unique-constraint conflict.

```json
{ "message": "Extension already exists in this queue." }
```

**Handling**: refresh local state and notify the user.

### 422 Unprocessable Entity

Validation error — the body parsed correctly, but one or more field values are invalid.

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "extension_number": ["Extension number format is invalid."],
    "outbound_caller_id": ["The selected outbound caller id is invalid."]
  }
}
```

**Handling**:
- Iterate over `errors`, show each message next to its field in the UI.
- For form submits — don't refresh the page; keep the user's current state.

### 429 Too Many Requests

Rate-limit exceeded.

```json
{ "message": "Too many requests. Retry after 25 seconds." }
```

Response headers:

```
Retry-After: 25
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782706011
```

**Handling**: back off per `Retry-After`. Implement exponential backoff + jitter to avoid a thundering herd.

## 5xx — Server errors

### 500 Internal Server Error

Unexpected backend error.

```json
{ "message": "Internal server error" }
```

**Handling**: retry with exponential backoff (3 attempts, 1s / 4s / 16s). If 500 persists → contact Zorio support with `X-Request-Id` (if available) or the request timestamp.

### 502 Bad Gateway

Lower-tier failure — most common cases:

- Click-to-call: Zorio PBX did not accept the originate (the PBX may have just restarted).

```json
{ "message": "PBX did not accept the originate. Please try again." }
```

**Handling**: retry after a few seconds. If 502 persists → escalate.

### 503 Service Unavailable

Maintenance or temporary overload.

```json
{ "message": "Service temporarily unavailable" }
```

The `Retry-After: <seconds>` header advises the suggested retry delay.

### 504 Gateway Timeout

Upstream timeout. Rare.

## Best practices

### Always handle 4xx + 5xx

Every API call MUST have an error handler. DO NOT assume "200 OK by default".

### Distinguish retry-able vs non-retry-able

| Status | Retry? | Reason |
|---|---|---|
| 4xx (except 408, 429) | No | Client-side error — retry won't change the result |
| 408 Request Timeout | Yes (1-3 times) | May be a network blip |
| 429 Too Many Requests | Yes (after `Retry-After`) | Back off per the header |
| 500, 502, 503, 504 | Yes (exponential backoff) | Temporary server-side errors |

### Trace requests

Response header: `X-Request-Id: <uuid>` — paste it into your support ticket; the Zorio team uses it to trace root cause quickly.

### Network error vs HTTP error

A network error (DNS failure, connection refused, TLS error) is NOT an HTTP status code — there is no body. Catch it separately:

```js
try {
  const res = await fetch(url, opts);
  if (!res.ok) {
    // HTTP error 4xx / 5xx
  }
} catch (err) {
  // Network error
}
```


---

# API methods

<!-- source: https://docs.zorio.vn/en/sdk/webphone/api.md -->

# API methods

The `ZorioWebphone` class exposes 12 primary methods. The first four live on the webphone instance (`phone.*`); the eight call-control methods live on the call object (`call.*` — returned by `phone.call()` or via the `incoming_call` event payload).

::: tip Calling convention
Every method is **async** and returns a Promise. `await` it to catch errors and ensure state is synchronized before chaining the next call.
:::

## 1. Static factory

```ts
ZorioWebphone.connect(opts: ConnectOptions): Promise<ZorioWebphone>
ZorioWebphone.diagnose(opts: { apiBase: string; token: string }): Promise<DiagnoseResult>
```

`connect()` bootstraps: calls `/api/webphone/sip-config` → creates a SIP.js `UserAgent` → registers → mounts the UI (if `mount` is set). `diagnose()` runs a preflight on HTTPS / mic / WSS / STUN / TURN — call it before `connect()` for debugging.

```ts
interface ConnectOptions {
  apiBase:              string
  token:                string
  mount?:               string | HTMLElement
  layout?:              'docked' | 'overlay' | 'fullscreen'
  theme?:               'light' | 'dark' | 'auto'
  locale?:              'vi' | 'en'
  autoRegister?:        boolean
  ringtoneUrl?:         string
  audioOutputDeviceId?: string
  audioInputDeviceId?:  string
  tokenResolver?:       () => Promise<string>
  debug?:               boolean
  onError?:             (err: ZorioWebphoneError) => void
}
```

## 2. Instance methods — connection and control

### 2.1 `connect`

Documented in the Static factory section above. Returns a `phone` instance used for the remaining methods.

### 2.2 `disconnect`

```ts
phone.disconnect(): Promise<void>
```

Closes every resource: unregister SIP, close the WebSocket, remove the UI DOM (if embedded), clear the audio element, cancel every reconnect timer. **Must be called** when the user logs out of your app.

```ts
async function onLogout() {
  await phone.disconnect()
  redirectTo('/login')
}
```

::: tip Pagehide is handled for you
The SDK installs `addEventListener('pagehide', ...)` to unregister cleanly when the user closes the tab. You only need to call `disconnect()` manually for explicit logout flows.
:::

### 2.3 `call`

```ts
phone.call(number: string, options?: CallOptions): Promise<ZorioCall>

interface CallOptions {
  campaignId?:  number
  leadId?:      number
  customerId?:  number
  recording?:   boolean
  callerName?:  string
  meta?:        Record<string, unknown>
}
```

Initiates an outbound call. Returns a `ZorioCall` immediately after the SIP `INVITE` is sent (state `originating`); the call continues its lifecycle through events [`call_ringing`](/en/sdk/webphone/events#call-ringing) → [`call_answered`](/en/sdk/webphone/events#call-answered) → [`call_hangup`](/en/sdk/webphone/events#call-hangup).

```ts
const call = await phone.call('0912345678', {
  campaignId: 36,
  leadId: 78912,
  recording: true,
  meta: { source: 'crm-quickdial' },
})
console.log('Call UUID:', call.uuid)
```

::: warning Number format
The number format follows the customer's Zorio PBX dial plan. The default is E.164 (`+84912345678`) or domestic (`0912345678`). Unparseable numbers throw `ZorioWebphoneError` with `code = 'invalid_target'`.
:::

## 3. Call-control methods (on `ZorioCall`)

The following methods are invoked on the `ZorioCall` object obtained from `phone.call()`, the `incoming_call` payload, or via `phone.calls.find(c => c.state === 'answered')`.

### 3.1 `answer`

```ts
call.answer(): Promise<void>
```

Answer an inbound call. Throws `code = 'not_incoming'` if invoked on an outbound call. Automatically attaches the mic track and remote audio.

```ts
phone.on('incoming_call', async ({ call }) => {
  if (myUI.shouldAutoAnswer()) await call.answer()
})
```

### 3.2 `reject` / `hangup`

```ts
call.hangup(): Promise<void>
```

Ends a call in **any state**. The SDK picks the right SIP method automatically:

| State | SIP method |
|---|---|
| `originating` (outbound, not yet ringing) | `CANCEL` |
| `ringing` inbound (not yet answered) | `REJECT` (response 486 / 603) |
| `answered` | `BYE` |

::: tip `reject` vs `hangup`
The SDK exposes a single `call.hangup()` that is state-aware. If you want explicit "reject incoming" semantics, alias it:

```ts
const reject = (call: ZorioCall) => call.hangup()
```
:::

### 3.3 `mute` / `unmute`

```ts
call.mute():   Promise<void>
call.unmute(): Promise<void>
```

Toggle the local microphone. Does NOT affect remote audio. The state is mirrored on `call.muted: boolean` and emitted via `muted` / `unmuted` events.

```ts
muteBtn.onclick = async () => {
  const active = phone.calls.find(c => c.state === 'answered')
  if (!active) return
  if (active.muted) await active.unmute()
  else              await active.mute()
}
```

### 3.4 `hold` / `unhold`

```ts
call.hold():   Promise<void>
call.unhold(): Promise<void>
```

Hold the call via SIP `re-INVITE` with SDP `a=sendonly`. This is a standards-compliant hold so the callee hears the Zorio PBX music-on-hold (if enabled on the profile).

```ts
await call.hold()
// ... handle something else
await call.unhold()
```

### 3.5 `sendDtmf`

```ts
call.sendDtmf(digits: string): Promise<void>
```

Sends DTMF tones via RFC 2833. Supports characters `0-9`, `*`, `#`, `A-D`. Other characters throw `code = 'invalid_dtmf'`.

```ts
// Navigate an IVR after the callee answers (wait 1s for the IVR prompt)
phone.on('call_answered', async ({ call }) => {
  await new Promise(r => setTimeout(r, 1000))
  await call.sendDtmf('1')      // pick branch 1
  await call.sendDtmf('2#')     // pick 2 then #
})
```

### 3.6 `transfer`

```ts
call.transfer(target: string): Promise<void>
```

Blind transfer — moves the call to `target` (extension/number) without consult. The state moves to `closed` once the Zorio PBX accepts the SIP `REFER`.

```ts
// User clicks "Transfer to extension 2002"
await call.transfer('2002')
```

::: warning v1.0 — not yet supported
`transfer()` and the consult/attended transfer method currently throw `code = 'not_implemented'` in v1.0. Scheduled for Phase 2. Partners who need transfer today can fall back on the Zorio PBX `*8` blind-transfer feature code → press DTMF via `sendDtmf('*8' + target + '#')`.
:::

## 4. Event subscription

`phone.on()` / `phone.off()` are not part of the 12 primary methods but are essential:

```ts
phone.on<E extends EventName>(event: E, handler: (payload: EventPayload<E>) => void): void
phone.off<E extends EventName>(event: E, handler?: Function): void
```

See all 12 events in the [Events page](/en/sdk/webphone/events).

## 5. Read-only properties

Useful properties for observing state without waiting for an event:

```ts
phone.status        // 'connecting' | 'registered' | 'unregistered' | 'failed'
phone.extension     // the registered SIP extension number
phone.user          // UserProfile | null
phone.calls         // ZorioCall[] — every active call

// On ZorioCall:
call.uuid           // Zorio PBX UUID (links to the CDR)
call.direction      // 'incoming' | 'outgoing'
call.state          // 'originating' | 'ringing' | 'answered' | 'wrap_up' | 'closed'
call.number         // remote number (E.164)
call.startedAt      // Date — when the call was created
call.answeredAt     // Date | null — when it connected
call.endedAt        // Date | null
call.muted          // boolean
call.onHold         // boolean
```

## 6. Error handling

Every method throws `ZorioWebphoneError`:

```ts
class ZorioWebphoneError extends Error {
  code:     string
  details?: Record<string, unknown>
}
```

Common error codes: `bootstrap_failed`, `webphone_disabled`, `incomplete_sip_config`, `invalid_target`, `not_incoming`, `invalid_dtmf`, `audio_autoplay_blocked`, `reconnect_failed`, `not_implemented`, `not_bootstrapped`.

```ts
try {
  const call = await phone.call('xxx')
} catch (err) {
  if (err.code === 'invalid_target') {
    alert('Invalid phone number')
  } else {
    console.error(err)
  }
}
```

## 7. Summary table of the 12 primary methods

| # | Method | Scope | Purpose |
|---|---|---|---|
| 1 | `connect` | static | Bootstrap the SDK and register SIP |
| 2 | `disconnect` | `phone` | Tear everything down; use on logout |
| 3 | `call` | `phone` | Start an outbound call |
| 4 | `hangup` | `call` | Cancel/Bye an in-progress call |
| 5 | `answer` | `call` | Answer an inbound call |
| 6 | `reject` | `call` | Alias for hangup when an inbound is not yet answered |
| 7 | `mute` | `call` | Mute the microphone |
| 8 | `unmute` | `call` | Unmute the microphone |
| 9 | `hold` | `call` | Hold (re-INVITE sendonly) |
| 10 | `unhold` | `call` | Resume |
| 11 | `sendDtmf` | `call` | Send IVR tones |
| 12 | `transfer` | `call` | Blind transfer (Phase 2) |

See also:

- [Events](/en/sdk/webphone/events)
- [Quickstart HTML](/en/sdk/webphone/quickstart)


---

# Events

<!-- source: https://docs.zorio.vn/en/sdk/webphone/events.md -->

# Events

The Webphone SDK emits 12 events covering the SIP registration lifecycle + call lifecycle + system errors. Subscribe via `phone.on(eventName, handler)` and unsubscribe via `phone.off(eventName, handler?)`.

::: tip Handler scope
Handlers are called **synchronously** when the event fires. If you need heavy async work inside a handler (API calls, DB writes), `await` separately so you do not block the SDK event loop.
:::

## Summary table

| # | Event | Payload | When emitted |
|---|---|---|---|
| 1 | `registered` | `{}` | SIP register succeeded for the first time, or after a reconnect |
| 2 | `unregistered` | `{ reason }` | SIP unregister (manual / remote / transport_disconnect) |
| 3 | `connected` | `{}` | WebSocket WSS is up — not yet registered |
| 4 | `disconnected` | `{ reason? }` | WebSocket dropped, before the auto-reconnect kicks in |
| 5 | `incoming_call` | `{ call, contact }` | An INVITE arrived |
| 6 | `call_ringing` | `{ call }` | Outbound received 180/183, or inbound is locally ringing |
| 7 | `call_answered` | `{ call }` | The call entered `answered` state |
| 8 | `call_hangup` | `{ call, reason, billsec }` | Either side hung up, or the call failed |
| 9 | `dtmf` | `{ call, digit }` | DTMF received from the remote party (RFC 2833) |
| 10 | `error` | `ZorioWebphoneError` | Any runtime error — must be handled |
| 11 | `auto_reconnect` | `{ attempt, delay_ms }` | Each time the supervisor schedules a reconnect attempt |
| 12 | `audio_autoplay_blocked` | `{ call }` | The browser blocked autoplay when a call arrived |

## 1. `registered`

```ts
phone.on('registered', () => {
  console.log('SIP ready, extension:', phone.extension)
  showBanner('Online', 'success')
})
```

Emitted on the first registration (after `connect()`) and on every successful re-register after a reconnect. Use it to surface online status in the UI.

## 2. `unregistered`

```ts
phone.on('unregistered', ({ reason }) => {
  // reason: 'manual' | 'remote' | 'transport_disconnect'
  if (reason === 'transport_disconnect') {
    showBanner('Connection lost, reconnecting…', 'warn')
  }
})
```

| `reason` | Meaning |
|---|---|
| `manual` | The user explicitly called `phone.unregister()` |
| `remote` | The Zorio PBX returned 401/403, possibly due to a credential change |
| `transport_disconnect` | The WebSocket WSS dropped |

## 3. `connected`

```ts
phone.on('connected', () => {
  console.log('WSS connected — about to register')
})
```

The WebSocket layer is up but the SIP `REGISTER` has not completed yet. Useful for showing a 2-step progress: "Connecting…" → "Registering…" → "Ready".

## 4. `disconnected`

```ts
phone.on('disconnected', ({ reason }) => {
  console.warn('WSS drop:', reason)
})
```

The WebSocket closed. The SDK supervisor will retry — followed by `auto_reconnect`.

## 5. `incoming_call`

```ts
phone.on('incoming_call', ({ call, contact }) => {
  myUI.showIncomingPopup({
    name: contact?.full_name || call.number,
    onAccept: () => call.answer(),
    onReject: () => call.hangup(),
  })
})
```

Full payload:

```ts
{
  call: ZorioCall,                       // direction='incoming', state='ringing'
  contact: {
    id: number
    full_name: string
    phones?: string[]
    customer_id?: number
    lead_id?: number
  } | null
}
```

`contact` is looked up from the Zorio backend (`/api/contacts/lookup?number=...`). If the customer is not yet in CSKH → `contact = null`, display the raw `call.number`.

## 6. `call_ringing`

```ts
phone.on('call_ringing', ({ call }) => {
  if (call.direction === 'outgoing') {
    showStatus(`Calling ${call.number}…`)
  }
})
```

::: tip Early media (v7)
For outbound, this event fires when the SDK receives a **SIP 180 Ringing** or **183 Session Progress**. Thanks to `earlyMedia: true`, you hear ringback / IVR carrier audio **right at this point** — no need to wait for an answer.
:::

## 7. `call_answered`

```ts
phone.on('call_answered', ({ call }) => {
  console.log('Connected, UUID:', call.uuid)
  startTimer(call.uuid)
})
```

The remote side answered (200 OK + ACK). Start billing/billsec from this moment.

## 8. `call_hangup`

```ts
phone.on('call_hangup', ({ call, reason, billsec }) => {
  stopTimer(call.uuid)
  if (reason === 'no_answer') {
    showToast('No answer')
  } else if (reason === 'busy') {
    showToast('Busy')
  }
  saveBillsec(call.uuid, billsec)
})
```

| Common `reason` | Source Zorio PBX HangupCause |
|---|---|
| `normal_clearing` | `NORMAL_CLEARING` (billsec > 0) |
| `no_answer` | `NORMAL_CLEARING + billsec = 0` or `NO_ANSWER` |
| `busy` | `USER_BUSY` |
| `unallocated_number` | `UNALLOCATED_NUMBER` |
| `originator_cancel` | `ORIGINATOR_CANCEL` |
| `call_rejected` | `CALL_REJECTED` |

For the complete mapping see [Hangup cause codes](/en/reference/hangup-codes).

## 9. `dtmf`

```ts
phone.on('dtmf', ({ call, digit }) => {
  console.log('Remote pressed:', digit)
})
```

A DTMF was received from the remote party (e.g. the customer pressing a key in a reverse IVR). `digit` is a single character `0-9 * # A-D`.

## 10. `error`

```ts
phone.on('error', (err) => {
  switch (err.code) {
    case 'bootstrap_failed':
      alert('Could not connect to Zorio — check the token / network')
      break
    case 'audio_autoplay_blocked':
      showBanner('Please click the page to enable audio')
      break
    case 'reconnect_failed':
      showBanner('Connection lost for too long — please reload the page')
      break
    default:
      console.error('[zorio-webphone]', err.code, err.message, err.details)
  }
})
```

A catch-all for every runtime error. The `ZorioWebphoneError` class:

```ts
class ZorioWebphoneError extends Error {
  code:     string                            // machine-readable
  details?: Record<string, unknown>
}
```

See the full list of `code` values at [API methods → Error handling](/en/sdk/webphone/api#_6-error-handling).

## 11. `auto_reconnect`

```ts
phone.on('auto_reconnect', ({ attempt, delay_ms }) => {
  console.log(`Reconnect attempt ${attempt}, waiting ${delay_ms}ms`)
  if (attempt > 5) showBanner('Connection unstable', 'warn')
})
```

Emitted every time the v7 supervisor schedules a reconnect. Exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (cap) + 0-500ms of jitter. Resets after a successful re-register.

::: tip Recommended UX
Show a discreet "Reconnecting…" banner only when `attempt >= 2`. Do not panic the user on the first attempt — a 1-2s network blip is normal.
:::

## 12. `audio_autoplay_blocked`

```ts
phone.on('audio_autoplay_blocked', ({ call }) => {
  // Safari/iOS blocks autoplay when the tab has no user gesture yet
  myUI.showUnlockBanner({
    message: 'Tap here to enable call audio',
    onClick: async () => {
      await phone.unlockAudio() // creates a gesture context for the audio element
    },
  })
})
```

::: warning Safari / iOS quirk
The browser blocks `audio.play()` until the page has had a user interaction (click/tap). The SDK detects this → emits this event → the host app MUST display a button asking the user to tap. If you ignore it, the call still connects but the user cannot hear audio.
:::

## Common patterns

### Wire the 3 minimum events for an MVP

```ts
const phone = await ZorioWebphone.connect({ apiBase, token, mount: '#zorio-phone' })

phone.on('incoming_call', ({ call, contact }) => myUI.showIncoming(call, contact))
phone.on('call_answered',  ({ call }) => myUI.openInCall(call))
phone.on('call_hangup',    ({ call, billsec }) => myUI.closeInCall(call, billsec))
phone.on('error',          (err) => console.error(err))
```

### Track online state for a dashboard

```ts
function updateStatusBadge() {
  badge.textContent = phone.status === 'registered' ? 'Online' : 'Offline'
}

phone.on('registered',        updateStatusBadge)
phone.on('unregistered',      updateStatusBadge)
phone.on('connected',         updateStatusBadge)
phone.on('disconnected',      updateStatusBadge)
phone.on('auto_reconnect',    updateStatusBadge)
```

See also:

- [API methods](/en/sdk/webphone/api)
- [Quickstart HTML](/en/sdk/webphone/quickstart)


---

# Embed via iframe (SSO)

<!-- source: https://docs.zorio.vn/en/sdk/webphone/iframe.md -->

# Embed via iframe (SSO)

The simplest embedding option for a **legacy CRM whose frontend source you cannot modify**, or for a partner who just wants to "hang" the Zorio webphone in their app without controlling it. The iframe ships a full UI (dialer, incoming popup, in-call panel) — drop in `<iframe src=...>` and you are done.

## 1. Minimal syntax

```html
<iframe
  src="https://app.zorio.vn/webphone-embed?token=<jwt>"
  allow="microphone"
  style="border:0; width:380px; height:560px"
></iframe>
```

::: tip Custom domain
Replace `app.zorio.vn` with your custom domain if the partner has been provisioned a custom domain (e.g. `pbx.your-crm.example`). The iframe is always hosted on the domain assigned to the customer so that the bearer token / SIP credentials do not cross account boundaries.
:::

## 2. SSO exchange — obtaining `<jwt>`

The JWT passed via the query string is a **short-lived embed token** (TTL 5 minutes by default), exchanged by the partner backend from the partner's user session via this API:

```
POST https://acme.zorio.example/api/webphone/embed-token
Authorization: Bearer <bearer-token-from-/api/auth/login>
Content-Type: application/json

{
  "ttl_seconds": 300
}
```

Response:

```json
{
  "embed_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-06-30T10:35:00+07:00"
}
```

::: warning Never expose your main bearer token
Do **not** put the original bearer token into the iframe `src`. A long-lived bearer leaked via a URL ends up in Referer headers and proxy logs. Always exchange it for a short-TTL embed token before injecting it into the iframe.
:::

### Typical flow

```text
[Partner CRM]                  [Partner backend]            [Zorio API]
       │                              │                            │
       │  needs to render the         │                            │
       │  webphone                    │                            │
       ├─────────────────────────────►│                            │
       │                              │  POST /webphone/embed-token│
       │                              ├───────────────────────────►│
       │                              │                            │
       │                              │◄───────────────────────────┤
       │                              │  embed_token (TTL 5 min)   │
       │◄─────────────────────────────┤                            │
       │  embed_token                 │                            │
       │                              │                            │
       │  <iframe src="?token=...">                                 │
       │  → mount + SIP register      │                            │
```

When the token nears expiry, the parent frame can fetch a new one and forward it via `postMessage` (see [postMessage API](#_5-postmessage-api)).

## 3. Full query string options

```html
<iframe
  src="https://app.zorio.vn/webphone-embed
        ?token=<jwt>
        &layout=docked
        &theme=auto
        &locale=vi
        &auto_register=1"
  allow="microphone"
  style="border:0; width:380px; height:560px"
></iframe>
```

| Parameter | Value | Description |
|---|---|---|
| `token` | embed JWT | Required — short-lived embed token |
| `layout` | `docked` \| `overlay` \| `fullscreen` | UI layout. Default: `docked` |
| `theme` | `light` \| `dark` \| `auto` | Default: `auto` |
| `locale` | `vi` \| `en` | Default: `vi` |
| `auto_register` | `1` \| `0` | Auto-register SIP after load. Default: `1` |

## 4. Microphone permission on the iframe

You MUST add `allow="microphone"` — without it the browser will block `getUserMedia` even when the user has already granted permission to the parent page:

```html
<iframe allow="microphone" ... ></iframe>

<!-- If you also need camera (video, Phase 2): -->
<iframe allow="microphone; camera" ... ></iframe>
```

::: warning Cross-origin
The `app.zorio.vn` iframe is always cross-origin with the partner CRM → all communication between parent and iframe **must go through postMessage** (see [postMessage API](#_5-postmessage-api)). Do not try to access `iframe.contentWindow.phone` directly — the browser will block it.
:::

## 5. postMessage API

The webphone iframe communicates with the parent via [`window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). Every message uses the same shape:

```ts
interface ZorioWebphoneMessage {
  source: 'zorio-webphone'   // marker, ignore other messages
  type:   string             // event name or command
  payload?: any              // accompanying data
}
```

### 5.1 Listening to events from the iframe (iframe → parent)

```js
window.addEventListener('message', (e) => {
  if (e.origin !== 'https://app.zorio.vn') return       // verify origin
  if (e.data?.source !== 'zorio-webphone') return       // verify marker

  switch (e.data.type) {
    case 'registered':
      console.log('Webphone is ready')
      break
    case 'incoming_call':
      console.log('Incoming call:', e.data.payload.call.number)
      myUI.showIncomingBanner(e.data.payload)
      break
    case 'call_answered':
      myUI.openCallControls(e.data.payload.call.uuid)
      break
    case 'call_hangup':
      myUI.closeCallControls()
      console.log('Billsec:', e.data.payload.billsec)
      break
    case 'error':
      console.error('Webphone error:', e.data.payload)
      break
  }
})
```

The iframe forwards all 12 events just like the npm/UMD SDK — see [Events](/en/sdk/webphone/events).

### 5.2 Controlling the webphone (parent → iframe)

```js
const iframe = document.querySelector('iframe')

function sendCommand(type, payload) {
  iframe.contentWindow.postMessage(
    { source: 'zorio-webphone', type, payload },
    'https://app.zorio.vn'  // target origin — DO NOT use '*'
  )
}

// Click-to-call from a button inside the CRM
sendCommand('call', {
  number: '0912345678',
  options: { campaignId: 36, leadId: 78912 },
})

// Hangup the active call
sendCommand('hangup', {})

// Send DTMF
sendCommand('send_dtmf', { digits: '1' })

// Mute / unmute
sendCommand('mute', {})
sendCommand('unmute', {})

// Refresh a token nearing expiry
sendCommand('refresh_token', { token: newEmbedToken })
```

Command `type` values map 1-to-1 with the [12 API methods](/en/sdk/webphone/api).

### 5.3 Full integration example

```html
<div id="phone-container">
  <iframe
    id="zorio-frame"
    src="https://app.zorio.vn/webphone-embed?token=PLACEHOLDER"
    allow="microphone"
    style="border:0; width:380px; height:560px"
  ></iframe>
</div>

<button id="btn-call">Call 0912345678</button>

<script>
const ZORIO_ORIGIN = 'https://app.zorio.vn'
const iframe = document.getElementById('zorio-frame')

// 1. Fetch the embed token then inject
fetch('/api/internal/zorio-embed-token').then(r => r.json()).then(({ token }) => {
  iframe.src = `${ZORIO_ORIGIN}/webphone-embed?token=${token}&layout=docked`
})

// 2. Listen for events
window.addEventListener('message', (e) => {
  if (e.origin !== ZORIO_ORIGIN) return
  if (e.data?.source !== 'zorio-webphone') return
  console.log('[zorio]', e.data.type, e.data.payload)
})

// 3. Control
document.getElementById('btn-call').onclick = () => {
  iframe.contentWindow.postMessage(
    { source: 'zorio-webphone', type: 'call', payload: { number: '0912345678' } },
    ZORIO_ORIGIN
  )
}
</script>
```

## 6. v7 features still work inside the iframe

The iframe is built from the same SDK bundle, so it carries everything:

- **Auto-reconnect supervisor** — no reconnect handling needed in the parent.
- **Pagehide cleanup** — when the user closes the CRM tab, the iframe unregisters cleanly.
- **Early media** — outbound calls hear ringback from SIP 183 Session Progress.

## 7. iframe vs SDK npm/UMD — when to use which?

| Criterion | iframe | SDK npm/UMD |
|---|---|---|
| Integration speed | Fastest (one `<iframe>` tag) | Medium |
| Custom UI | Stuck with the default Zorio UI | Full control |
| Cross-origin | Fully isolated | Requires CSP setup |
| Advanced event customization | postMessage | Native callbacks |
| Air-gap | Self-host the iframe internally | Self-host UMD |

::: tip Recommendation
If the partner just needs "a webphone on the CRM, today" → use the iframe. If you need custom UX or deep CRM workflow integration (CTI, screen-pop) → use [npm](/en/sdk/webphone/npm) or [UMD](/en/sdk/webphone/umd).
:::

See also:

- [API methods](/en/sdk/webphone/api)
- [Events](/en/sdk/webphone/events)


---

# Webphone SDK — Overview

<!-- source: https://docs.zorio.vn/en/sdk/webphone/index.md -->

# Webphone SDK — Overview

> A WebRTC SDK for embedding a webphone in your CRM or in-house application. Framework-agnostic vanilla DOM UI, 4 distribution channels (npm / UMD / airgap / iframe).
>
> Built with Vite library mode + TypeScript + SIP.js v0.21.

## Scope

- 12 API methods (`connect`, `disconnect`, `call`, `hangup`, `answer`, `reject`, `mute`, `unmute`, `hold`, `unhold`, `sendDtmf`, `transfer`).
- 12 events (`registered`, `unregistered`, `connected`, `disconnected`, `incoming_call`, `call_ringing`, `call_answered`, `call_hangup`, ...).
- Auto-reconnect + re-register supervisor + pagehide cleanup.
- Early media (ringback, IVR carrier announcement).

## Embedding methods

| Method | Documentation |
|---|---|
| npm (your own bundler) | [Open page](/en/sdk/webphone/npm) |
| UMD/CDN (plain HTML) | [Open page](/en/sdk/webphone/umd) |
| iframe (SSO) | [Open page](/en/sdk/webphone/iframe) |
| API methods | [Open page](/en/sdk/webphone/api) |
| Events | [Open page](/en/sdk/webphone/events) |
| Quickstart HTML | [Open page](/en/sdk/webphone/quickstart) |


---

# Embed via npm

<!-- source: https://docs.zorio.vn/en/sdk/webphone/npm.md -->

# Embed via npm

The recommended method for any application that already has a build pipeline (Vite / webpack / Rollup / Next.js / Nuxt / Angular CLI…). The SDK ships TypeScript declarations and tree-shakable ES modules.

## 1. Install the package

The SDK is published as either an **internal tarball** (`zorio-webphone-sdk-1.0.0.tgz`) or via a scoped npm registry that the Zorio team provisions per partner.

```bash
# Option A — install directly from a Zorio-provided tarball
npm install ./zorio-webphone-sdk-1.0.0.tgz

# Option B — via scoped registry (if your partnership has been granted access)
npm install @zorio/webphone-sdk
```

::: tip Versions
SDK v1 uses `sip.js@0.21.x` as the WebRTC + SIP signaling transport. Bundle ~85 KB gzipped, SIP.js is bundled — you do **not** need to install it separately.
:::

## 2. Import and initialize

```ts
import { ZorioWebphone } from '@zorio/webphone-sdk'

const phone = await ZorioWebphone.connect({
  apiBase: 'https://acme.zorio.example',
  token:   bearerToken,
  mount:   '#zorio-phone', // leave empty to run headless
})
```

`ZorioWebphone.connect()` returns a Promise — `await` it before calling `phone.call()` or subscribing to events.

## 3. TypeScript

The package ships `.d.ts` files; import types directly:

```ts
import type {
  ConnectOptions,
  ZorioCall,
  ZorioWebphoneError,
  CallOptions,
  DiagnoseResult,
} from '@zorio/webphone-sdk'

const opts: ConnectOptions = {
  apiBase: import.meta.env.VITE_ZORIO_API_BASE,
  token:   import.meta.env.VITE_ZORIO_TOKEN,
  mount:   '#zorio-phone',
  layout:  'docked',
  theme:   'auto',
  locale:  'vi',
  autoRegister: true,
}

const phone = await ZorioWebphone.connect(opts)
```

## 4. Vue 3 integration example (Composition API)

```vue
<script setup lang="ts">
import { onMounted, onBeforeUnmount, ref } from 'vue'
import { ZorioWebphone } from '@zorio/webphone-sdk'

const phoneRef = ref<ZorioWebphone | null>(null)

onMounted(async () => {
  phoneRef.value = await ZorioWebphone.connect({
    apiBase: 'https://acme.zorio.example',
    token:   await getBearerToken(),
    mount:   '#zorio-phone',
  })

  phoneRef.value.on('incoming_call', ({ call, contact }) => {
    console.log('Incoming call:', contact?.full_name || call.number)
  })
})

onBeforeUnmount(async () => {
  await phoneRef.value?.disconnect()
})
</script>

<template>
  <div id="zorio-phone" />
</template>
```

## 5. React integration example

```tsx
import { useEffect, useRef } from 'react'
import { ZorioWebphone } from '@zorio/webphone-sdk'

export function WebphoneWidget({ token }: { token: string }) {
  const phoneRef = useRef<ZorioWebphone | null>(null)

  useEffect(() => {
    let cancelled = false
    ;(async () => {
      const phone = await ZorioWebphone.connect({
        apiBase: 'https://acme.zorio.example',
        token,
        mount:   '#zorio-phone',
      })
      if (cancelled) { await phone.disconnect(); return }
      phoneRef.current = phone
    })()
    return () => {
      cancelled = true
      phoneRef.current?.disconnect()
    }
  }, [token])

  return <div id="zorio-phone" />
}
```

## 6. Notable v7 features

::: warning Auto-reconnect + re-register supervisor
SDK v7 automatically re-registers SIP whenever the WebSocket is throttled (background tab) or the network drops. You do **not** need to write your own reconnect logic — just listen for the `auto_reconnect` event so you can show a banner like "Reconnecting…" to the user.
:::

::: tip Pagehide cleanup
When the user closes the tab, the SDK automatically `unregister`s cleanly against the Zorio PBX to avoid stale registrations (which would otherwise cause missed inbound calls within the timeout window). Works even when embedded via a bundler.
:::

::: tip Early media
Outbound calls over mobile play ringback / IVR carrier announcements **as soon as the SIP 183 Session Progress arrives** instead of being silent until the callee answers. Enabled by default in SDK v7 (`earlyMedia: true`).
:::

## 7. Suggested bundler configuration

Vite / Rollup tree-shake well by default. If you use webpack < 5 and hit `Cannot resolve module`, add:

```js
// webpack.config.js
module.exports = {
  resolve: {
    fallback: { crypto: false, stream: false, buffer: false },
  },
}
```

See also:

- [API methods](/en/sdk/webphone/api)
- [Events](/en/sdk/webphone/events)
- [Quickstart HTML](/en/sdk/webphone/quickstart)


---

# Quickstart HTML

<!-- source: https://docs.zorio.vn/en/sdk/webphone/quickstart.md -->

# Quickstart HTML

A complete HTML file you can copy-paste and run immediately — no build pipeline, no npm install. Open it in a browser (over HTTPS or `localhost`) and you can place a call.

::: tip Prerequisites
- The page must be served over **HTTPS** (WebRTC mandate). For local testing, plain `localhost` is fine.
- Browser >= Chrome 90 / Edge 90 / Firefox 90 / Safari 14.
- A **bearer token** obtained from `POST /api/auth/login` for the Zorio account in use.
- Microphone permission granted to the page.
:::

## 1. Minimal quickstart (~20 lines)

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Zorio Webphone Quickstart</title>
</head>
<body>
  <div id="zorio-phone" style="position:fixed;bottom:24px;right:24px"></div>

  <script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
  <script>
    const { ZorioWebphone } = window.ZorioWebphoneSDK

    ZorioWebphone.connect({
      apiBase: 'https://acme.zorio.example',
      token:   'PASTE-BEARER-TOKEN-HERE',
      mount:   '#zorio-phone',
    }).then((phone) => {
      window.phone = phone
      console.log('Webphone ready — type phone.call("0912345678") to test')
    })
  </script>
</body>
</html>
```

## 2. Full quickstart — dialer + status + log + 12 events

The standalone HTML below includes: a token-login form, dialer pad, status badge, real-time event log, and an error banner. It is the template Zorio uses to demo for partners.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Zorio Webphone — Full Quickstart</title>
  <style>
    body { font-family: system-ui, sans-serif; max-width: 880px; margin: 24px auto; padding: 0 16px; }
    .row { display: flex; gap: 12px; align-items: center; margin: 12px 0; }
    input, button { padding: 8px 12px; font-size: 14px; border-radius: 6px; border: 1px solid #cbd5e1; }
    button { cursor: pointer; background: #2563eb; color: #fff; border-color: #2563eb; }
    button.secondary { background: #f1f5f9; color: #0f172a; border-color: #cbd5e1; }
    button.danger    { background: #dc2626; border-color: #dc2626; }
    button:disabled  { opacity: 0.5; cursor: not-allowed; }
    #status { font-weight: 600; padding: 4px 10px; border-radius: 999px; background: #f1f5f9; }
    #status.ready    { background: #d1fae5; color: #065f46; }
    #status.error    { background: #fee2e2; color: #991b1b; }
    #status.warn     { background: #fef3c7; color: #92400e; }
    #log { background: #0f172a; color: #e2e8f0; font-family: ui-monospace, monospace;
            font-size: 12px; padding: 12px; border-radius: 8px; height: 280px;
            overflow-y: auto; white-space: pre-wrap; }
    .log-row { margin: 2px 0; }
    .log-row .ts  { color: #94a3b8; }
    .log-row .ev  { color: #38bdf8; font-weight: 600; }
    #zorio-phone { position: fixed; bottom: 24px; right: 24px; }
  </style>
</head>
<body>
  <h1>Zorio Webphone — Quickstart</h1>

  <div class="row">
    <input id="api-base" placeholder="https://acme.zorio.example" style="flex:1" />
    <input id="token"    placeholder="Bearer token"             style="flex:2" />
    <button id="btn-connect">Connect</button>
    <button id="btn-disconnect" class="secondary" disabled>Disconnect</button>
    <span id="status">Idle</span>
  </div>

  <div class="row">
    <input id="dial" placeholder="0912345678" style="flex:1" />
    <button id="btn-call"    disabled>Call</button>
    <button id="btn-hangup"  class="danger"    disabled>Hangup</button>
    <button id="btn-answer"  class="secondary" disabled>Answer</button>
    <button id="btn-mute"    class="secondary" disabled>Mute</button>
    <button id="btn-hold"    class="secondary" disabled>Hold</button>
  </div>

  <div id="log"></div>
  <div id="zorio-phone"></div>

  <script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
  <script>
    const { ZorioWebphone } = window.ZorioWebphoneSDK
    const $ = (id) => document.getElementById(id)

    let phone = null
    let activeCall = null

    function setStatus(text, cls) {
      const el = $('status')
      el.textContent = text
      el.className = cls || ''
    }
    function log(event, payload) {
      const ts = new Date().toISOString().slice(11, 19)
      const row = document.createElement('div')
      row.className = 'log-row'
      row.innerHTML =
        `<span class="ts">${ts}</span> ` +
        `<span class="ev">${event}</span> ` +
        (payload !== undefined ? JSON.stringify(payload) : '')
      $('log').appendChild(row)
      $('log').scrollTop = $('log').scrollHeight
    }
    function setActiveCall(call) {
      activeCall = call
      $('btn-hangup').disabled = !call
      $('btn-answer').disabled = !(call && call.direction === 'incoming' && call.state === 'ringing')
      $('btn-mute').disabled   = !(call && call.state === 'answered')
      $('btn-hold').disabled   = !(call && call.state === 'answered')
      $('btn-mute').textContent = call?.muted ? 'Unmute' : 'Mute'
      $('btn-hold').textContent = call?.onHold ? 'Unhold' : 'Hold'
    }

    $('btn-connect').onclick = async () => {
      try {
        setStatus('Connecting…', 'warn')
        phone = await ZorioWebphone.connect({
          apiBase: $('api-base').value.trim(),
          token:   $('token').value.trim(),
          mount:   '#zorio-phone',
          debug:   true,
        })
        window.phone = phone

        // === 12 events ===
        phone.on('registered',      ()              => { log('registered'); setStatus('Online', 'ready') })
        phone.on('unregistered',    (p)             => { log('unregistered', p); setStatus('Offline', 'warn') })
        phone.on('connected',       ()              => log('connected'))
        phone.on('disconnected',    (p)             => { log('disconnected', p); setStatus('Disconnected', 'warn') })
        phone.on('incoming_call',   ({ call, contact }) => {
          log('incoming_call', { number: call.number, contact: contact?.full_name })
          setActiveCall(call)
        })
        phone.on('call_ringing',    ({ call })      => { log('call_ringing', { number: call.number }); setActiveCall(call) })
        phone.on('call_answered',   ({ call })      => { log('call_answered', { uuid: call.uuid });   setActiveCall(call) })
        phone.on('call_hangup',     ({ call, reason, billsec }) => {
          log('call_hangup', { reason, billsec })
          setActiveCall(null)
        })
        phone.on('dtmf',            ({ digit })     => log('dtmf', { digit }))
        phone.on('error',           (err)           => { log('error', { code: err.code, msg: err.message }); setStatus('Error: ' + err.code, 'error') })
        phone.on('auto_reconnect',  (p)             => { log('auto_reconnect', p); setStatus(`Reconnect attempt ${p.attempt}…`, 'warn') })
        phone.on('audio_autoplay_blocked', ()       => {
          log('audio_autoplay_blocked')
          setStatus('Click the page to enable audio', 'warn')
        })

        $('btn-connect').disabled    = true
        $('btn-disconnect').disabled = false
        $('btn-call').disabled       = false
      } catch (err) {
        log('connect-failed', { code: err.code, msg: err.message })
        setStatus('Connect failed', 'error')
      }
    }

    $('btn-disconnect').onclick = async () => {
      await phone?.disconnect()
      phone = null
      setActiveCall(null)
      setStatus('Idle', '')
      $('btn-connect').disabled    = false
      $('btn-disconnect').disabled = true
      $('btn-call').disabled       = true
    }

    $('btn-call').onclick = async () => {
      const num = $('dial').value.trim()
      if (!num) return
      try {
        const call = await phone.call(num, { meta: { source: 'quickstart' } })
        setActiveCall(call)
      } catch (err) {
        log('call-failed', { code: err.code, msg: err.message })
      }
    }
    $('btn-hangup').onclick = () => activeCall?.hangup()
    $('btn-answer').onclick = () => activeCall?.answer()
    $('btn-mute').onclick = async () => {
      if (!activeCall) return
      if (activeCall.muted) await activeCall.unmute()
      else                  await activeCall.mute()
      setActiveCall(activeCall)
    }
    $('btn-hold').onclick = async () => {
      if (!activeCall) return
      if (activeCall.onHold) await activeCall.unhold()
      else                   await activeCall.hold()
      setActiveCall(activeCall)
    }
  </script>
</body>
</html>
```

## 3. How to use

1. Copy the HTML above into a file `quickstart.html`.
2. Serve over HTTPS (e.g. `npx http-server -S -C cert.pem -K key.pem`), or open it via `localhost`.
3. Open the browser and enter:
   - `apiBase`: the customer's URL (e.g. `https://acme.zorio.example`).
   - `token`: the bearer token from `POST /api/auth/login`.
4. Click **Connect** → wait for status to show "Online" → enter a number → click **Call**.

## 4. Observing v7 features in the log

When the network drops momentarily, the log shows:

```
10:14:32  disconnected     {"reason":"transport_disconnect"}
10:14:33  auto_reconnect   {"attempt":1,"delay_ms":1000}
10:14:34  connected
10:14:34  registered
```

Outbound calls to mobile networks show `call_ringing` (with audible ringback) before `call_answered` — thanks to early media.

::: tip Extension
Place an outbound call inside a telesales campaign:

```js
const call = await phone.call('0912345678', {
  campaignId: 36,
  leadId:     78912,
  recording:  true,
  meta:       { script_id: 12, agent_note: 'call back after 2pm' },
})
```

`campaignId` / `leadId` link the CDR to the telesales campaign, immediately visible in the customer's Reports and Live monitoring views.
:::

::: warning Token exposure in the quickstart
This file pastes the bearer token straight into the HTML — for internal demos ONLY. In production, always fetch the token via the partner's backend endpoint and supply `tokenResolver` to auto-refresh on 401:

```js
ZorioWebphone.connect({
  apiBase,
  token: currentToken,
  tokenResolver: async () => {
    const r = await fetch('/my-app/refresh-zorio-token', { method: 'POST' })
    return (await r.json()).token
  },
})
```
:::

See also:

- [Embed via npm](/en/sdk/webphone/npm) — production-grade
- [API methods](/en/sdk/webphone/api) — full TypeScript signatures
- [Events](/en/sdk/webphone/events) — payload for every event


---

# Embed via UMD/CDN

<!-- source: https://docs.zorio.vn/en/sdk/webphone/umd.md -->

# Embed via UMD/CDN

The right approach for static websites, WordPress, legacy CRMs without a bundler, or air-gapped environments without outbound CDN access. A single `<script>` tag is enough to use the `ZorioWebphone` class via a global variable.

## 1. UMD file layout

| File | Size (~) | Use case |
|---|---|---|
| `zorio-webphone.umd.cjs` | 85 KB gzip | `<script src=...>` |
| `zorio-webphone.umd.js`  | 85 KB gzip | Stable CDN alias |
| `zorio-webphone.esm.js`  | 80 KB gzip | `<script type="module">` |

Every bundle already bundles `sip.js@0.21.x` + every runtime dependency — no extra scripts to load.

## 2. Drop-in via the Zorio CDN

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Webphone demo</title>
</head>
<body>
  <div id="zorio-phone" style="position:fixed;bottom:24px;right:24px"></div>

  <script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
  <script>
    const { ZorioWebphone } = window.ZorioWebphoneSDK

    ZorioWebphone.connect({
      apiBase: 'https://acme.zorio.example',
      token:   '<bearer-token-from-login>',
      mount:   '#zorio-phone',
    }).then((phone) => {
      window.phone = phone // handy for debugging
      phone.on('incoming_call', ({ call, contact }) => {
        console.log('Incoming call:', contact?.full_name || call.number)
      })
    })
  </script>
</body>
</html>
```

::: tip Global namespace
The UMD bundle exposes `window.ZorioWebphoneSDK`. Destructure the main class: `const { ZorioWebphone } = window.ZorioWebphoneSDK`. You should **not** touch `window.SIP` (the bundled SIP.js) — always go through the `ZorioWebphone` class to stay forward-compatible.
:::

## 3. ESM script tag (modern browsers)

```html
<script type="module">
  import { ZorioWebphone } from 'https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.esm.js'

  const phone = await ZorioWebphone.connect({
    apiBase: 'https://acme.zorio.example',
    token:   bearerToken,
    mount:   '#zorio-phone',
  })
</script>
```

## 4. Self-host (air-gapped environments)

If the application runs in an internal network without outbound CDN access (real estate, banking, healthcare), download the SDK tarball and serve it from your own nginx/Apache:

```
/var/www/static/vendor/zorio-webphone.umd.cjs
/var/www/static/vendor/zorio-webphone.d.ts
```

```html
<script src="/static/vendor/zorio-webphone.umd.cjs"></script>
```

::: warning CSP — Content Security Policy
When self-hosting or embedding into a page with a strict CSP, add the following directives:

```
connect-src wss://*.zorio.example https://*.zorio.example;
media-src   blob:;
script-src  'self' https://cdn.zorio.vn;
```

WebRTC needs `blob:` for the `MediaStream` audio element, and `wss://` for SIP signaling.
:::

## 5. Pattern for WordPress / legacy CRM

```html
<!-- Drop into the theme footer.php or a plugin shortcode -->
<div id="zorio-phone"></div>

<script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
<script>
(function () {
  // Get the bearer token from the CRM backend session
  fetch('/wp-json/my-app/v1/zorio-token', { credentials: 'include' })
    .then(r => r.json())
    .then(({ token }) => window.ZorioWebphoneSDK.ZorioWebphone.connect({
      apiBase: 'https://acme.zorio.example',
      token,
      mount:   '#zorio-phone',
      layout:  'docked',
      theme:   'auto',
    }))
    .then((phone) => { window.phone = phone })
    .catch(console.error)
})()
</script>
```

## 6. v7 features in the UMD bundle

Every bundle (UMD / ESM / npm) ships the same feature set:

- **Auto-reconnect supervisor** — automatically re-registers when WSS drops / the tab is backgrounded.
- **Pagehide cleanup** — closing the tab triggers an `unregister` to the Zorio PBX.
- **Early media** — outbound calls hear ringback / IVR carrier audio from SIP 183 Session Progress.

::: tip Diagnostic preflight
Before `connect()`, you can run a preflight to check HTTPS / mic / WSS / STUN / TURN:

```js
const r = await window.ZorioWebphoneSDK.ZorioWebphone.diagnose({
  apiBase: 'https://acme.zorio.example',
  token,
})
if (!r.micOk)  alert('Please grant microphone permission')
if (!r.wssOk)  alert('Firewall is blocking WSS 443')
```
:::

## 7. Environment requirements

- The page must be served over **HTTPS** (WebRTC mandate, except `localhost`).
- Browser >= Chrome 90 / Edge 90 / Firefox 90 / Safari 14.
- The user must have at least one **gesture** (click/tap) on the page before the first incoming call, to bypass Safari/iOS autoplay policy — otherwise you will receive the [`audio_autoplay_blocked`](/en/sdk/webphone/events#audio-autoplay-blocked) event.

See also:

- [API methods](/en/sdk/webphone/api)
- [Events](/en/sdk/webphone/events)
- [Quickstart HTML](/en/sdk/webphone/quickstart)


---

# HMAC-SHA256 signing

<!-- source: https://docs.zorio.vn/en/webhooks/hmac.md -->

# HMAC-SHA256 signing

Every webhook Zorio sends to your receiver is **signed with HMAC-SHA256** using the secret you saved at registration. Purpose:

- **Authenticate** that the event came from Zorio (not an impersonator).
- **Verify integrity** of the payload (not altered in transit).
- **Block replay attacks** via a timestamp window.

## Headers Zorio sends

| Header | Description |
|---|---|
| `X-Zorio-Event` | Event name, e.g. `pbx.call.hangup` |
| `X-Zorio-Timestamp` | UTC epoch seconds when Zorio published the event |
| `X-Zorio-Delivery` | Unique UUID for each delivery (retries included) — use for dedupe |
| `X-Zorio-Signature` | `sha256=<hex>` HMAC-SHA256 of the raw body with the secret |
| `Content-Type` | `application/json; charset=utf-8` |

## How Zorio computes the signature

```
signature = "sha256=" + lowercase(hex(HMAC-SHA256(secret, raw_body)))
```

- `secret`: 32 alphanumeric chars generated when the webhook was created.
- `raw_body`: the raw bytes of the request body — DO NOT parse JSON before computing.

## How a receiver verifies

### Step 1 — Reject stale timestamps

Compare `X-Zorio-Timestamp` with current time. If it's off by more than **300 seconds (5 minutes)** → reject with 400.

Why: defeat replay attacks (an attacker captures one valid request and resends it many times).

### Step 2 — Recompute the signature

```
expected = "sha256=" + lowercase(hex(HMAC-SHA256(secret, raw_body)))
```

### Step 3 — Constant-time compare

Compare `expected` against `X-Zorio-Signature` with a **constant-time** function (`crypto.timingSafeEqual` in Node.js, `hmac.compare_digest` in Python, `hash_equals` in PHP).

::: warning DO NOT use `==` for string comparison
A plain `==` comparison can leak the signature byte by byte through **timing attacks**. Always use your language's timing-safe API.
:::

### Step 4 — Dedupe by `X-Zorio-Delivery`

Store the processed `X-Zorio-Delivery` UUID in Redis/DB with 24h TTL. If you've already seen the UUID → return 200 immediately (skip reprocessing).

## Node.js (Express) sample

```js
const crypto = require('crypto');
const express = require('express');
const app = express();

const SECRET = process.env.ZORIO_WEBHOOK_SECRET;

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = parseInt(req.headers['x-zorio-timestamp'], 10);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) {
    return res.status(400).send('Stale timestamp');
  }

  const sig = req.headers['x-zorio-signature'] || '';
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');

  if (sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  console.log('Verified event:', event.event, event.data);
  res.status(200).send('OK');
});

app.listen(3000);
```

More samples in Python, PHP, Go at [Sample receivers](/en/webhooks/sample-receivers).

## Common errors

### Signatures don't match even with the right secret

Frequent causes:

- **Parsing JSON before computing the HMAC** — you must use the RAW body, not a parsed object. In Express use `express.raw()`. In server frameworks use `$request->getContent()`. In Flask use `request.get_data()`.
- **Charset encoding** — must be raw UTF-8 bytes, no re-encoding.
- **Body modified by middleware** — e.g. nginx/CDN re-gzipping then unzipping → bytes change. Configure your stack to skip body modification on the webhook route.
- **Trimming whitespace** — DO NOT trim; the last byte may be `}` with no trailing newline.

### Timestamp is always off

- Your server clock is drifting — run `ntpd` / `chronyd` to sync via NTP.
- The receiver runs in a container without clock sync — make sure the container uses the right timezone.

## Related docs

- [Register a webhook](/en/webhooks/register)
- [Retry policy](/en/webhooks/retry)
- [Sample receivers](/en/webhooks/sample-receivers)


---

# Register a webhook

<!-- source: https://docs.zorio.vn/en/webhooks/register.md -->

# Register a webhook

A webhook is a channel through which Zorio **proactively pushes events** (calls, leads, CDR, ...) to your URL in real time — instead of you polling the API.

## How to register

::: warning No self-registration via API
For security and audit reasons (to prevent token abuse to redirect webhooks to an external URL), webhook registration is **done only through the Admin Console UI**. There is no public CRUD API.
:::

### 5-step flow

1. **Log in to the Admin Console** with an admin account.
2. Go to **Settings → Integrations → Webhooks** (`Admin Console`).
3. Click **Create webhook** and fill in:
   - **URL** — the HTTPS endpoint that will receive events (you deploy it).
   - **Events** — pick the events of interest (e.g. `pbx.call.hangup`, `telesales.lead.updated`).
   - **Display name** — to distinguish multiple webhooks.
4. The system generates a **secret** (32 alphanumeric chars) — **copy it now, you won't see it again**.
5. Deploy a receiver that verifies HMAC (see [HMAC-SHA256 signing](/en/webhooks/hmac)) and processes events.

## Supported events

### PBX (see [PBX Webhooks](/en/api/pbx/webhooks))

| Event | Fires when |
|---|---|
| `pbx.call.ringing` | An inbound call hits an extension and it's ringing |
| `pbx.call.answered` | The extension picks up |
| `pbx.call.hangup` | The call ends — real-time from ESL |
| `pbx.cdr.created` | The CDR pipeline has inserted the full row including `recording_url` |

### Telesales (see [Telesales](/en/api/telesales/))

| Event | Fires when |
|---|---|
| `telesales.lead.created` | A lead is inserted/imported |
| `telesales.lead.updated` | Disposition / custom fields change |
| `telesales.call.disposed` | An agent sets the outcome for a call |
| `telesales.campaign.completed` | Every lead in a campaign has been dialed |

### AutoCall (see [AutoCall Webhooks](/en/api/autocall/webhooks))

| Event | Fires when |
|---|---|
| `autocall.campaign.started` / `paused` / `resumed` / `finished` | Campaign lifecycle |
| `autocall.lead.dialed` / `answered` / `dtmf_pressed` / `transferred` | Lifecycle of a single call |

## Receiver URL requirements

- **HTTPS required** (no plain HTTP).
- Return **HTTP 2xx within 5 seconds** — anything slower is treated as a failure and retried.
- **Idempotent** by `X-Zorio-Delivery` (UUID) — Zorio may retry the same event after a failure.
- Verify HMAC before processing — see [HMAC-SHA256 signing](/en/webhooks/hmac).

## Test a webhook

The Admin Console has a **Send test event** button — it pushes a sample payload so you can debug your receiver without waiting for a real event.

## Rotate the secret

If you suspect the secret has leaked:

1. Open the webhook in the Admin Console → **Rotate secret**.
2. The system mints a new secret — copy it and update your receiver.
3. The old secret is **disabled immediately** — the next event is signed with the new secret.

## Pause / Delete a webhook

- **Pause**: configuration is kept, but no events are sent. Use this during receiver maintenance.
- **Delete**: permanent; history is retained in the audit log but cannot be restored.

## View delivery history

Every dispatched event has a **delivery record** kept for 30 days:

- Endpoint, event, timestamp, receiver's response status.
- Full payload + response body.
- Retry count.

Browse at Admin Console → **Webhook deliveries**.


---

# Retry policy

<!-- source: https://docs.zorio.vn/en/webhooks/retry.md -->

# Retry policy

When Zorio pushes a webhook to your receiver and the delivery **fails** (timeout / non-2xx / network error), the platform **retries automatically** on an escalating schedule.

## Definition of a failure

A receiver is considered failed when:

- It **times out** after **5 seconds** without a response.
- It returns an HTTP status **that is not 2xx** (e.g. 500, 502, 503, 4xx).
- A connection error (DNS failure, TLS handshake failure, ...).

::: tip Receiver takes a while to process?
Return **HTTP 200 as soon as you've verified the HMAC**, then process the event asynchronously through your internal queue. Don't run business logic synchronously with Zorio — you'll pile up retries.
:::

## Retry schedule

| Attempt | Delay since previous | Cumulative |
|---|---|---|
| 1 (first try) | — | 0s |
| 2 | 30 seconds | 30s |
| 3 | 5 minutes | 5m 30s |
| 4 (last try) | 30 minutes | 35m 30s |

After attempt 4 fails → the event moves to **`deadletter`** in the audit log.

## Deadletter

When an event lands in `deadletter`:

- It's kept in the webhook delivery log for 30 days.
- Admins can open **Admin Console → Webhook deliveries** to inspect: payload, failure reason, receiver's response.
- It **is NOT retried automatically** after deadletter — you must fix the receiver bug, then:
  - Either click **Replay** on each delivery to resend it.
  - Or re-register the webhook so new events flow again.

## Idempotency on the receiver side

Because Zorio may retry, the receiver MUST be idempotent — processing the same event multiple times must not cause inconsistent side effects (e.g. don't create two rows with the same UUID, don't deduct money twice).

### Implementation

Every delivery carries `X-Zorio-Delivery: <UUID>`. Save the UUID in Redis with 24h TTL:

```js
const seen = await redis.set(`zorio:delivery:${deliveryId}`, '1',
                              'NX', 'EX', 86400);
if (seen === null) {
  // Already processed → return 200 and skip
  return res.status(200).send('Duplicate');
}
// Process the event...
```

Result: no matter how many times Zorio retries, your business logic only runs once.

## Throughput & concurrency

- Zorio delivers events **in parallel** up to **20 concurrent connections** per receiver URL.
- During a burst (e.g. importing 10,000 leads), the receiver may see ~200-500 req/s. Plan capacity accordingly.
- If your receiver can't keep up → return **HTTP 503** with the header `Retry-After: <seconds>`. Zorio honors this header (the next retry waits at least the time you specified).

## When a webhook auto-suspends

If a webhook URL fails **50 events in a row** without a single success → the platform **auto-suspends** it to stop wasting resources.

- Admins get a notification in the Admin Console.
- You must re-enable it manually after fixing the receiver.

## Related docs

- [Register a webhook](/en/webhooks/register)
- [HMAC-SHA256 signing](/en/webhooks/hmac)
- [Sample receivers](/en/webhooks/sample-receivers)


---

# Sample receivers

<!-- source: https://docs.zorio.vn/en/webhooks/sample-receivers.md -->

# Sample receivers

Sample code for deploying a receiver that verifies HMAC, dedupes deliveries, and handles Zorio events. Copy-paste as a starting point and customize the "Process the event" section for your business logic.

## Node.js (Express)

```js
const crypto = require('crypto');
const express = require('express');
const Redis = require('ioredis');

const SECRET = process.env.ZORIO_WEBHOOK_SECRET;
const redis = new Redis(process.env.REDIS_URL);
const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const ts = parseInt(req.headers['x-zorio-timestamp'], 10);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) {
    return res.status(400).send('Stale timestamp');
  }

  const sig = req.headers['x-zorio-signature'] || '';
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');

  if (sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const deliveryId = req.headers['x-zorio-delivery'];
  const seen = await redis.set(`zorio:delivery:${deliveryId}`, '1', 'NX', 'EX', 86400);
  if (seen === null) {
    return res.status(200).send('Duplicate');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  res.status(200).send('OK');

  await handleEvent(event).catch((err) => {
    console.error('Process error:', err);
  });
});

async function handleEvent(event) {
  switch (event.event) {
    case 'pbx.call.hangup':
      console.log('Call ended:', event.data.call_uuid, event.data.hangup_cause);
      break;
    case 'telesales.lead.updated':
      console.log('Lead updated:', event.data.id);
      break;
  }
}

app.listen(3000, () => console.log('Receiver on :3000'));
```

## PHP (server framework)

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Redis;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        $secret = env('ZORIO_WEBHOOK_SECRET');

        $ts = (int) $request->header('X-Zorio-Timestamp');
        if (!$ts || abs(time() - $ts) > 300) {
            return response('Stale timestamp', 400);
        }

        $raw = $request->getContent();
        $signature = $request->header('X-Zorio-Signature', '');
        $expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);

        if (!hash_equals($expected, $signature)) {
            return response('Invalid signature', 401);
        }

        $deliveryId = $request->header('X-Zorio-Delivery');
        $key = "zorio:delivery:{$deliveryId}";
        $isNew = Redis::set($key, '1', 'NX', 'EX', 86400);
        if (!$isNew) {
            return response('Duplicate', 200);
        }

        $event = json_decode($raw, true);

        dispatch(function () use ($event) {
            $this->processEvent($event);
        })->afterResponse();

        return response('OK', 200);
    }

    protected function processEvent(array $event): void
    {
        match ($event['event']) {
            'pbx.call.hangup' => logger()->info('Call ended', $event['data']),
            'telesales.lead.updated' => logger()->info('Lead updated', $event['data']),
            default => null,
        };
    }
}
```

Register the route in `routes/api.php`:

```php
Route::post('/webhook', [WebhookController::class, 'handle']);
```

## Python (FastAPI)

```python
import hmac
import hashlib
import os
import time
import json
import redis.asyncio as redis
from fastapi import FastAPI, Request, HTTPException, BackgroundTasks

SECRET = os.environ["ZORIO_WEBHOOK_SECRET"].encode()
redis_client = redis.from_url(os.environ["REDIS_URL"])
app = FastAPI()


@app.post("/webhook")
async def webhook(request: Request, bg: BackgroundTasks):
    ts = int(request.headers.get("x-zorio-timestamp", "0"))
    if not ts or abs(time.time() - ts) > 300:
        raise HTTPException(400, "Stale timestamp")

    raw = await request.body()
    signature = request.headers.get("x-zorio-signature", "")
    expected = "sha256=" + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise HTTPException(401, "Invalid signature")

    delivery_id = request.headers.get("x-zorio-delivery")
    is_new = await redis_client.set(
        f"zorio:delivery:{delivery_id}", "1", nx=True, ex=86400
    )
    if not is_new:
        return {"status": "duplicate"}

    event = json.loads(raw)
    bg.add_task(process_event, event)
    return {"status": "ok"}


async def process_event(event: dict) -> None:
    match event["event"]:
        case "pbx.call.hangup":
            print(f"Call ended: {event['data']['call_uuid']}")
        case "telesales.lead.updated":
            print(f"Lead updated: {event['data']['id']}")
```

## Go (net/http)

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"strconv"
	"time"
)

var secret = []byte(os.Getenv("ZORIO_WEBHOOK_SECRET"))

func handler(w http.ResponseWriter, r *http.Request) {
	ts, _ := strconv.ParseInt(r.Header.Get("X-Zorio-Timestamp"), 10, 64)
	if ts == 0 || abs(time.Now().Unix()-ts) > 300 {
		http.Error(w, "Stale timestamp", 400)
		return
	}

	raw, _ := io.ReadAll(r.Body)
	sig := r.Header.Get("X-Zorio-Signature")
	mac := hmac.New(sha256.New, secret)
	mac.Write(raw)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(sig), []byte(expected)) {
		http.Error(w, "Invalid signature", 401)
		return
	}

	w.WriteHeader(200)
	w.Write([]byte("OK"))

	var event struct {
		Event string                 `json:"event"`
		Data  map[string]interface{} `json:"data"`
	}
	if err := json.Unmarshal(raw, &event); err == nil {
		go processEvent(event.Event, event.Data)
	}
}

func processEvent(name string, data map[string]interface{}) {
	log.Printf("event=%s data=%+v", name, data)
}

func abs(x int64) int64 { if x < 0 { return -x }; return x }

func main() {
	http.HandleFunc("/webhook", handler)
	log.Fatal(http.ListenAndServe(":3000", nil))
}
```

## Pre-go-live checklist

- [ ] HTTPS (TLS valid, not self-signed).
- [ ] Verify HMAC + timestamp on every request.
- [ ] Dedupe by `X-Zorio-Delivery`.
- [ ] Process events asynchronously, return 200 within < 5s.
- [ ] Log full payload + delivery_id for debugging.
- [ ] Test with the **Send test event** button in the Admin Console.
- [ ] Stress-test at ≥ 200 req/s if you expect high volume.

## Related docs

- [Register a webhook](/en/webhooks/register)
- [HMAC-SHA256 signing](/en/webhooks/hmac)
- [Retry policy](/en/webhooks/retry)


---

# API methods

<!-- source: https://docs.zorio.vn/sdk/webphone/api.md -->

# API methods

Class `ZorioWebphone` expose 12 phương thức chính. Bốn phương thức đầu nằm trên instance webphone (`phone.*`), tám phương thức điều khiển cuộc gọi nằm trên object cuộc gọi (`call.*` — trả về từ `phone.call()` hoặc payload event `incoming_call`).

::: tip Phương pháp gọi
Mọi method đều **async** trả về Promise. Anh chị `await` để bắt error và đảm bảo state sync trước khi gọi method tiếp theo.
:::

## 1. Static factory

```ts
ZorioWebphone.connect(opts: ConnectOptions): Promise<ZorioWebphone>
ZorioWebphone.diagnose(opts: { apiBase: string; token: string }): Promise<DiagnoseResult>
```

`connect()` bootstrap: gọi `/api/webphone/sip-config` → tạo `UserAgent` SIP.js → register → mount UI (nếu có `mount`). `diagnose()` chạy preflight HTTPS / Micro / WSS / STUN / TURN — gọi trước `connect()` khi debug.

```ts
interface ConnectOptions {
  apiBase:              string
  token:                string
  mount?:               string | HTMLElement
  layout?:              'docked' | 'overlay' | 'fullscreen'
  theme?:               'light' | 'dark' | 'auto'
  locale?:              'vi' | 'en'
  autoRegister?:        boolean
  ringtoneUrl?:         string
  audioOutputDeviceId?: string
  audioInputDeviceId?:  string
  tokenResolver?:       () => Promise<string>
  debug?:               boolean
  onError?:             (err: ZorioWebphoneError) => void
}
```

## 2. Instance methods — connection & control

### 2.1 `connect`

Đã document ở phần Static factory phía trên. Trả về `phone` instance dùng cho các method còn lại.

### 2.2 `disconnect`

```ts
phone.disconnect(): Promise<void>
```

Đóng toàn bộ resource: unregister SIP, đóng WebSocket, remove UI DOM (nếu embedded), clear audio element, cancel mọi reconnect timer. **Bắt buộc gọi** khi user logout app.

```ts
async function onLogout() {
  await phone.disconnect()
  redirectTo('/login')
}
```

::: tip Pagehide tự xử lý
SDK đã tự `addEventListener('pagehide', ...)` để unregister sạch khi user đóng tab. Anh chị chỉ cần gọi `disconnect()` thủ công cho luồng logout chủ động.
:::

### 2.3 `call`

```ts
phone.call(number: string, options?: CallOptions): Promise<ZorioCall>

interface CallOptions {
  campaignId?:  number
  leadId?:      number
  customerId?:  number
  recording?:   boolean
  callerName?:  string
  meta?:        Record<string, unknown>
}
```

Khởi tạo cuộc gọi outbound. Trả về `ZorioCall` ngay sau khi SIP `INVITE` được gửi (state `originating`); cuộc gọi tiếp tục lifecycle qua events [`call_ringing`](/sdk/webphone/events#call-ringing) → [`call_answered`](/sdk/webphone/events#call-answered) → [`call_hangup`](/sdk/webphone/events#call-hangup).

```ts
const call = await phone.call('0912345678', {
  campaignId: 36,
  leadId: 78912,
  recording: true,
  meta: { source: 'crm-quickdial' },
})
console.log('Call UUID:', call.uuid)
```

::: warning Format số
Format số tuân thủ dial-plan Zorio PBX của khách hàng. Mặc định E.164 (`+84912345678`) hoặc số quốc nội (`0912345678`). Số không parse được sẽ throw `ZorioWebphoneError` với `code = 'invalid_target'`.
:::

## 3. Call-control methods (trên `ZorioCall`)

Các method sau gọi trên object `ZorioCall` lấy được từ `phone.call()`, payload `incoming_call`, hoặc qua `phone.calls.find(c => c.state === 'answered')`.

### 3.1 `answer`

```ts
call.answer(): Promise<void>
```

Trả lời cuộc gọi inbound. Throw `code = 'not_incoming'` nếu gọi trên outbound. Tự attach micro track + remote audio.

```ts
phone.on('incoming_call', async ({ call }) => {
  if (myUI.shouldAutoAnswer()) await call.answer()
})
```

### 3.2 `reject` / `hangup`

```ts
call.hangup(): Promise<void>
```

Kết thúc cuộc gọi ở **bất kỳ state nào**. SDK tự chọn SIP method phù hợp:

| State | SIP method |
|---|---|
| `originating` (outbound chưa ring) | `CANCEL` |
| `ringing` inbound (chưa answer) | `REJECT` (response 486 / 603) |
| `answered` | `BYE` |

::: tip `reject` vs `hangup`
SDK expose chung qua `call.hangup()` — state-aware. Khi bạn muốn rõ semantic "từ chối cuộc đến", có thể alias:

```ts
const reject = (call: ZorioCall) => call.hangup()
```
:::

### 3.3 `mute` / `unmute`

```ts
call.mute():   Promise<void>
call.unmute(): Promise<void>
```

Tắt/bật micro local. KHÔNG ảnh hưởng remote audio. State sync qua property `call.muted: boolean` và emit event `muted` / `unmuted`.

```ts
muteBtn.onclick = async () => {
  const active = phone.calls.find(c => c.state === 'answered')
  if (!active) return
  if (active.muted) await active.unmute()
  else              await active.mute()
}
```

### 3.4 `hold` / `unhold`

```ts
call.hold():   Promise<void>
call.unhold(): Promise<void>
```

Tạm dừng cuộc gọi qua SIP `re-INVITE` với SDP `a=sendonly`. Hold đúng chuẩn nên callee sẽ nghe music-on-hold của Zorio PBX (nếu profile bật).

```ts
await call.hold()
// ... user xử lý việc khác
await call.unhold()
```

### 3.5 `sendDtmf`

```ts
call.sendDtmf(digits: string): Promise<void>
```

Gửi DTMF tones qua RFC 2833. Hỗ trợ ký tự `0-9`, `*`, `#`, `A-D`. Ký tự khác throw `code = 'invalid_dtmf'`.

```ts
// Điều hướng IVR sau khi callee answer (đợi 1s cho IVR phát prompt)
phone.on('call_answered', async ({ call }) => {
  await new Promise(r => setTimeout(r, 1000))
  await call.sendDtmf('1')      // chọn nhánh 1
  await call.sendDtmf('2#')     // chọn 2 rồi #
})
```

### 3.6 `transfer`

```ts
call.transfer(target: string): Promise<void>
```

Blind transfer — chuyển cuộc gọi sang `target` (extension/số điện thoại) không cần consult. State chuyển về `closed` sau khi SIP `REFER` được Zorio PBX chấp nhận.

```ts
// User bấm "Chuyển sang nhánh 2002"
await call.transfer('2002')
```

::: warning v1.0 — chưa hỗ trợ
`transfer()` và phương thức consult attended transfer hiện throw `code = 'not_implemented'` trong v1.0. Đặt vào roadmap Phase 2. Đối tác cần transfer hôm nay có thể fallback qua `*8` blind-transfer Zorio PBX feature code → bấm DTMF qua `sendDtmf('*8' + target + '#')`.
:::

## 4. Events subscription

`phone.on()` / `phone.off()` tuy không nằm trong 12 method chính nhưng là phần không thể thiếu:

```ts
phone.on<E extends EventName>(event: E, handler: (payload: EventPayload<E>) => void): void
phone.off<E extends EventName>(event: E, handler?: Function): void
```

Xem chi tiết tất cả 12 events ở [trang Events](/sdk/webphone/events).

## 5. Properties read-only

Một số property tiện theo dõi state mà không cần wait event:

```ts
phone.status        // 'connecting' | 'registered' | 'unregistered' | 'failed'
phone.extension     // số máy nhánh SIP đã đăng ký
phone.user          // UserProfile | null
phone.calls         // ZorioCall[] — mọi cuộc đang active

// Trên ZorioCall:
call.uuid           // UUID Zorio PBX (link với CDR)
call.direction      // 'incoming' | 'outgoing'
call.state          // 'originating' | 'ringing' | 'answered' | 'wrap_up' | 'closed'
call.number         // số đối phương (E.164)
call.startedAt      // Date — lúc khởi tạo
call.answeredAt     // Date | null — lúc kết nối thành công
call.endedAt        // Date | null
call.muted          // boolean
call.onHold         // boolean
```

## 6. Error handling

Tất cả method throw `ZorioWebphoneError`:

```ts
class ZorioWebphoneError extends Error {
  code:     string
  details?: Record<string, unknown>
}
```

Mã lỗi thường gặp: `bootstrap_failed`, `webphone_disabled`, `incomplete_sip_config`, `invalid_target`, `not_incoming`, `invalid_dtmf`, `audio_autoplay_blocked`, `reconnect_failed`, `not_implemented`, `not_bootstrapped`.

```ts
try {
  const call = await phone.call('xxx')
} catch (err) {
  if (err.code === 'invalid_target') {
    alert('Số gọi không hợp lệ')
  } else {
    console.error(err)
  }
}
```

## 7. Bảng tổng hợp 12 method chính

| # | Method | Phạm vi | Mục đích |
|---|---|---|---|
| 1 | `connect` | static | Bootstrap SDK + register SIP |
| 2 | `disconnect` | `phone` | Đóng sạch, dùng khi logout |
| 3 | `call` | `phone` | Khởi tạo outbound |
| 4 | `hangup` | `call` | Cancel/Bye cuộc đang đi |
| 5 | `answer` | `call` | Trả lời inbound |
| 6 | `reject` | `call` | Alias hangup khi inbound chưa answer |
| 7 | `mute` | `call` | Tắt micro |
| 8 | `unmute` | `call` | Bật micro |
| 9 | `hold` | `call` | Tạm dừng (re-INVITE sendonly) |
| 10 | `unhold` | `call` | Tiếp tục |
| 11 | `sendDtmf` | `call` | Gửi tone IVR |
| 12 | `transfer` | `call` | Blind transfer (Phase 2) |

Tham khảo thêm:

- [Events](/sdk/webphone/events)
- [Quickstart HTML](/sdk/webphone/quickstart)


---

# Events

<!-- source: https://docs.zorio.vn/sdk/webphone/events.md -->

# Events

Webphone SDK emit 12 events theo lifecycle SIP registration + cuộc gọi + lỗi hệ thống. Anh chị subscribe qua `phone.on(eventName, handler)` và unsubscribe qua `phone.off(eventName, handler?)`.

::: tip Phạm vi handler
Handler được gọi **đồng bộ** khi event xảy ra. Nếu trong handler cần async work nặng (gọi API, ghi DB), nên `await` riêng để không block event loop của SDK.
:::

## Bảng tổng hợp

| # | Event | Payload | Khi nào emit |
|---|---|---|---|
| 1 | `registered` | `{}` | SIP register thành công lần đầu hoặc sau reconnect |
| 2 | `unregistered` | `{ reason }` | SIP unregister (manual / remote / transport_disconnect) |
| 3 | `connected` | `{}` | WebSocket WSS lên — chưa register |
| 4 | `disconnected` | `{ reason? }` | WebSocket drop, trước khi auto-reconnect kick in |
| 5 | `incoming_call` | `{ call, contact }` | INVITE tới |
| 6 | `call_ringing` | `{ call }` | Outbound nhận 180/183, hoặc inbound đang đổ chuông local |
| 7 | `call_answered` | `{ call }` | Cuộc gọi vào state `answered` |
| 8 | `call_hangup` | `{ call, reason, billsec }` | Bất kỳ bên nào hangup, hoặc call fail |
| 9 | `dtmf` | `{ call, digit }` | Nhận DTMF từ remote (RFC 2833) |
| 10 | `error` | `ZorioWebphoneError` | Mọi lỗi runtime — bắt buộc handle |
| 11 | `auto_reconnect` | `{ attempt, delay_ms }` | Mỗi lần supervisor thử reconnect lại |
| 12 | `audio_autoplay_blocked` | `{ call }` | Browser block autoplay khi cuộc gọi tới |

## 1. `registered`

```ts
phone.on('registered', () => {
  console.log('SIP sẵn sàng, extension:', phone.extension)
  showBanner('Đã online', 'success')
})
```

Emit cả lần register đầu (sau `connect()`) và mọi lần re-register thành công sau reconnect. Dùng để hiển thị trạng thái online lên UI.

## 2. `unregistered`

```ts
phone.on('unregistered', ({ reason }) => {
  // reason: 'manual' | 'remote' | 'transport_disconnect'
  if (reason === 'transport_disconnect') {
    showBanner('Mất kết nối, đang khôi phục…', 'warn')
  }
})
```

| `reason` | Ý nghĩa |
|---|---|
| `manual` | User gọi `phone.unregister()` chủ động |
| `remote` | Zorio PBX gửi 401/403, có thể do credential thay đổi |
| `transport_disconnect` | WebSocket WSS drop |

## 3. `connected`

```ts
phone.on('connected', () => {
  console.log('WSS đã connect — chuẩn bị register')
})
```

WebSocket layer lên nhưng SIP `REGISTER` chưa hoàn tất. Hữu ích để hiển thị progress 2-step "Connecting…" → "Registering…" → "Ready".

## 4. `disconnected`

```ts
phone.on('disconnected', ({ reason }) => {
  console.warn('WSS drop:', reason)
})
```

WebSocket bị đóng. SDK supervisor sẽ tự retry — emit kèm `auto_reconnect` sau đó.

## 5. `incoming_call`

```ts
phone.on('incoming_call', ({ call, contact }) => {
  myUI.showIncomingPopup({
    name: contact?.full_name || call.number,
    onAccept: () => call.answer(),
    onReject: () => call.hangup(),
  })
})
```

Payload đầy đủ:

```ts
{
  call: ZorioCall,                       // direction='incoming', state='ringing'
  contact: {
    id: number
    full_name: string
    phones?: string[]
    customer_id?: number
    lead_id?: number
  } | null
}
```

`contact` lookup từ backend Zorio (`/api/contacts/lookup?number=...`). Nếu chưa có khách trong CSKH → `contact = null`, hiển thị raw `call.number`.

## 6. `call_ringing`

```ts
phone.on('call_ringing', ({ call }) => {
  if (call.direction === 'outgoing') {
    showStatus(`Đang gọi ${call.number}…`)
  }
})
```

::: tip Early media v7
Với outbound, event này emit khi SDK nhận **SIP 180 Ringing** hoặc **183 Session Progress**. Nhờ `earlyMedia: true`, bạn nghe ringback / IVR carrier announcement **ngay từ lúc này** — không cần đợi answer.
:::

## 7. `call_answered`

```ts
phone.on('call_answered', ({ call }) => {
  console.log('Kết nối thành công, UUID:', call.uuid)
  startTimer(call.uuid)
})
```

Cuộc gọi đã được phía remote bốc máy (200 OK + ACK). Bắt đầu billsec tính từ thời điểm này.

## 8. `call_hangup`

```ts
phone.on('call_hangup', ({ call, reason, billsec }) => {
  stopTimer(call.uuid)
  if (reason === 'no_answer') {
    showToast('Không bắt máy')
  } else if (reason === 'busy') {
    showToast('Máy bận')
  }
  saveBillsec(call.uuid, billsec)
})
```

| `reason` thường gặp | Nguồn Zorio PBX HangupCause |
|---|---|
| `normal_clearing` | `NORMAL_CLEARING` (billsec > 0) |
| `no_answer` | `NORMAL_CLEARING + billsec = 0` hoặc `NO_ANSWER` |
| `busy` | `USER_BUSY` |
| `unallocated_number` | `UNALLOCATED_NUMBER` |
| `originator_cancel` | `ORIGINATOR_CANCEL` |
| `call_rejected` | `CALL_REJECTED` |

Chi tiết mapping xem [Hangup cause codes](/tham-chieu/hangup-codes).

## 9. `dtmf`

```ts
phone.on('dtmf', ({ call, digit }) => {
  console.log('Remote bấm:', digit)
})
```

Nhận DTMF gửi đến từ remote (vd khách hàng bấm phím trong IVR đối ứng). `digit` là single character `0-9 * # A-D`.

## 10. `error`

```ts
phone.on('error', (err) => {
  switch (err.code) {
    case 'bootstrap_failed':
      alert('Không kết nối được tới Zorio — kiểm tra token / network')
      break
    case 'audio_autoplay_blocked':
      showBanner('Vui lòng click vào trang để bật âm thanh')
      break
    case 'reconnect_failed':
      showBanner('Mất kết nối quá lâu — vui lòng reload trang')
      break
    default:
      console.error('[zorio-webphone]', err.code, err.message, err.details)
  }
})
```

Catch-all cho mọi runtime error. Class `ZorioWebphoneError`:

```ts
class ZorioWebphoneError extends Error {
  code:     string                            // machine-readable
  details?: Record<string, unknown>
}
```

Mã `code` đầy đủ xem [API methods → Error handling](/sdk/webphone/api#_6-error-handling).

## 11. `auto_reconnect`

```ts
phone.on('auto_reconnect', ({ attempt, delay_ms }) => {
  console.log(`Reconnect lần ${attempt}, đợi ${delay_ms}ms`)
  if (attempt > 5) showBanner('Đường truyền không ổn định', 'warn')
})
```

Emit mỗi lần supervisor v7 lên lịch reconnect. Exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (cap) + jitter 0-500ms. Reset khi register lại OK.

::: tip UX khuyến nghị
Hiển thị banner discreet "Đang khôi phục kết nối…" khi `attempt >= 2`. Đừng làm hoảng user ngay attempt đầu vì network blip 1-2s là bình thường.
:::

## 12. `audio_autoplay_blocked`

```ts
phone.on('audio_autoplay_blocked', ({ call }) => {
  // Safari/iOS chặn autoplay khi tab chưa có user gesture
  myUI.showUnlockBanner({
    message: 'Bấm vào đây để bật âm thanh cuộc gọi',
    onClick: async () => {
      await phone.unlockAudio() // tạo gesture context cho audio element
    },
  })
})
```

::: warning Safari / iOS quirk
Browser block `audio.play()` nếu trang chưa có user interaction (click/tap). SDK detect → emit event này → host app PHẢI hiển thị nút yêu cầu user bấm. Nếu bỏ qua, cuộc gọi vẫn kết nối nhưng user không nghe được audio.
:::

## Pattern thường dùng

### Wire 3 events tối thiểu cho MVP

```ts
const phone = await ZorioWebphone.connect({ apiBase, token, mount: '#zorio-phone' })

phone.on('incoming_call', ({ call, contact }) => myUI.showIncoming(call, contact))
phone.on('call_answered',  ({ call }) => myUI.openInCall(call))
phone.on('call_hangup',    ({ call, billsec }) => myUI.closeInCall(call, billsec))
phone.on('error',          (err) => console.error(err))
```

### Theo dõi state online cho dashboard

```ts
function updateStatusBadge() {
  badge.textContent = phone.status === 'registered' ? '🟢 Online' : '🔴 Offline'
}

phone.on('registered',        updateStatusBadge)
phone.on('unregistered',      updateStatusBadge)
phone.on('connected',         updateStatusBadge)
phone.on('disconnected',      updateStatusBadge)
phone.on('auto_reconnect',    updateStatusBadge)
```

Tham khảo thêm:

- [API methods](/sdk/webphone/api)
- [Quickstart HTML](/sdk/webphone/quickstart)


---

# Nhúng qua iframe (SSO)

<!-- source: https://docs.zorio.vn/sdk/webphone/iframe.md -->

# Nhúng qua iframe (SSO)

Phương án nhúng đơn giản nhất cho **CRM legacy không sửa được source frontend** hoặc khi đối tác chỉ muốn "treo" webphone Zorio mà không cần controlling nó. Iframe đã được build sẵn UI đầy đủ (dialer, popup incoming, in-call panel), chỉ cần `<iframe src=...>` là chạy.

## 1. Cú pháp tối giản

```html
<iframe
  src="https://app.zorio.vn/webphone-embed?token=<jwt>"
  allow="microphone"
  style="border:0; width:380px; height:560px"
></iframe>
```

::: tip Tên miền tuỳ chỉnh
Thay `app.zorio.vn` bằng tên miền tuỳ chỉnh riêng nếu đối tác đã được cấp custom domain (vd `pbx.crm-cua-ban.vn`). Iframe luôn host trên đúng tên miền cấp cho khách hàng để bearer token / SIP credentials không bị cross-account.
:::

## 2. SSO exchange — lấy `<jwt>`

JWT truyền qua query string là **short-lived embed token** (TTL mặc định 5 phút), được backend của đối tác đổi từ session user của họ qua API:

```
POST https://acme.zorio.example/api/webphone/embed-token
Authorization: Bearer <bearer-token-từ-/api/auth/login>
Content-Type: application/json

{
  "ttl_seconds": 300
}
```

Response:

```json
{
  "embed_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-06-30T10:35:00+07:00"
}
```

::: warning Không expose bearer token chính
Tuyệt đối **không** truyền bearer token gốc vào `src` của iframe. Bearer dài hạn lộ qua URL sẽ ghi vào Referer header / log proxy. Luôn đổi sang embed token TTL ngắn rồi inject vào iframe.
:::

### Flow điển hình

```text
[CRM của đối tác]               [Backend CRM]                [Zorio API]
       │                              │                            │
       │  cần render webphone         │                            │
       ├─────────────────────────────►│                            │
       │                              │  POST /webphone/embed-token│
       │                              ├───────────────────────────►│
       │                              │                            │
       │                              │◄───────────────────────────┤
       │                              │  embed_token (TTL 5 phút)  │
       │◄─────────────────────────────┤                            │
       │  embed_token                 │                            │
       │                              │                            │
       │  <iframe src="?token=...">                                 │
       │  → mount + SIP register      │                            │
```

Khi token gần hết hạn, frame parent có thể fetch token mới rồi gửi qua `postMessage` (xem [postMessage API](#_5-postmessage-api)).

## 3. Cấu hình query string đầy đủ

```html
<iframe
  src="https://app.zorio.vn/webphone-embed
        ?token=<jwt>
        &layout=docked
        &theme=auto
        &locale=vi
        &auto_register=1"
  allow="microphone"
  style="border:0; width:380px; height:560px"
></iframe>
```

| Tham số | Giá trị | Mô tả |
|---|---|---|
| `token` | JWT embed | Bắt buộc — short-lived embed token |
| `layout` | `docked` \| `overlay` \| `fullscreen` | Bố cục UI. Default: `docked` |
| `theme` | `light` \| `dark` \| `auto` | Default: `auto` |
| `locale` | `vi` \| `en` | Default: `vi` |
| `auto_register` | `1` \| `0` | Tự register SIP sau load. Default: `1` |

## 4. Quyền microphone trên iframe

Bắt buộc thêm `allow="microphone"` — nếu thiếu, browser sẽ block `getUserMedia` ngay cả khi user đã cấp quyền cho parent page:

```html
<iframe allow="microphone" ... ></iframe>

<!-- Nếu cần thêm camera (video Phase 2): -->
<iframe allow="microphone; camera" ... ></iframe>
```

::: warning Cross-origin
Iframe `app.zorio.vn` luôn cross-origin với CRM của đối tác → mọi giao tiếp giữa parent và iframe **phải qua postMessage** (xem [postMessage API](#_5-postmessage-api)). Không cố truy cập `iframe.contentWindow.phone` trực tiếp — sẽ bị browser block.
:::

## 5. postMessage API

Iframe webphone giao tiếp với parent qua [`window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). Mọi message đều có format:

```ts
interface ZorioWebphoneMessage {
  source: 'zorio-webphone'   // marker, lọc message khác
  type:   string             // tên event hoặc command
  payload?: any              // dữ liệu kèm theo
}
```

### 5.1 Lắng nghe event từ iframe (iframe → parent)

```js
window.addEventListener('message', (e) => {
  if (e.origin !== 'https://app.zorio.vn') return       // verify origin
  if (e.data?.source !== 'zorio-webphone') return       // verify marker

  switch (e.data.type) {
    case 'registered':
      console.log('Webphone đã sẵn sàng')
      break
    case 'incoming_call':
      console.log('Cuộc gọi đến:', e.data.payload.call.number)
      myUI.showIncomingBanner(e.data.payload)
      break
    case 'call_answered':
      myUI.openCallControls(e.data.payload.call.uuid)
      break
    case 'call_hangup':
      myUI.closeCallControls()
      console.log('Billsec:', e.data.payload.billsec)
      break
    case 'error':
      console.error('Webphone error:', e.data.payload)
      break
  }
})
```

Iframe forward đầy đủ 12 events giống SDK npm/UMD — xem [Events](/sdk/webphone/events).

### 5.2 Điều khiển webphone (parent → iframe)

```js
const iframe = document.querySelector('iframe')

function sendCommand(type, payload) {
  iframe.contentWindow.postMessage(
    { source: 'zorio-webphone', type, payload },
    'https://app.zorio.vn'  // target origin — KHÔNG dùng '*'
  )
}

// Click-to-call từ button trong CRM
sendCommand('call', {
  number: '0912345678',
  options: { campaignId: 36, leadId: 78912 },
})

// Hangup cuộc đang nói
sendCommand('hangup', {})

// Gửi DTMF
sendCommand('send_dtmf', { digits: '1' })

// Mute / unmute
sendCommand('mute', {})
sendCommand('unmute', {})

// Refresh token sắp hết hạn
sendCommand('refresh_token', { token: newEmbedToken })
```

Danh sách `type` command tương ứng 1-1 với [12 method API](/sdk/webphone/api).

### 5.3 Ví dụ tích hợp đầy đủ

```html
<div id="phone-container">
  <iframe
    id="zorio-frame"
    src="https://app.zorio.vn/webphone-embed?token=PLACEHOLDER"
    allow="microphone"
    style="border:0; width:380px; height:560px"
  ></iframe>
</div>

<button id="btn-call">Gọi 0912345678</button>

<script>
const ZORIO_ORIGIN = 'https://app.zorio.vn'
const iframe = document.getElementById('zorio-frame')

// 1. Lấy embed token rồi inject
fetch('/api/internal/zorio-embed-token').then(r => r.json()).then(({ token }) => {
  iframe.src = `${ZORIO_ORIGIN}/webphone-embed?token=${token}&layout=docked`
})

// 2. Lắng nghe events
window.addEventListener('message', (e) => {
  if (e.origin !== ZORIO_ORIGIN) return
  if (e.data?.source !== 'zorio-webphone') return
  console.log('[zorio]', e.data.type, e.data.payload)
})

// 3. Điều khiển
document.getElementById('btn-call').onclick = () => {
  iframe.contentWindow.postMessage(
    { source: 'zorio-webphone', type: 'call', payload: { number: '0912345678' } },
    ZORIO_ORIGIN
  )
}
</script>
```

## 6. Tính năng v7 vẫn hoạt động trong iframe

Iframe build từ cùng bundle SDK, nên đầy đủ:

- **Auto-reconnect supervisor** — không cần xử lý reconnect ở parent.
- **Pagehide cleanup** — khi user đóng tab CRM, iframe unregister sạch.
- **Early media** — outbound nghe ringback ngay từ 183 Session Progress.

## 7. Khi nào nên iframe vs SDK npm/UMD?

| Tiêu chí | Iframe | SDK npm/UMD |
|---|---|---|
| Tốc độ tích hợp | ✅ Nhanh nhất (1 thẻ `<iframe>`) | Trung bình |
| Custom UI | ❌ UI mặc định của Zorio | ✅ Toàn quyền |
| Cross-origin | ✅ Cách ly hoàn toàn | Cần CSP setup |
| Tùy biến events nâng cao | postMessage | ✅ Native callback |
| Air-gap | Cần host iframe nội bộ | ✅ Self-host UMD |

::: tip Khuyến nghị
Nếu đối tác chỉ cần "có cái webphone" trên CRM trong **một ngày** → dùng iframe. Nếu cần custom UX hoặc tích hợp sâu vào workflow CRM (CTI, screen-pop) → dùng [npm](/sdk/webphone/npm) hoặc [UMD](/sdk/webphone/umd).
:::

Tham khảo thêm:

- [API methods](/sdk/webphone/api)
- [Events](/sdk/webphone/events)


---

# Webphone SDK — Tổng quan

<!-- source: https://docs.zorio.vn/sdk/webphone/index.md -->

# Webphone SDK — Tổng quan

> SDK WebRTC để nhúng webphone vào CRM/ứng dụng riêng của khách hàng. Framework-agnostic vanilla DOM UI, 4 distribution channels (npm / UMD / airgap / iframe).
>
> Build từ Vite library mode + TypeScript + SIP.js v0.21.

## Phạm vi

- 12 phương thức API (`connect`, `disconnect`, `call`, `hangup`, `answer`, `reject`, `mute`, `unmute`, `hold`, `unhold`, `sendDtmf`, `transfer`).
- 12 events (`registered`, `unregistered`, `connected`, `disconnected`, `incoming_call`, `call_ringing`, `call_answered`, `call_hangup`, ...).
- Auto-reconnect + re-register supervisor + pagehide cleanup.
- Early media (ringback, IVR carrier announcement).

## Các phương thức nhúng

| Phương thức | Tài liệu |
|---|---|
| npm (bundler riêng) | [Tới trang](/sdk/webphone/npm) |
| UMD/CDN (HTML thuần) | [Tới trang](/sdk/webphone/umd) |
| iframe (SSO) | [Tới trang](/sdk/webphone/iframe) |
| API methods | [Tới trang](/sdk/webphone/api) |
| Events | [Tới trang](/sdk/webphone/events) |
| Quickstart HTML | [Tới trang](/sdk/webphone/quickstart) |


---

# Nhúng qua npm

<!-- source: https://docs.zorio.vn/sdk/webphone/npm.md -->

# Nhúng qua npm

Phương thức khuyến nghị cho mọi ứng dụng đã có sẵn build pipeline (Vite / webpack / Rollup / Next.js / Nuxt / Angular CLI…). SDK đi kèm TypeScript declarations và ES modules tree-shakable.

## 1. Cài đặt package

SDK được phát hành dưới dạng **tarball nội bộ** (`zorio-webphone-sdk-1.0.0.tgz`) hoặc qua npm scoped registry mà đội Zorio cung cấp riêng cho từng đối tác.

```bash
# Cách A — cài trực tiếp từ tarball Zorio cấp
npm install ./zorio-webphone-sdk-1.0.0.tgz

# Cách B — qua scoped registry (nếu đối tác đã được cấp quyền)
npm install @zorio/webphone-sdk
```

::: tip Phiên bản
SDK v1 dùng `sip.js@0.21.x` làm transport WebRTC + SIP signaling. Bundle ~85 KB gzipped, đã include sẵn SIP.js — bạn **không cần** tự cài thêm.
:::

## 2. Import + khởi tạo

```ts
import { ZorioWebphone } from '@zorio/webphone-sdk'

const phone = await ZorioWebphone.connect({
  apiBase: 'https://acme.zorio.example',
  token:   bearerToken,
  mount:   '#zorio-phone', // bỏ trống nếu chạy headless
})
```

`ZorioWebphone.connect()` trả về một Promise — đợi resolve trước khi gọi `phone.call()` hoặc subscribe events.

## 3. TypeScript

Package đã kèm `.d.ts`, bạn import type trực tiếp:

```ts
import type {
  ConnectOptions,
  ZorioCall,
  ZorioWebphoneError,
  CallOptions,
  DiagnoseResult,
} from '@zorio/webphone-sdk'

const opts: ConnectOptions = {
  apiBase: import.meta.env.VITE_ZORIO_API_BASE,
  token:   import.meta.env.VITE_ZORIO_TOKEN,
  mount:   '#zorio-phone',
  layout:  'docked',
  theme:   'auto',
  locale:  'vi',
  autoRegister: true,
}

const phone = await ZorioWebphone.connect(opts)
```

## 4. Ví dụ tích hợp Vue 3 (Composition API)

```vue
<script setup lang="ts">
import { onMounted, onBeforeUnmount, ref } from 'vue'
import { ZorioWebphone } from '@zorio/webphone-sdk'

const phoneRef = ref<ZorioWebphone | null>(null)

onMounted(async () => {
  phoneRef.value = await ZorioWebphone.connect({
    apiBase: 'https://acme.zorio.example',
    token:   await getBearerToken(),
    mount:   '#zorio-phone',
  })

  phoneRef.value.on('incoming_call', ({ call, contact }) => {
    console.log('Cuộc gọi đến:', contact?.full_name || call.number)
  })
})

onBeforeUnmount(async () => {
  await phoneRef.value?.disconnect()
})
</script>

<template>
  <div id="zorio-phone" />
</template>
```

## 5. Ví dụ tích hợp React

```tsx
import { useEffect, useRef } from 'react'
import { ZorioWebphone } from '@zorio/webphone-sdk'

export function WebphoneWidget({ token }: { token: string }) {
  const phoneRef = useRef<ZorioWebphone | null>(null)

  useEffect(() => {
    let cancelled = false
    ;(async () => {
      const phone = await ZorioWebphone.connect({
        apiBase: 'https://acme.zorio.example',
        token,
        mount:   '#zorio-phone',
      })
      if (cancelled) { await phone.disconnect(); return }
      phoneRef.current = phone
    })()
    return () => {
      cancelled = true
      phoneRef.current?.disconnect()
    }
  }, [token])

  return <div id="zorio-phone" />
}
```

## 6. Tính năng v7 quan trọng

::: warning Auto-reconnect + re-register supervisor
SDK v7 tự động re-register SIP khi WebSocket bị throttle (tab nền) hoặc network drop. Anh chị **không cần** code thêm logic reconnect — chỉ nên lắng nghe event `auto_reconnect` để hiển thị banner "Đang khôi phục kết nối…" cho user.
:::

::: tip Pagehide cleanup
Khi user đóng tab, SDK tự `unregister` sạch về Zorio PBX để tránh stale registration (gây miss inbound trong window timeout). Hoạt động cả khi nhúng qua bundler.
:::

::: tip Early media
Outbound call qua di động sẽ phát ringback / IVR carrier announcement **ngay từ SIP 183 Session Progress** thay vì im lặng tới khi callee bốc máy. Bật mặc định trong SDK v7 (`earlyMedia: true`).
:::

## 7. Bundler config gợi ý

Vite / Rollup mặc định tree-shake tốt. Nếu dùng webpack < 5 và gặp lỗi `Cannot resolve module`, thêm:

```js
// webpack.config.js
module.exports = {
  resolve: {
    fallback: { crypto: false, stream: false, buffer: false },
  },
}
```

Tham khảo thêm:

- [API methods](/sdk/webphone/api)
- [Events](/sdk/webphone/events)
- [Quickstart HTML](/sdk/webphone/quickstart)


---

# Quickstart HTML

<!-- source: https://docs.zorio.vn/sdk/webphone/quickstart.md -->

# Quickstart HTML

File HTML đầy đủ copy-paste chạy ngay — không cần build pipeline, không cần npm install. Mở bằng browser (qua HTTPS hoặc `localhost`) là gọi điện được.

::: tip Yêu cầu trước khi chạy
- Trang phải serve qua **HTTPS** (WebRTC mandate). Test local có thể dùng `localhost` thường.
- Browser ≥ Chrome 90 / Edge 90 / Firefox 90 / Safari 14.
- Có **Bearer token** lấy từ `POST /api/auth/login` của tài khoản Zorio đang dùng.
- Đã cấp quyền microphone cho trang.
:::

## 1. Quickstart tối giản (~20 dòng)

```html
<!DOCTYPE html>
<html lang="vi">
<head>
  <meta charset="UTF-8" />
  <title>Zorio Webphone Quickstart</title>
</head>
<body>
  <div id="zorio-phone" style="position:fixed;bottom:24px;right:24px"></div>

  <script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
  <script>
    const { ZorioWebphone } = window.ZorioWebphoneSDK

    ZorioWebphone.connect({
      apiBase: 'https://acme.zorio.example',
      token:   'PASTE-BEARER-TOKEN-HERE',
      mount:   '#zorio-phone',
    }).then((phone) => {
      window.phone = phone
      console.log('Webphone sẵn sàng — gõ phone.call("0912345678") để gọi thử')
    })
  </script>
</body>
</html>
```

## 2. Quickstart đầy đủ — dialer + status + log + 12 events

File HTML standalone dưới đây bao gồm: form login token, dialer pad, status badge, real-time event log, error banner. Đây là template Zorio dùng để demo cho đối tác.

```html
<!DOCTYPE html>
<html lang="vi">
<head>
  <meta charset="UTF-8" />
  <title>Zorio Webphone — Quickstart đầy đủ</title>
  <style>
    body { font-family: system-ui, sans-serif; max-width: 880px; margin: 24px auto; padding: 0 16px; }
    .row { display: flex; gap: 12px; align-items: center; margin: 12px 0; }
    input, button { padding: 8px 12px; font-size: 14px; border-radius: 6px; border: 1px solid #cbd5e1; }
    button { cursor: pointer; background: #2563eb; color: #fff; border-color: #2563eb; }
    button.secondary { background: #f1f5f9; color: #0f172a; border-color: #cbd5e1; }
    button.danger    { background: #dc2626; border-color: #dc2626; }
    button:disabled  { opacity: 0.5; cursor: not-allowed; }
    #status { font-weight: 600; padding: 4px 10px; border-radius: 999px; background: #f1f5f9; }
    #status.ready    { background: #d1fae5; color: #065f46; }
    #status.error    { background: #fee2e2; color: #991b1b; }
    #status.warn     { background: #fef3c7; color: #92400e; }
    #log { background: #0f172a; color: #e2e8f0; font-family: ui-monospace, monospace;
            font-size: 12px; padding: 12px; border-radius: 8px; height: 280px;
            overflow-y: auto; white-space: pre-wrap; }
    .log-row { margin: 2px 0; }
    .log-row .ts  { color: #94a3b8; }
    .log-row .ev  { color: #38bdf8; font-weight: 600; }
    #zorio-phone { position: fixed; bottom: 24px; right: 24px; }
  </style>
</head>
<body>
  <h1>Zorio Webphone — Quickstart</h1>

  <div class="row">
    <input id="api-base" placeholder="https://acme.zorio.example" style="flex:1" />
    <input id="token"    placeholder="Bearer token"             style="flex:2" />
    <button id="btn-connect">Connect</button>
    <button id="btn-disconnect" class="secondary" disabled>Disconnect</button>
    <span id="status">Idle</span>
  </div>

  <div class="row">
    <input id="dial" placeholder="0912345678" style="flex:1" />
    <button id="btn-call"    disabled>Gọi</button>
    <button id="btn-hangup"  class="danger"    disabled>Hangup</button>
    <button id="btn-answer"  class="secondary" disabled>Answer</button>
    <button id="btn-mute"    class="secondary" disabled>Mute</button>
    <button id="btn-hold"    class="secondary" disabled>Hold</button>
  </div>

  <div id="log"></div>
  <div id="zorio-phone"></div>

  <script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
  <script>
    const { ZorioWebphone } = window.ZorioWebphoneSDK
    const $ = (id) => document.getElementById(id)

    let phone = null
    let activeCall = null

    function setStatus(text, cls) {
      const el = $('status')
      el.textContent = text
      el.className = cls || ''
    }
    function log(event, payload) {
      const ts = new Date().toISOString().slice(11, 19)
      const row = document.createElement('div')
      row.className = 'log-row'
      row.innerHTML =
        `<span class="ts">${ts}</span> ` +
        `<span class="ev">${event}</span> ` +
        (payload !== undefined ? JSON.stringify(payload) : '')
      $('log').appendChild(row)
      $('log').scrollTop = $('log').scrollHeight
    }
    function setActiveCall(call) {
      activeCall = call
      $('btn-hangup').disabled = !call
      $('btn-answer').disabled = !(call && call.direction === 'incoming' && call.state === 'ringing')
      $('btn-mute').disabled   = !(call && call.state === 'answered')
      $('btn-hold').disabled   = !(call && call.state === 'answered')
      $('btn-mute').textContent = call?.muted ? 'Unmute' : 'Mute'
      $('btn-hold').textContent = call?.onHold ? 'Unhold' : 'Hold'
    }

    $('btn-connect').onclick = async () => {
      try {
        setStatus('Connecting…', 'warn')
        phone = await ZorioWebphone.connect({
          apiBase: $('api-base').value.trim(),
          token:   $('token').value.trim(),
          mount:   '#zorio-phone',
          debug:   true,
        })
        window.phone = phone

        // === 12 events ===
        phone.on('registered',      ()              => { log('registered'); setStatus('Online', 'ready') })
        phone.on('unregistered',    (p)             => { log('unregistered', p); setStatus('Offline', 'warn') })
        phone.on('connected',       ()              => log('connected'))
        phone.on('disconnected',    (p)             => { log('disconnected', p); setStatus('Disconnected', 'warn') })
        phone.on('incoming_call',   ({ call, contact }) => {
          log('incoming_call', { number: call.number, contact: contact?.full_name })
          setActiveCall(call)
        })
        phone.on('call_ringing',    ({ call })      => { log('call_ringing', { number: call.number }); setActiveCall(call) })
        phone.on('call_answered',   ({ call })      => { log('call_answered', { uuid: call.uuid });   setActiveCall(call) })
        phone.on('call_hangup',     ({ call, reason, billsec }) => {
          log('call_hangup', { reason, billsec })
          setActiveCall(null)
        })
        phone.on('dtmf',            ({ digit })     => log('dtmf', { digit }))
        phone.on('error',           (err)           => { log('error', { code: err.code, msg: err.message }); setStatus('Error: ' + err.code, 'error') })
        phone.on('auto_reconnect',  (p)             => { log('auto_reconnect', p); setStatus(`Reconnect lần ${p.attempt}…`, 'warn') })
        phone.on('audio_autoplay_blocked', ()       => {
          log('audio_autoplay_blocked')
          setStatus('Hãy click vào trang để bật âm thanh', 'warn')
        })

        $('btn-connect').disabled    = true
        $('btn-disconnect').disabled = false
        $('btn-call').disabled       = false
      } catch (err) {
        log('connect-failed', { code: err.code, msg: err.message })
        setStatus('Connect failed', 'error')
      }
    }

    $('btn-disconnect').onclick = async () => {
      await phone?.disconnect()
      phone = null
      setActiveCall(null)
      setStatus('Idle', '')
      $('btn-connect').disabled    = false
      $('btn-disconnect').disabled = true
      $('btn-call').disabled       = true
    }

    $('btn-call').onclick = async () => {
      const num = $('dial').value.trim()
      if (!num) return
      try {
        const call = await phone.call(num, { meta: { source: 'quickstart' } })
        setActiveCall(call)
      } catch (err) {
        log('call-failed', { code: err.code, msg: err.message })
      }
    }
    $('btn-hangup').onclick = () => activeCall?.hangup()
    $('btn-answer').onclick = () => activeCall?.answer()
    $('btn-mute').onclick = async () => {
      if (!activeCall) return
      if (activeCall.muted) await activeCall.unmute()
      else                  await activeCall.mute()
      setActiveCall(activeCall)
    }
    $('btn-hold').onclick = async () => {
      if (!activeCall) return
      if (activeCall.onHold) await activeCall.unhold()
      else                   await activeCall.hold()
      setActiveCall(activeCall)
    }
  </script>
</body>
</html>
```

## 3. Cách dùng

1. Copy toàn bộ HTML phía trên vào file `quickstart.html`.
2. Serve qua HTTPS (vd `npx http-server -S -C cert.pem -K key.pem`), hoặc mở qua `localhost`.
3. Mở browser, nhập:
   - `apiBase`: URL truy cập của khách hàng (vd `https://acme.zorio.example`).
   - `token`: Bearer token lấy từ `POST /api/auth/login`.
4. Bấm **Connect** → đợi status hiện "Online" → nhập số → bấm **Gọi**.

## 4. Quan sát feature v7 trong log

Khi mất mạng tạm thời, log sẽ hiện chuỗi:

```
10:14:32  disconnected     {"reason":"transport_disconnect"}
10:14:33  auto_reconnect   {"attempt":1,"delay_ms":1000}
10:14:34  connected
10:14:34  registered
```

Cuộc gọi outbound qua di động sẽ thấy `call_ringing` (có audio ringback) trước khi `call_answered` — nhờ early media.

::: tip Mở rộng
Thêm cuộc gọi outbound trong campaign telesales:

```js
const call = await phone.call('0912345678', {
  campaignId: 36,
  leadId:     78912,
  recording:  true,
  meta:       { script_id: 12, agent_note: 'gọi lại sau 14h' },
})
```

`campaignId` / `leadId` sẽ link CDR với telesales campaign, hiện ngay trong Reports + Live monitoring của khách hàng.
:::

::: warning Token expose trong quickstart
File này dán bearer token thẳng vào HTML → CHỈ dùng cho demo nội bộ. Production luôn fetch token qua endpoint backend của đối tác, kèm `tokenResolver` để auto-refresh khi 401:

```js
ZorioWebphone.connect({
  apiBase,
  token: currentToken,
  tokenResolver: async () => {
    const r = await fetch('/my-app/refresh-zorio-token', { method: 'POST' })
    return (await r.json()).token
  },
})
```
:::

Tham khảo thêm:

- [Nhúng qua npm](/sdk/webphone/npm) — production-grade
- [API methods](/sdk/webphone/api) — đầy đủ signature TypeScript
- [Events](/sdk/webphone/events) — payload từng event


---

# Nhúng qua UMD/CDN

<!-- source: https://docs.zorio.vn/sdk/webphone/umd.md -->

# Nhúng qua UMD/CDN

Phương thức phù hợp cho website tĩnh, WordPress, CRM legacy không có bundler hoặc môi trường air-gapped không kết nối CDN ngoài. Chỉ cần một thẻ `<script>` là dùng được class `ZorioWebphone` qua biến global.

## 1. Cấu trúc file UMD

| File | Kích thước (~) | Dùng cho |
|---|---|---|
| `zorio-webphone.umd.cjs` | 85 KB gzip | `<script src=...>` |
| `zorio-webphone.umd.js`  | 85 KB gzip | Alias CDN ổn định |
| `zorio-webphone.esm.js`  | 80 KB gzip | `<script type="module">` |

Tất cả bundle đã include sẵn `sip.js@0.21.x` + các dependency runtime — không cần load thêm script ngoài.

## 2. Drop-in qua CDN Zorio

```html
<!DOCTYPE html>
<html lang="vi">
<head>
  <meta charset="UTF-8" />
  <title>Demo Webphone</title>
</head>
<body>
  <div id="zorio-phone" style="position:fixed;bottom:24px;right:24px"></div>

  <script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
  <script>
    const { ZorioWebphone } = window.ZorioWebphoneSDK

    ZorioWebphone.connect({
      apiBase: 'https://acme.zorio.example',
      token:   '<bearer-token-from-login>',
      mount:   '#zorio-phone',
    }).then((phone) => {
      window.phone = phone // tiện debug
      phone.on('incoming_call', ({ call, contact }) => {
        console.log('Cuộc gọi đến:', contact?.full_name || call.number)
      })
    })
  </script>
</body>
</html>
```

::: tip Global namespace
UMD bundle expose `window.ZorioWebphoneSDK`. Class chính lấy ra qua destructuring: `const { ZorioWebphone } = window.ZorioWebphoneSDK`. Anh chị **không** nên đụng tới `window.SIP` (SIP.js nội bộ) — luôn dùng qua class `ZorioWebphone` để giữ tương thích về sau.
:::

## 3. ESM script tag (browser hiện đại)

```html
<script type="module">
  import { ZorioWebphone } from 'https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.esm.js'

  const phone = await ZorioWebphone.connect({
    apiBase: 'https://acme.zorio.example',
    token:   bearerToken,
    mount:   '#zorio-phone',
  })
</script>
```

## 4. Self-host (môi trường air-gapped)

Nếu ứng dụng chạy trong mạng nội bộ không kết nối CDN ngoài (BĐS, ngân hàng, bệnh viện), tải tarball SDK rồi serve qua nginx/Apache:

```
/var/www/static/vendor/zorio-webphone.umd.cjs
/var/www/static/vendor/zorio-webphone.d.ts
```

```html
<script src="/static/vendor/zorio-webphone.umd.cjs"></script>
```

::: warning CSP — Content Security Policy
Khi self-host hoặc nhúng vào trang có CSP nghiêm ngặt, thêm các directive sau:

```
connect-src wss://*.zorio.example https://*.zorio.example;
media-src   blob:;
script-src  'self' https://cdn.zorio.vn;
```

WebRTC cần `blob:` cho `MediaStream` audio element, còn `wss://` cho SIP signaling.
:::

## 5. Pattern cho WordPress / CRM legacy

```html
<!-- Vào theme footer.php hoặc plugin shortcode -->
<div id="zorio-phone"></div>

<script src="https://cdn.zorio.vn/webphone-sdk/v1/zorio-webphone.umd.cjs"></script>
<script>
(function () {
  // Lấy bearer token từ session backend của CRM
  fetch('/wp-json/my-app/v1/zorio-token', { credentials: 'include' })
    .then(r => r.json())
    .then(({ token }) => window.ZorioWebphoneSDK.ZorioWebphone.connect({
      apiBase: 'https://acme.zorio.example',
      token,
      mount:   '#zorio-phone',
      layout:  'docked',
      theme:   'auto',
    }))
    .then((phone) => { window.phone = phone })
    .catch(console.error)
})()
</script>
```

## 6. Tính năng v7 trong bundle UMD

Mọi bundle (UMD / ESM / npm) đều có cùng feature set:

- **Auto-reconnect supervisor** — tự re-register khi WSS drop / tab background.
- **Pagehide cleanup** — đóng tab tự `unregister` về Zorio PBX.
- **Early media** — outbound nghe ringback / IVR carrier từ 183 Session Progress.

::: tip Diagnostic preflight
Trước khi `connect()`, bạn có thể chạy preflight để kiểm tra HTTPS / Micro / WSS / STUN / TURN:

```js
const r = await window.ZorioWebphoneSDK.ZorioWebphone.diagnose({
  apiBase: 'https://acme.zorio.example',
  token,
})
if (!r.micOk)  alert('Vui lòng cấp quyền micro')
if (!r.wssOk)  alert('Firewall đang chặn WSS 443')
```
:::

## 7. Yêu cầu môi trường

- Trang phải chạy qua **HTTPS** (WebRTC mandate, ngoài `localhost`).
- Browser ≥ Chrome 90 / Edge 90 / Firefox 90 / Safari 14.
- User phải có một **gesture** (click/tap) trên trang trước khi cuộc gọi đầu tiên đến, để bypass autoplay policy của Safari/iOS — nếu không sẽ nhận event [`audio_autoplay_blocked`](/sdk/webphone/events#audio-autoplay-blocked).

Tham khảo thêm:

- [API methods](/sdk/webphone/api)
- [Events](/sdk/webphone/events)
- [Quickstart HTML](/sdk/webphone/quickstart)


---

# Câu hỏi thường gặp

<!-- source: https://docs.zorio.vn/tham-chieu/faq.md -->

# Câu hỏi thường gặp

Các câu hỏi tích hợp gặp nhiều nhất. Nếu chưa có ở đây, liên hệ team support Zorio.

## Xác thực & API Token

### Tôi mất token thì làm sao?

Token chỉ hiển thị 1 lần lúc tạo, không xem lại được. Vào Admin Console → API Tokens → **Revoke** token cũ → tạo token mới. Update token mới vào CRM của bạn.

### Token có thời hạn không?

Token cơ chế phiên user mặc định **không tự expire** — chỉ revoke thủ công bởi admin. Khuyến nghị **rotate 90 ngày 1 lần** theo chuẩn ngành. Bạn có thể tự rotate qua flow tạo token mới → update CRM → revoke token cũ.

### Tôi muốn dùng OAuth2 thay vì Bearer Token?

OAuth2 chưa hỗ trợ. Hiện tại chỉ Bearer Token (phiên user).

### Có sandbox để test trước khi tích hợp production?

Mỗi khách hàng được cấp 1 tài khoản riêng. Hãy dùng tài khoản đã được cấp để test — không có sandbox dùng chung.

## PBX

### Click-to-call không gọi được?

Check theo thứ tự:

1. Token có permission `pbx_api_access` không?
2. `from_extension` tồn tại + `status=active` trong tài khoản?
3. `to_phone` đúng format `^[0-9+]+$`?
4. Nếu truyền `trunk_id` — trunk có `status=active` không?
5. Nếu không truyền trunk — admin đã cấu hình outbound routing chưa?
6. Webhook receiver online không (để nhận event `ringing` / `answered` / `hangup`)?

### Tôi muốn click-to-call với caller ID riêng cho từng khách?

Truyền field `caller_id` trong body. Số phải thuộc danh sách caller-ids `active` của tài khoản — lấy qua `GET /api/pbx/caller-ids`.

### Recording URL hết hạn 30 phút — nếu khách cần tải sau?

Gọi lại `GET /api/pbx/cdr/{uuid}` để nhận signed URL mới (TTL 30' kể từ lúc request). URL cũ hết hạn, request mới sinh URL khác.

### Khi nào dùng `pbx.call.hangup` vs `pbx.cdr.created`?

- `pbx.call.hangup`: fire ngay realtime khi cuộc gọi kết thúc, **chưa có recording_url**.
- `pbx.cdr.created`: fire sau khi pipeline CDR xử lý xong, **có recording_url** + `result` phân loại chi tiết hơn.

CRM cần realtime → subscribe `pbx.call.hangup`. CRM cần data đầy đủ + recording → subscribe `pbx.cdr.created`.

### Filter webhook theo extension cụ thể?

Hiện chưa hỗ trợ. Webhook nhận TẤT CẢ event PBX của tài khoản. Bạn tự filter ở receiver side qua field `data.extension`.

## Telesales

### Một campaign có thể có bao nhiêu lead?

Không giới hạn cứng. Recommend ≤ **100.000 lead** per campaign để dashboard reports load mượt.

### Lead có duplicate được không?

Mặc định **không** — hệ thống dedupe theo `(campaign_id, phone)`. Nếu cần duplicate (vd cùng campaign nhưng khác chiến lược) — tạo 2 campaign riêng.

### Disposition có những trạng thái nào?

Có **bộ catalog mặc định** seed cho mỗi tài khoản mới (Đã hẹn / Không nghe / Bận / Từ chối / ...). Khách hàng có thể tự thêm disposition mới qua API hoặc Admin Console.

### Tôi cần webhook cho event "agent bấm điểm cuộc gọi"?

Subscribe `telesales.call.disposed` — fire ngay sau khi agent đặt outcome.

## AutoCall TTS

### Tier A vs Tier B chọn cái nào?

- **Tier A**: chất lượng giọng cao hơn, realtime (mỗi cuộc gọi render mới), tính phí theo ký tự. Phù hợp text động (vd nhắc số tiền cụ thể từng khách).
- **Tier B**: dùng audio library pre-rendered từ trước, không phí, throughput cao. Phù hợp text cố định hoặc volume lớn.

Khuyến nghị default `B` cho volume > 1000 cuộc/ngày.

### Voice nào support tiếng Việt?

Tier B đã có vi-VN-female-01 pre-rendered cho tiếng Việt. Tier A có nhiều voice hơn qua nhà cung cấp TTS cao cấp /  /  — list voices qua `GET /api/autocall/voices`.

### Khách bấm DTMF, tôi nhận thông tin ở đâu?

Subscribe `autocall.lead.dtmf_pressed` — fire mỗi khi khách bấm phím. Payload có `digit` + `lead_id` + `script_id`.

## Webhook

### Receiver tôi đôi khi không nhận event?

Check theo thứ tự:

1. Trong Admin Console → Webhook deliveries — có entry nào marked `failed` / `deadletter` không?
2. Receiver có verify HMAC đúng không (dùng RAW body, không phải JSON parsed)?
3. Receiver trả 200 trong < 5s không (mở metric trên server)?
4. URL có cert TLS valid không (test bằng `curl https://your-url/`)?

### Sự kiện đến nhiều lần — bug?

Không phải bug. Zorio retry khi receiver trả non-2xx hoặc timeout. Receiver PHẢI dedupe theo `X-Zorio-Delivery` (UUID).

### Tôi đổi URL webhook giữa chừng — event đang queue sẽ ra đâu?

Event trong queue (retry) gửi tới URL **mới** sau khi update. Event đã `deadletter` không tự retry — cần admin replay tay.

## Webphone SDK

### SDK chạy được trên browser nào?

Chrome 88+, Edge 88+, Firefox 78+, Safari 14+. KHÔNG support IE11.

### Tôi nhúng iframe nhưng không vào được — Mixed Content?

Trang chứa iframe PHẢI là HTTPS. Webphone iframe cũng phải HTTPS. Nếu trang HTTP nhúng iframe HTTPS — browser block vì security policy.

### Webphone mất register sau vài phút?

SDK v7+ có auto-reconnect + re-register supervisor. Nếu vẫn mất:

- Check `events` log có emit `auto_reconnect` không.
- Network có proxy block WebSocket (ws://)?
- TLS cert wildcard có valid không?

### Tôi muốn customize UI webphone?

Hiện SDK ship với UI vanilla DOM mặc định. Để customize:

- **Cấp 1**: override CSS qua `:root` variables.
- **Cấp 2**: dùng option `renderer: 'headless'` — SDK chỉ emit events, bạn tự render UI.

## Khác

### Có rate limit toàn portal không?

Có. Mặc định 60 req/min/token cho mọi endpoint, riêng `click-to-call` 10 req/min. Vượt → HTTP 429 với header `Retry-After`.

### API có version không?

Hiện chỉ 1 version `v1` (URL hiện tại). Khi có breaking change, sẽ thêm `/api/v2/...` song song. Roadmap thông báo trước ≥ 6 tháng.

### Có OpenAPI spec / Postman collection để import không?

OpenAPI spec đang chuẩn bị — sẽ phát hành tại `/openapi/` trong Phase 2.

### Tôi muốn deploy receiver ở Việt Nam — server Zorio ở đâu?

Server Zorio host tại Việt Nam (HCM + HN). Receiver deploy cùng vùng VN sẽ giảm latency webhook < 50ms.

### Báo bug / hỗ trợ tích hợp?

- Email: liên hệ admin để biết kênh hỗ trợ chính thức.
- Khi báo bug — luôn kèm `X-Request-Id` (nếu có) hoặc `call_uuid` + timestamp.


---

# Hangup cause codes

<!-- source: https://docs.zorio.vn/tham-chieu/hangup-codes.md -->

# Hangup cause codes

Mã `hangup_cause` xuất hiện trong response CDR + payload webhook (`pbx.call.hangup`, `pbx.cdr.created`). Mã theo chuẩn **Q.850** của ITU-T, được Zorio PBX mapping từ SIP response.

## Mã phổ biến nhất

| `hangup_cause` | Ý nghĩa | Tình huống thực tế |
|---|---|---|
| `NORMAL_CLEARING` | Cuộc gọi kết thúc bình thường | 1 trong 2 bên cúp máy chủ động sau khi nói chuyện xong |
| `NO_ANSWER` | Hết thời gian đổ chuông, không ai nhấc | Khách không nghe máy / không tới điện thoại |
| `USER_BUSY` | Số bị bận | Khách đang trong cuộc gọi khác |
| `CALL_REJECTED` | Số đích từ chối nhận cuộc | Khách bấm "từ chối" trên điện thoại |
| `ORIGINATOR_CANCEL` | Agent / hệ thống huỷ trước khi nhấc | Agent đổi ý cúp trong lúc đang đổ chuông |
| `RECOVERY_ON_TIMER_EXPIRE` | Cuộc gọi treo do timeout SIP | Mạng/PBX có vấn đề kỹ thuật |

## Mã liên quan tới định tuyến

| `hangup_cause` | Ý nghĩa |
|---|---|
| `UNALLOCATED_NUMBER` | Số không tồn tại trong mạng (vd 1XX, đầu số fake) |
| `NO_ROUTE_DESTINATION` | Không có route gọi tới đích (vd chưa cấu hình trunk) |
| `NO_ROUTE_TRANSIT_NET` | Trunk không nhận cuộc gọi |
| `DESTINATION_OUT_OF_ORDER` | Số đích offline |
| `INVALID_NUMBER_FORMAT` | Số sai format (vd thừa ký tự, sai prefix) |
| `FACILITY_REJECTED` | Telco từ chối route |

## Mã liên quan tới chất lượng cuộc gọi

| `hangup_cause` | Ý nghĩa |
|---|---|
| `MEDIA_TIMEOUT` | RTP packet ngừng đến trong N giây (mạng đứt) |
| `BEARERCAPABILITY_NOTAVAIL` | Codec không tương thích giữa 2 bên |
| `INCOMPATIBLE_DESTINATION` | Khác chuẩn (vd analog ↔ SIP không bridge được) |
| `EXCHANGE_ROUTING_ERROR` | Lỗi định tuyến của telco |

## Mã liên quan tới chính sách

| `hangup_cause` | Ý nghĩa |
|---|---|
| `CALL_REJECTED` | Bị reject cứng (vd DNC list, blacklist) |
| `INTERWORKING` | Không tương thích giao thức (vd ISDN ↔ SIP) |
| `BEARERCAPABILITY_NOTAUTH` | Không có quyền dùng dịch vụ này |
| `CHANNEL_UNACCEPTABLE` | Channel không sẵn sàng |

## Mã liên quan tới quá tải

| `hangup_cause` | Ý nghĩa |
|---|---|
| `NORMAL_TEMPORARY_FAILURE` | Lỗi tạm thời, thử lại sau |
| `SWITCH_CONGESTION` | Hệ thống quá tải, không xử lý được thêm |
| `REQUESTED_CHAN_UNAVAIL` | Hết channel rảnh ở trunk |
| `RESOURCE_UNAVAILABLE` | Hết tài nguyên (vd SBC) |

## Mã liên quan tới hệ thống nội bộ

| `hangup_cause` | Ý nghĩa |
|---|---|
| `LOSE_RACE` | Mất race khi 2 cuộc gọi cùng tới 1 số (chỉ 1 win) |
| `MANAGER_REQUEST` | Admin / supervisor cúp máy thủ công qua API |
| `SYSTEM_SHUTDOWN` | Hệ thống đang shutdown |
| `BLIND_TRANSFER` | Cuộc gọi bị chuyển blind sang số khác |
| `ATTENDED_TRANSFER` | Cuộc gọi bị chuyển attended sang số khác |
| `PICKED_OFF` | Cuộc gọi bị 1 ext khác bắt qua hàng đợi |

## Mapping sang trường `result`

Field `result` trong CDR phân loại đơn giản hơn để CRM dễ thống kê. Quy tắc map:

| Điều kiện | `result` |
|---|---|
| `hangup_cause = NORMAL_CLEARING` + `billsec > 0` | `answered` |
| `hangup_cause = NORMAL_CLEARING` + `billsec = 0` | `no_answer` (case đặc biệt: agent cúp ngay khi nhấc) |
| `hangup_cause = NO_ANSWER` | `no_answer` |
| `hangup_cause = USER_BUSY` | `busy` |
| `hangup_cause = CALL_REJECTED` | `rejected` |
| `hangup_cause = ORIGINATOR_CANCEL` | `cancelled` |
| Cuộc gọi tới hộp thư thoại | `voicemail` |
| Còn lại (lỗi mạng, định tuyến, hệ thống) | `failed` |

## Khi gặp `hangup_cause` lạ

Nếu bạn thấy mã không có trong bảng trên (vd `BIB_NA`, `XXX_ZZZ`), đó có thể là:

- Mã mở rộng của telco cụ thể (Viettel, Mobifone, ...).
- Lỗi hiếm gặp ở hạ tầng — báo team support Zorio kèm `call_uuid` để truy nguyên.

Tài liệu chi tiết Q.850: [ITU-T Q.850](https://www.itu.int/rec/T-REC-Q.850).


---

# HTTP status codes

<!-- source: https://docs.zorio.vn/tham-chieu/http-codes.md -->

# HTTP status codes

Tham chiếu đầy đủ HTTP status codes Zorio API trả về và cách CRM xử lý.

## 2xx — Thành công

| HTTP | Khi nào | Body |
|---|---|---|
| **200 OK** | Đa số request GET / PUT / DELETE thành công | `{ "data": {} }` hoặc list paginated |
| **201 Created** | POST tạo resource mới | `{ "data": { "id": ..., "..." } }` |
| **202 Accepted** | Action async đã enqueue (vd `click-to-call`, import lead) | `{ "data": { "call_uuid": "...", "status": "queued" } }` |

## 3xx — Redirect

| HTTP | Khi nào | Body |
|---|---|---|
| **302 Found** | `/api/pbx/cdr/{uuid}/recording` redirect tới signed URL | Empty body, header `Location: <signed URL>` |

## 4xx — Lỗi từ client

### 400 Bad Request

Request không hợp lệ ở mức HTTP (JSON malformed, missing required header, ...).

```json
{ "message": "Malformed request body" }
```

**Xử lý**: kiểm tra JSON đã đúng + header `Content-Type: application/json` đầy đủ.

### 401 Unauthorized

Token thiếu / sai / expired.

```json
{ "message": "Unauthenticated." }
```

**Xử lý**: redirect user đến trang login lấy token mới. KHÔNG hardcode token trong frontend.

### 403 Forbidden

Token hợp lệ nhưng thiếu permission.

```json
{ "message": "This action is unauthorized." }
```

**Xử lý**: ghi log + báo admin cấp thêm permission cho user (vd `pbx_api_access`, `telesales_api_access`).

### 404 Not Found

Resource không tồn tại trong dữ liệu của khách hàng.

```json
{ "message": "Resource not found" }
```

::: warning Bảo mật
Khi gửi token sai khách hàng (vd tài khoản A truy vấn data của tài khoản B) — Zorio cũng trả **404** thay vì 403 để **không leak existence** của resource. CRM không phân biệt được 2 case này.
:::

### 409 Conflict

State machine vi phạm hoặc unique constraint conflict.

```json
{ "message": "Extension đã tồn tại trong queue này." }
```

**Xử lý**: refresh state local + thông báo user.

### 422 Unprocessable Entity

Validation lỗi — body parse OK nhưng giá trị field không hợp lệ.

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "extension_number": ["Định dạng số máy nhánh không hợp lệ."],
    "outbound_caller_id": ["Giá trị đã chọn cho outbound caller id không hợp lệ."]
  }
}
```

**Xử lý**:
- Lặp qua `errors` object, hiển thị error message bên cạnh field tương ứng trên UI.
- Nếu là form submit — không refresh trang, giữ state cũ của user.

### 429 Too Many Requests

Vượt rate limit.

```json
{ "message": "Too many requests. Retry after 25 seconds." }
```

Header trả về:

```
Retry-After: 25
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782706011
```

**Xử lý**: backoff theo `Retry-After`. Triển khai exponential backoff + jitter để tránh thundering herd.

## 5xx — Lỗi từ server

### 500 Internal Server Error

Lỗi bất ngờ ở backend.

```json
{ "message": "Internal server error" }
```

**Xử lý**: retry với exponential backoff (3 lần, 1s / 4s / 16s). Nếu vẫn 500 → báo team support Zorio kèm `X-Request-Id` (nếu có) hoặc timestamp request.

### 502 Bad Gateway

Lỗi tầng dưới — phổ biến nhất:

- Click-to-call: Zorio PBX không tiếp nhận originate (có thể PBX restart).

```json
{ "message": "PBX không tiếp nhận originate cuộc gọi. Vui lòng thử lại." }
```

**Xử lý**: retry sau vài giây. Nếu vẫn 502 → escalate.

### 503 Service Unavailable

Hệ thống đang bảo trì hoặc quá tải tạm thời.

```json
{ "message": "Service temporarily unavailable" }
```

Header `Retry-After: <giây>` cho biết thời gian gợi ý retry.

### 504 Gateway Timeout

Upstream timeout. Hiếm gặp.

## Best practice

### Always handle 4xx + 5xx

Mọi API call PHẢI có error handler. KHÔNG assume "200 OK by default".

### Phân biệt retry-able vs non-retry-able

| Status | Retry? | Lý do |
|---|---|---|
| 4xx (trừ 408, 429) | Không | Lỗi do client — retry không đổi kết quả |
| 408 Request Timeout | Có (1-3 lần) | Có thể do network |
| 429 Too Many Requests | Có (sau `Retry-After`) | Backoff theo header |
| 500, 502, 503, 504 | Có (exponential backoff) | Server lỗi tạm thời |

### Trace request

Header response: `X-Request-Id: <uuid>` — copy vào ticket support khi báo lỗi, team Zorio dùng để trace nguyên nhân nhanh.

### Network error vs HTTP error

Network error (DNS fail, connection refused, TLS error) KHÔNG phải HTTP status code — không có body. Cần catch riêng:

```js
try {
  const res = await fetch(url, opts);
  if (!res.ok) {
    // HTTP error 4xx / 5xx
  }
} catch (err) {
  // Network error
}
```


---

# Thuật ngữ

<!-- source: https://docs.zorio.vn/tham-chieu/thuat-ngu.md -->

# Thuật ngữ

Glossary tổng hợp khái niệm Zorio xuyên suốt các module API.

## Tài khoản & truy cập

| Thuật ngữ | Giải thích |
|---|---|
| **Tài khoản (account)** | Mỗi khách hàng Zorio có hệ thống độc lập với dữ liệu riêng, tên miền truy cập riêng, API token riêng |
| **API Token** | Bearer Token (phiên user) cấp riêng cho user, dùng trong header `Authorization: Bearer <token>` |
| **Permission** | Quyền cụ thể trên 1 hành động (vd `pbx_api_access`, `manage_caller_ids`) |
| **Role** | Nhóm permission gắn cho user (`admin`, `supervisor`, `agent`, `read_only`) |
| **Permission tier** | Mức truy cập module (`viewer`, `operator`, `admin`) |

## PBX

| Thuật ngữ | Giải thích |
|---|---|
| **Extension** | Máy nhánh SIP nội bộ, đăng ký lên Zorio PBX bằng `extension_number` + `sip_password` |
| **Trunk** | Đường gọi ra ngoài qua telco / SBC / nhà cung cấp SIP trunking |
| **Caller ID** | Số hiển thị khi gọi ra |
| **CDR (Call Detail Record)** | Bản ghi 1 cuộc gọi với metadata đầy đủ |
| **Hangup cause** | Mã chuẩn Q.850 chỉ lý do cuộc gọi kết thúc — xem [Hangup codes](/tham-chieu/hangup-codes) |
| **Queue** | Hàng đợi cuộc gọi, agents trả lời theo strategy (round-robin, longest-idle, ...) |
| **Tier** | Cấp ưu tiên agent trong queue (`tier_level` 1-9 + `tier_position`) |
| **A-leg / B-leg** | Pattern click-to-call: A-leg gọi agent, B-leg gọi khách, bridge khi cả 2 nhấc |
| **SIP registration** | Trạng thái softphone đăng ký lên PBX (`registered`, `unregistered`, `unknown`) |
| **TLS / SIPS** | SIP qua TLS encryption (port 5061) thay vì UDP plain (5060) |
| **WebRTC** | Giao thức gọi qua web browser, dùng cho Webphone SDK |

## Telesales / Contact Center

| Thuật ngữ | Giải thích |
|---|---|
| **Campaign** | Chiến dịch gọi ra với danh sách lead, script, agent, caller-ID group |
| **Lead** | Khách hàng tiềm năng — số điện thoại + custom fields theo ngành |
| **Disposition / Outcome** | Kết quả cuộc gọi do agent đánh dấu (vd "Đã hẹn callback", "Không quan tâm", "Mua hàng") |
| **Dialer mode** | Cách dialer gọi: `manual` (agent click), `preview` (xem lead trước khi gọi), `progressive` (auto dial khi agent rảnh), `predictive` (overdial dự đoán) |
| **Caller-ID rotation** | Xoay vòng nhiều caller-ID để tránh telco flag spam — 6 strategy (`round_robin`, `least_used`, `cap_based`, `weighted`, `sticky_lead`, `random`) |
| **DNC (Do Not Call)** | Danh sách số bị chặn không gọi (compliance PDPL) |
| **Recording** | File ghi âm `.wav` của cuộc gọi, tải qua signed URL TTL 30 phút |
| **Wrap-up time** | Thời gian sau khi cúp để agent điền disposition (vd 5 giây) |
| **ASR (Answer-Seizure Ratio)** | Tỷ lệ cuộc gọi được nhấc / tổng cuộc gọi đi (đo chất lượng số) |
| **ACD (Average Call Duration)** | Thời lượng trung bình của cuộc gọi đã nhấc |
| **Abandon rate** | Tỷ lệ khách nhấc nhưng không kịp nối với agent (rớt trong queue) |

## AutoCall TTS

| Thuật ngữ | Giải thích |
|---|---|
| **TTS (Text-to-Speech)** | Tổng hợp giọng nói từ văn bản |
| **Voice** | Giọng đọc cụ thể (vd "vi-VN-female-01", "Linh Đan") |
| **Tier A** | Premium realtime TTS qua provider (nhà cung cấp TTS cao cấp) — tính phí theo ký tự |
| **Tier B** | Local TTS dùng audio library pre-rendered — không phí, throughput cao |
| **Script** | Kịch bản TTS với biến `{{placeholder}}` thay thế runtime |
| **DTMF** | Tone bấm số trên điện thoại (0-9, *, #) |
| **DTMF action** | Hành động khi khách bấm phím: `playback`, `playback_then_hangup`, `switch_script`, `queue`, `repeat_script`, `hangup` |
| **Variable** | Biến do khách hàng định nghĩa, gắn vào script (vd `customer_name`, `appointment_date`) |
| **Media file** | File audio upload sẵn để playback (không qua TTS) |

## Webphone SDK

| Thuật ngữ | Giải thích |
|---|---|
| **SDK (Software Development Kit)** | Bộ thư viện cài vào ứng dụng để dùng tính năng webphone |
| **UMD** | Universal Module Definition — format bundle chạy được trong cả browser + Node.js qua `<script>` tag |
| **npm tarball** | Package `.tgz` cài qua `npm install ./file.tgz` cho môi trường airgap |
| **iframe SSO** | Nhúng webphone trong iframe + exchange SSO token để khách không cần đăng nhập lại |
| **postMessage** | API browser truyền message giữa parent ↔ iframe |
| **SIP.js** | Thư viện SIP-over-WebSocket dùng làm core của SDK (`sip.js@0.21.x`) |
| **Early media** | Audio (ringback / IVR announcement) phát TRƯỚC khi callee accept |
| **Auto-reconnect** | SDK tự reconnect khi mạng đứt với exponential backoff |
| **Pagehide cleanup** | SDK tự unregister khi user đóng tab → tránh stale registration ở PBX |

## Webhook

| Thuật ngữ | Giải thích |
|---|---|
| **Webhook** | URL HTTPS Zorio POST event tới CRM/app khách realtime |
| **HMAC** | Hash-based Message Authentication Code — verify signature payload bằng secret |
| **Idempotency** | Property: gọi 1 lần hay nhiều lần kết quả như nhau |
| **Replay attack** | Kẻ tấn công bắt 1 request hợp lệ rồi gửi lại nhiều lần — chống bằng timestamp window |
| **Deadletter** | Event không deliver được sau N lần retry — lưu trong audit log để admin replay tay |

## HTTP / API

| Thuật ngữ | Giải thích |
|---|---|
| **REST** | REpresentational State Transfer — chuẩn API qua HTTP |
| **Bearer Token** | Token gắn trong header `Authorization: Bearer <token>` |
| **Bearer (phiên user)** | Cơ chế xác thực Zorio dùng — cấp token gắn với phiên đăng nhập user |
| **Pagination** | Chia kết quả thành nhiều trang qua `?page=N&per_page=M` |
| **Soft delete** | Đánh dấu `deleted_at` thay vì xoá row — có thể restore |
| **Rate limit** | Giới hạn số request/khoảng thời gian, vượt → HTTP 429 |
| **ISO 8601** | Chuẩn datetime `2026-06-30T03:30:45+00:00` |
| **E.164** | Chuẩn số điện thoại quốc tế `+84xxxxxxxxx` |
| **UUID** | Universally Unique Identifier 36 ký tự (vd `65569ce0-0183-4f61-a3b2-0e433cfa4031`) |

## Telco Việt Nam

| Thuật ngữ | Giải thích |
|---|---|
| **Carrier** | Nhà mạng: Viettel, Mobifone, Vinaphone, Vietnamobile |
| **CLI type** | Loại số: `mobile` (di động), `fixed_02x` (cố định), `hotline_1900` / `hotline_1800` (đầu số dịch vụ), `brandname` (tên thương hiệu) |
| **PDPL** | Personal Data Protection Law — luật bảo vệ dữ liệu cá nhân VN |
| **DNC list** | Danh sách số không được gọi (compliance PDPL) |


---

# Đăng ký webhook

<!-- source: https://docs.zorio.vn/webhooks/dang-ky.md -->

# Đăng ký webhook

Webhook là kênh để hệ thống Zorio **chủ động đẩy sự kiện** (cuộc gọi, lead, CDR, ...) sang URL của bạn realtime — thay vì bạn phải poll API liên tục.

## Cách đăng ký

::: warning Không tự đăng ký qua API
Vì lý do bảo mật + audit (chống abuse token để redirect webhook ra URL ngoài), đăng ký webhook **chỉ làm qua giao diện Admin Console**, KHÔNG có API CRUD công khai.
:::

### Quy trình 5 bước

1. **Đăng nhập Admin Console** với tài khoản admin.
2. Vào **Cài đặt → Tích hợp → Webhooks** (`Admin Console`).
3. Bấm **Tạo webhook**, điền:
   - **URL** — endpoint HTTPS nhận event (do bạn deploy).
   - **Events** — chọn danh sách event quan tâm (vd `pbx.call.hangup`, `telesales.lead.updated`).
   - **Tên hiển thị** — để phân biệt khi có nhiều webhook.
4. Hệ thống tự sinh **secret** (32 ký tự alphanumeric) — **copy ngay, không xem lại được**.
5. Deploy receiver xác minh HMAC (xem [Ký HMAC-SHA256](/webhooks/hmac)) và xử lý event.

## Các event hỗ trợ

### PBX (xem chi tiết [PBX Webhooks](/api/pbx/webhooks))

| Event | Khi nào fire |
|---|---|
| `pbx.call.ringing` | Cuộc gọi vào ext, ext đang đổ chuông |
| `pbx.call.answered` | Ext đã nhấc máy |
| `pbx.call.hangup` | Cuộc gọi kết thúc — realtime từ ESL |
| `pbx.cdr.created` | Pipeline CDR đã insert row đầy đủ + recording_url |

### Telesales (xem chi tiết [Telesales](/api/telesales/))

| Event | Khi nào fire |
|---|---|
| `telesales.lead.created` | Lead mới được insert/import |
| `telesales.lead.updated` | Disposition / custom field thay đổi |
| `telesales.call.disposed` | Agent đặt outcome cho cuộc gọi |
| `telesales.campaign.completed` | Toàn bộ lead trong campaign đã được dial |

### AutoCall (xem chi tiết [AutoCall Webhooks](/api/autocall/webhooks))

| Event | Khi nào fire |
|---|---|
| `autocall.campaign.started` / `paused` / `resumed` / `finished` | Lifecycle campaign |
| `autocall.lead.dialed` / `answered` / `dtmf_pressed` / `transferred` | Lifecycle 1 cuộc gọi |

## URL receiver phải đáp ứng

- **HTTPS bắt buộc** (không nhận HTTP plain).
- Trả về **HTTP 2xx trong vòng 5 giây** — quá thời gian Zorio coi như fail và retry.
- **Idempotent** theo header `X-Zorio-Delivery` (UUID) — Zorio có thể retry cùng 1 event nếu lần trước fail.
- Verify HMAC trước khi xử lý — xem [Ký HMAC-SHA256](/webhooks/hmac).

## Test webhook

Trong Admin Console có nút **Send test event** — gửi payload mẫu để bạn debug receiver mà không cần chờ event thật.

## Xoay secret

Nếu nghi ngờ secret bị lộ:

1. Vào Admin Console → mục webhook → **Xoay secret**.
2. Hệ thống sinh secret mới — copy + update vào receiver.
3. Secret cũ **disable ngay lập tức** — event tiếp theo sẽ ký bằng secret mới.

## Tạm dừng / Xoá webhook

- **Tạm dừng**: webhook giữ cấu hình, không gửi event. Phù hợp khi receiver đang bảo trì.
- **Xoá**: vĩnh viễn, history giữ trong audit log nhưng không thể restore.

## Xem nhật ký delivery

Mỗi event gửi đi có **delivery record** lưu trong 30 ngày:

- Endpoint, event, timestamp, status code receiver trả về.
- Payload đầy đủ + response body.
- Số lần retry.

Truy cập tại Admin Console → **Webhook deliveries**.


---

# Ký HMAC-SHA256

<!-- source: https://docs.zorio.vn/webhooks/hmac.md -->

# Ký HMAC-SHA256

Mọi webhook Zorio gửi đến receiver của bạn đều được **ký HMAC-SHA256** với secret bạn lưu lúc tạo webhook. Mục đích:

- **Xác thực** event đến từ Zorio (không phải kẻ giả mạo).
- **Toàn vẹn** payload (không bị sửa giữa đường).
- **Chống replay attack** qua timestamp window.

## Headers Zorio gửi

| Header | Mô tả |
|---|---|
| `X-Zorio-Event` | Tên event, vd `pbx.call.hangup` |
| `X-Zorio-Timestamp` | Epoch giây UTC lúc Zorio publish event |
| `X-Zorio-Delivery` | UUID duy nhất cho mỗi lần delivery (kể cả retry) — dùng cho dedupe |
| `X-Zorio-Signature` | `sha256=<hex>` HMAC-SHA256 của raw body với secret |
| `Content-Type` | `application/json; charset=utf-8` |

## Cách Zorio tính signature

```
signature = "sha256=" + lowercase(hex(HMAC-SHA256(secret, raw_body)))
```

- `secret`: 32 ký tự alphanumeric do hệ thống sinh khi tạo webhook.
- `raw_body`: bytes nguyên văn body request — KHÔNG parse JSON trước khi tính.

## Cách receiver verify

### Bước 1 — Reject timestamp quá cũ

So sánh `X-Zorio-Timestamp` với thời gian hiện tại. Nếu lệch quá **300 giây (5 phút)** → reject 400.

Lý do: chống replay attack (kẻ tấn công bắt được 1 request hợp lệ rồi gửi lại nhiều lần).

### Bước 2 — Tính lại signature

```
expected = "sha256=" + lowercase(hex(HMAC-SHA256(secret, raw_body)))
```

### Bước 3 — So sánh constant-time

So sánh `expected` với `X-Zorio-Signature` bằng hàm **constant-time** (`crypto.timingSafeEqual` ở Node.js, `hmac.compare_digest` ở Python, `hash_equals` ở PHP).

::: warning KHÔNG dùng `==` để so chuỗi
So `==` thông thường có thể leak signature từng byte qua **timing attack**. Luôn dùng API timing-safe của ngôn ngữ.
:::

### Bước 4 — Dedupe theo `X-Zorio-Delivery`

Lưu `X-Zorio-Delivery` UUID đã xử lý vào Redis/DB với TTL 24h. Nếu UUID đã thấy → trả 200 ngay (không xử lý lại).

## Mẫu Node.js (Express)

```js
const crypto = require('crypto');
const express = require('express');
const app = express();

const SECRET = process.env.ZORIO_WEBHOOK_SECRET;

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = parseInt(req.headers['x-zorio-timestamp'], 10);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) {
    return res.status(400).send('Stale timestamp');
  }

  const sig = req.headers['x-zorio-signature'] || '';
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');

  if (sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  console.log('Verified event:', event.event, event.data);
  res.status(200).send('OK');
});

app.listen(3000);
```

Xem thêm mẫu Python, PHP, Go ở [Mẫu receiver](/webhooks/receiver-mau).

## Lỗi thường gặp

### Lỗi: signature không khớp dù secret đúng

Nguyên nhân phổ biến:

- **Parse JSON trước khi tính HMAC** — bạn phải dùng RAW body, không phải object đã parse. Ở Express dùng `express.raw()`. Ở hệ thống dùng `$request->getContent()`. Ở Flask dùng `request.get_data()`.
- **Charset encoding** — phải UTF-8 bytes thuần, không encode lại.
- **Body bị middleware modify** — vd nginx/CDN nén lại gzip rồi giải nén → bytes khác. Cần config skip body modification cho route webhook.
- **Trim whitespace** — KHÔNG trim, byte cuối có thể là `}` không có newline.

### Lỗi: timestamp luôn lệch

- Đồng hồ server của bạn lệch — chạy `ntpd` / `chronyd` đồng bộ NTP.
- Receiver chạy trong container không sync clock với host — đảm bảo container dùng đúng timezone.

## Tài liệu liên quan

- [Đăng ký webhook](/webhooks/dang-ky)
- [Retry policy](/webhooks/retry)
- [Mẫu receiver](/webhooks/receiver-mau)


---

# Mẫu receiver

<!-- source: https://docs.zorio.vn/webhooks/receiver-mau.md -->

# Mẫu receiver

Code mẫu deploy receiver verify HMAC + dedupe + xử lý event Zorio. Copy-paste làm điểm khởi đầu, customize phần "Xử lý event" theo nghiệp vụ của bạn.

## Node.js (Express)

```js
const crypto = require('crypto');
const express = require('express');
const Redis = require('ioredis');

const SECRET = process.env.ZORIO_WEBHOOK_SECRET;
const redis = new Redis(process.env.REDIS_URL);
const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const ts = parseInt(req.headers['x-zorio-timestamp'], 10);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) {
    return res.status(400).send('Stale timestamp');
  }

  const sig = req.headers['x-zorio-signature'] || '';
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');

  if (sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const deliveryId = req.headers['x-zorio-delivery'];
  const seen = await redis.set(`zorio:delivery:${deliveryId}`, '1', 'NX', 'EX', 86400);
  if (seen === null) {
    return res.status(200).send('Duplicate');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  res.status(200).send('OK');

  await handleEvent(event).catch((err) => {
    console.error('Process error:', err);
  });
});

async function handleEvent(event) {
  switch (event.event) {
    case 'pbx.call.hangup':
      console.log('Call ended:', event.data.call_uuid, event.data.hangup_cause);
      break;
    case 'telesales.lead.updated':
      console.log('Lead updated:', event.data.id);
      break;
  }
}

app.listen(3000, () => console.log('Receiver on :3000'));
```

## PHP (hệ thống)

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Redis;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        $secret = env('ZORIO_WEBHOOK_SECRET');

        $ts = (int) $request->header('X-Zorio-Timestamp');
        if (!$ts || abs(time() - $ts) > 300) {
            return response('Stale timestamp', 400);
        }

        $raw = $request->getContent();
        $signature = $request->header('X-Zorio-Signature', '');
        $expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);

        if (!hash_equals($expected, $signature)) {
            return response('Invalid signature', 401);
        }

        $deliveryId = $request->header('X-Zorio-Delivery');
        $key = "zorio:delivery:{$deliveryId}";
        $isNew = Redis::set($key, '1', 'NX', 'EX', 86400);
        if (!$isNew) {
            return response('Duplicate', 200);
        }

        $event = json_decode($raw, true);

        dispatch(function () use ($event) {
            $this->processEvent($event);
        })->afterResponse();

        return response('OK', 200);
    }

    protected function processEvent(array $event): void
    {
        match ($event['event']) {
            'pbx.call.hangup' => logger()->info('Call ended', $event['data']),
            'telesales.lead.updated' => logger()->info('Lead updated', $event['data']),
            default => null,
        };
    }
}
```

Đăng ký route ở `routes/api.php`:

```php
Route::post('/webhook', [WebhookController::class, 'handle']);
```

## Python (FastAPI)

```python
import hmac
import hashlib
import os
import time
import json
import redis.asyncio as redis
from fastapi import FastAPI, Request, HTTPException, BackgroundTasks

SECRET = os.environ["ZORIO_WEBHOOK_SECRET"].encode()
redis_client = redis.from_url(os.environ["REDIS_URL"])
app = FastAPI()


@app.post("/webhook")
async def webhook(request: Request, bg: BackgroundTasks):
    ts = int(request.headers.get("x-zorio-timestamp", "0"))
    if not ts or abs(time.time() - ts) > 300:
        raise HTTPException(400, "Stale timestamp")

    raw = await request.body()
    signature = request.headers.get("x-zorio-signature", "")
    expected = "sha256=" + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise HTTPException(401, "Invalid signature")

    delivery_id = request.headers.get("x-zorio-delivery")
    is_new = await redis_client.set(
        f"zorio:delivery:{delivery_id}", "1", nx=True, ex=86400
    )
    if not is_new:
        return {"status": "duplicate"}

    event = json.loads(raw)
    bg.add_task(process_event, event)
    return {"status": "ok"}


async def process_event(event: dict) -> None:
    match event["event"]:
        case "pbx.call.hangup":
            print(f"Call ended: {event['data']['call_uuid']}")
        case "telesales.lead.updated":
            print(f"Lead updated: {event['data']['id']}")
```

## Go (net/http)

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"strconv"
	"time"
)

var secret = []byte(os.Getenv("ZORIO_WEBHOOK_SECRET"))

func handler(w http.ResponseWriter, r *http.Request) {
	ts, _ := strconv.ParseInt(r.Header.Get("X-Zorio-Timestamp"), 10, 64)
	if ts == 0 || abs(time.Now().Unix()-ts) > 300 {
		http.Error(w, "Stale timestamp", 400)
		return
	}

	raw, _ := io.ReadAll(r.Body)
	sig := r.Header.Get("X-Zorio-Signature")
	mac := hmac.New(sha256.New, secret)
	mac.Write(raw)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(sig), []byte(expected)) {
		http.Error(w, "Invalid signature", 401)
		return
	}

	w.WriteHeader(200)
	w.Write([]byte("OK"))

	var event struct {
		Event string                 `json:"event"`
		Data  map[string]interface{} `json:"data"`
	}
	if err := json.Unmarshal(raw, &event); err == nil {
		go processEvent(event.Event, event.Data)
	}
}

func processEvent(name string, data map[string]interface{}) {
	log.Printf("event=%s data=%+v", name, data)
}

func abs(x int64) int64 { if x < 0 { return -x }; return x }

func main() {
	http.HandleFunc("/webhook", handler)
	log.Fatal(http.ListenAndServe(":3000", nil))
}
```

## Checklist trước khi go-live

- [ ] HTTPS (TLS valid, không self-signed).
- [ ] Verify HMAC + timestamp ở mọi request.
- [ ] Dedupe theo `X-Zorio-Delivery`.
- [ ] Xử lý event async, trả 200 nhanh trong < 5s.
- [ ] Log đầy đủ payload + delivery_id để debug.
- [ ] Test bằng nút **Send test event** ở Admin Console.
- [ ] Stress test ≥ 200 req/s nếu volume lớn.

## Tài liệu liên quan

- [Đăng ký webhook](/webhooks/dang-ky)
- [Ký HMAC-SHA256](/webhooks/hmac)
- [Retry policy](/webhooks/retry)


---

# Retry policy

<!-- source: https://docs.zorio.vn/webhooks/retry.md -->

# Retry policy

Khi Zorio đẩy webhook đến receiver mà bị **fail** (timeout / non-2xx / network error), hệ thống sẽ **retry tự động** theo lịch tăng dần.

## Định nghĩa fail

Receiver được coi là fail nếu:

- **Timeout** sau **5 giây** không trả response.
- Trả về HTTP status **không phải 2xx** (vd 500, 502, 503, 4xx).
- Connection error (DNS fail, TLS handshake fail, ...).

::: tip Receiver xử lý lâu?
Bạn nên trả **HTTP 200 ngay khi nhận** (sau khi verify HMAC), rồi xử lý event async qua queue nội bộ. Không xử lý đồng bộ với Zorio — sẽ bị retry chồng.
:::

## Lịch retry

| Lần | Sau bao lâu kể từ lần trước | Cumulative |
|---|---|---|
| 1 (lần đầu) | — | 0s |
| 2 | 30 giây | 30s |
| 3 | 5 phút | 5m 30s |
| 4 (lần cuối) | 30 phút | 35m 30s |

Sau lần 4 fail → event chuyển trạng thái **`deadletter`** trong audit log.

## Deadletter

Khi event vào `deadletter`:

- Lưu trong bảng nhật ký phân phối webhook 30 ngày.
- Admin có thể vào **Admin Console → Webhook deliveries** xem chi tiết: payload, lý do fail, response của receiver.
- **KHÔNG retry tự động** sau khi đã deadletter — cần fix bug ở receiver rồi:
  - Hoặc bấm **Replay** trên từng delivery để gửi lại.
  - Hoặc đăng ký lại webhook để event mới tiếp tục.

## Đảm bảo idempotency ở receiver

Vì Zorio có thể retry, receiver PHẢI idempotent — xử lý cùng 1 event nhiều lần không gây hậu quả lệch (vd không tạo 2 bản ghi cùng UUID, không trừ tiền 2 lần).

### Cách triển khai

Mỗi delivery có header `X-Zorio-Delivery: <UUID>`. Receiver lưu UUID vào Redis với TTL 24h:

```js
const seen = await redis.set(`zorio:delivery:${deliveryId}`, '1',
                              'NX', 'EX', 86400);
if (seen === null) {
  // Đã xử lý rồi → trả 200 và bỏ qua
  return res.status(200).send('Duplicate');
}
// Xử lý event...
```

Kết quả: dù Zorio retry bao nhiêu lần, business logic chỉ chạy 1 lần.

## Tốc độ + concurrency

- Zorio gửi event **song song** lên đến **20 connection đồng thời** per receiver URL.
- Trong burst (vd khi import 10.000 lead), receiver có thể nhận ~200-500 req/s. Hãy chuẩn bị throughput tương ứng.
- Nếu receiver không scale kịp → trả **HTTP 503** với header `Retry-After: <giây>`. Zorio sẽ tôn trọng header này (delay lần retry kế tiếp ≥ giá trị bạn nêu).

## Khi nào webhook tự ngưng (suspended)?

Nếu webhook URL bị fail **liên tục 50 event** không có bất kỳ event nào thành công → hệ thống **auto-suspend** webhook để tránh waste resources.

- Admin sẽ nhận notification trong Admin Console.
- Cần kích hoạt lại tay sau khi fix receiver.

## Tài liệu liên quan

- [Đăng ký webhook](/webhooks/dang-ky)
- [Ký HMAC-SHA256](/webhooks/hmac)
- [Mẫu receiver](/webhooks/receiver-mau)