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.