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

Tài liệu chính thức tích hợp REST API + Webphone SDK của hệ thống Zorio Contact Center.
Truy cập raw markdown bằng cách thêm `.md` vào URL bất kỳ (vd `/api/pbx/extensions.md`).

Toàn bộ tài liệu dạng 1 file: https://docs.zorio.vn/llms-full.txt

## Tiếng Việt

- [Campaigns](https://docs.zorio.vn/api/autocall/campaigns.md) — Quản lý chiến dịch AutoCall — CRUD + lifecycle controls (launch / pause / resume / archive / unarchive) + thống kê.
- [AutoCall TTS API — Tổng quan](https://docs.zorio.vn/api/autocall/index.md) — Public REST API cho Module AutoCall TTS — tự động hoá outbound với giọng đọc tự nhiên + DTMF actions + voices library.
- [Leads + Variables](https://docs.zorio.vn/api/autocall/leads.md) — 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 templatetext.
- [Reports](https://docs.zorio.vn/api/autocall/reports.md) — Các endpoint báo cáo cho campaign AutoCall — KPIs, trend, comparison, hangup analysis, heatmap, DTMF analytics, funnel + export Excel.
- [Scripts + DTMF actions](https://docs.zorio.vn/api/autocall/scripts.md) — 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.
- [Voices + Media files](https://docs.zorio.vn/api/autocall/voices.md) — Hai nhóm tài nguyên dùng chung trong AutoCall:
- [Webhook events AutoCall](https://docs.zorio.vn/api/autocall/webhooks.md) — Khi cuộc gọi xảy ra - Zorio POST event tới URL khách hàng đăng ký (HMAC signed).
- [Lịch sử cuộc gọi (CDR)](https://docs.zorio.vn/api/pbx/cdr.md) — Truy vấn CDR theo nhiều điều kiện + tải ghi âm signed URL.
- [Click-to-Call](https://docs.zorio.vn/api/pbx/click-to-call.md) — 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.
- [Máy nhánh (Extensions)](https://docs.zorio.vn/api/pbx/extensions.md) — 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.
- [PBX API — Tổng quan](https://docs.zorio.vn/api/pbx/index.md) — 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.
- [Hàng đợi (Queue)](https://docs.zorio.vn/api/pbx/queue.md) — Quản lý hàng đợi của Zorio PBX: CRUD queue, thêm/sửa/xoá tier agent.
- [Webhook events PBX](https://docs.zorio.vn/api/pbx/webhooks.md) — Mọi event đều có cấu trúc envelope:
- [Caller-ID rotation groups](https://docs.zorio.vn/api/telesales/caller-id-groups.md) — | 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 | ...
- [Chiến dịch (Campaigns)](https://docs.zorio.vn/api/telesales/campaigns.md) — 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 / stat...
- [DNC list](https://docs.zorio.vn/api/telesales/dnc.md) — 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.
- [Telesales API — Tổng quan](https://docs.zorio.vn/api/telesales/index.md) — 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.
- [Khách hàng tiềm năng (Leads)](https://docs.zorio.vn/api/telesales/leads.md) — 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.
- [Recording](https://docs.zorio.vn/api/telesales/recording.md) — 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.
- [Báo cáo (Reports)](https://docs.zorio.vn/api/telesales/reports.md) — 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.
- [Script + Outcome](https://docs.zorio.vn/api/telesales/scripts.md) — 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.
- [API Token (machine-to-machine)](https://docs.zorio.vn/auth/api-token.md) — 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.
- [Rate limit + Idempotency](https://docs.zorio.vn/auth/rate-limit.md) — Hai cơ chế Zorio dùng để bảo vệ API + giúp CRM xử lý retry an toàn.
- [Bearer (phiên user) (user session)](https://docs.zorio.vn/auth/sanctum-bearer.md) — 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).
- [Ký webhook HMAC-SHA256](https://docs.zorio.vn/auth/webhook-hmac.md) — Webhook nội dung sâu hơn và sample code đầy đủ ở Webhooks chung → Ký HMAC-SHA256. Trang này tóm tắt nhanh để CRM kỹ thuật onboarding mới hiểu cơ chế ký + verify.
- [Giới thiệu](https://docs.zorio.vn/bat-dau/gioi-thieu.md) — Zorio là nền tảng Contact Center cho doanh nghiệp gồm:
- [Khái niệm cơ bản](https://docs.zorio.vn/bat-dau/khai-niem.md) — Mỗi khách hàng Zorio có hệ thống riêng biệt với:
- [Quy ước chung](https://docs.zorio.vn/bat-dau/quy-uoc.md) — | 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 |
- [Lấy API Token](https://docs.zorio.vn/bat-dau/xin-token.md) — 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.
- [API methods](https://docs.zorio.vn/sdk/webphone/api.md) — 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 incomingcall).
- [Events](https://docs.zorio.vn/sdk/webphone/events.md) — 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?).
- [Nhúng qua iframe (SSO)](https://docs.zorio.vn/sdk/webphone/iframe.md) — 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 ...
- [Webphone SDK — Tổng quan](https://docs.zorio.vn/sdk/webphone/index.md) — 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).
- [Nhúng qua npm](https://docs.zorio.vn/sdk/webphone/npm.md) — 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.
- [Quickstart HTML](https://docs.zorio.vn/sdk/webphone/quickstart.md) — 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.
- [Nhúng qua UMD/CDN](https://docs.zorio.vn/sdk/webphone/umd.md) — 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.
- [Câu hỏi thường gặp](https://docs.zorio.vn/tham-chieu/faq.md) — 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.
- [Hangup cause codes](https://docs.zorio.vn/tham-chieu/hangup-codes.md) — Mã hangupcause 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.
- [HTTP status codes](https://docs.zorio.vn/tham-chieu/http-codes.md) — Tham chiếu đầy đủ HTTP status codes Zorio API trả về và cách CRM xử lý.
- [Thuật ngữ](https://docs.zorio.vn/tham-chieu/thuat-ngu.md) — Glossary tổng hợp khái niệm Zorio xuyên suốt các module API.
- [Đăng ký webhook](https://docs.zorio.vn/webhooks/dang-ky.md) — 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.
- [Ký HMAC-SHA256](https://docs.zorio.vn/webhooks/hmac.md) — 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:
- [Mẫu receiver](https://docs.zorio.vn/webhooks/receiver-mau.md) — 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.
- [Retry policy](https://docs.zorio.vn/webhooks/retry.md) — 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.

## English

- [Campaigns](https://docs.zorio.vn/en/api/autocall/campaigns.md) — Manage AutoCall campaigns — CRUD + lifecycle controls (launch / pause / resume / archive / unarchive) + statistics.
- [AutoCall TTS API — Overview](https://docs.zorio.vn/en/api/autocall/index.md) — Public REST API for the AutoCall TTS module — automated outbound calling with natural-sounding TTS voices + DTMF actions + voices library.
- [Leads + Variables](https://docs.zorio.vn/en/api/autocall/leads.md) — Manage leads (bulk import, list, blacklist/DNC) and customer-defined TTS variables used in the templatetext.
- [Reports](https://docs.zorio.vn/en/api/autocall/reports.md) — Reporting endpoints for AutoCall campaigns — KPIs, trend, comparison, hangup analysis, heatmap, DTMF analytics, funnel, and Excel export.
- [Scripts + DTMF actions](https://docs.zorio.vn/en/api/autocall/scripts.md) — Manage TTS scripts (template + voice + DTMF actions) for AutoCall. Includes script CRUD, the DTMF action types enum, a queue helper list, and TTS preview.
- [Voices + Media files](https://docs.zorio.vn/en/api/autocall/voices.md) — Two shared resource groups used in AutoCall:
- [AutoCall Webhook Events](https://docs.zorio.vn/en/api/autocall/webhooks.md) — When a call occurs, Zorio POSTs an event to the URL you registered (HMAC-signed).
- [Call Detail Records (CDR)](https://docs.zorio.vn/en/api/pbx/cdr.md) — Query CDRs with multiple filters and download recordings via signed URLs.
- [Click-to-Call](https://docs.zorio.vn/en/api/pbx/click-to-call.md) — Originate a two-leg call from the API: A-leg dials the agent extension → on pickup → B-leg dials the customer number → bridge.
- [Extensions](https://docs.zorio.vn/en/api/pbx/extensions.md) — Manage SIP extensions on the PBX: list, create, update, delete, fetch available numbers, and rotate the SIP password.
- [PBX API — Overview](https://docs.zorio.vn/en/api/pbx/index.md) — 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 section.
- [Queue](https://docs.zorio.vn/en/api/pbx/queue.md) — Manage Zorio PBX queues: CRUD queues, add / update / remove agent tiers.
- [PBX Webhook Events](https://docs.zorio.vn/en/api/pbx/webhooks.md) — Every event has the same envelope:
- [Caller-ID rotation groups](https://docs.zorio.vn/en/api/telesales/caller-id-groups.md) — | 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...
- [Campaigns](https://docs.zorio.vn/en/api/telesales/campaigns.md) — 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 (initi...
- [DNC list](https://docs.zorio.vn/en/api/telesales/dnc.md) — 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.
- [Telesales API — Overview](https://docs.zorio.vn/en/api/telesales/index.md) — Public REST API for the Telesales Module. Lets a customer CRM integrate dialer + campaigns + leads + caller-ID rotation + recording + reports.
- [Leads](https://docs.zorio.vn/en/api/telesales/leads.md) — 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.
- [Recording](https://docs.zorio.vn/en/api/telesales/recording.md) — 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.
- [Reports](https://docs.zorio.vn/en/api/telesales/reports.md) — 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/Exc...
- [Script + Outcome](https://docs.zorio.vn/en/api/telesales/scripts.md) — 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.
- [API Token (machine-to-machine)](https://docs.zorio.vn/en/auth/api-token.md) — 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.
- [Rate limit & Idempotency](https://docs.zorio.vn/en/auth/rate-limit.md) — Two mechanisms Zorio uses to protect the API and to help your CRM retry safely.
- [Bearer (user session)](https://docs.zorio.vn/en/auth/sanctum-bearer.md) — 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).
- [Webhook HMAC-SHA256 signing](https://docs.zorio.vn/en/auth/webhook-hmac.md) — For deeper coverage and full sample receivers see Webhooks → HMAC-SHA256 signing. This page is a quick summary so a new technical CRM team can grasp the signing and verification model.
- [Core concepts](https://docs.zorio.vn/en/getting-started/concepts.md) — Each Zorio customer gets an isolated system with:
- [Conventions](https://docs.zorio.vn/en/getting-started/conventions.md) — | Type | URL | |---|---| | REST API | https://app.zorio.vn/api/ | | Webhook receiver (you host) | your URL |
- [Introduction](https://docs.zorio.vn/en/getting-started/introduction.md) — Zorio is a Contact Center platform for businesses, consisting of:
- [Obtain an API token](https://docs.zorio.vn/en/getting-started/obtain-token.md) — 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.
- [FAQ](https://docs.zorio.vn/en/reference/faq.md) — The most frequent integration questions. If yours isn't here, reach out to Zorio support.
- [Glossary](https://docs.zorio.vn/en/reference/glossary.md) — A consolidated glossary of Zorio terms used across the API modules.
- [Hangup cause codes](https://docs.zorio.vn/en/reference/hangup-codes.md) — The hangupcause 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.
- [HTTP status codes](https://docs.zorio.vn/en/reference/http-codes.md) — Complete reference for HTTP status codes the Zorio API returns and how your CRM should handle them.
- [API methods](https://docs.zorio.vn/en/sdk/webphone/api.md) — 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 incomingcall event payload).
- [Events](https://docs.zorio.vn/en/sdk/webphone/events.md) — 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?).
- [Embed via iframe (SSO)](https://docs.zorio.vn/en/sdk/webphone/iframe.md) — 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,...
- [Webphone SDK — Overview](https://docs.zorio.vn/en/sdk/webphone/index.md) — 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).
- [Embed via npm](https://docs.zorio.vn/en/sdk/webphone/npm.md) — 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.
- [Quickstart HTML](https://docs.zorio.vn/en/sdk/webphone/quickstart.md) — 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.
- [Embed via UMD/CDN](https://docs.zorio.vn/en/sdk/webphone/umd.md) — 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.
- [HMAC-SHA256 signing](https://docs.zorio.vn/en/webhooks/hmac.md) — Every webhook Zorio sends to your receiver is signed with HMAC-SHA256 using the secret you saved at registration. Purpose:
- [Register a webhook](https://docs.zorio.vn/en/webhooks/register.md) — 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.
- [Retry policy](https://docs.zorio.vn/en/webhooks/retry.md) — 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.
- [Sample receivers](https://docs.zorio.vn/en/webhooks/sample-receivers.md) — 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.