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 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 + 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

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.

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
Scripts + DTMF actions	Tới trang
Leads + Variables	Tới trang
Voices + Media files	Tới trang
Reports	Tới trang
Webhook events AutoCall	Tới trang

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.

Response shape

{ "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.

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