Chiến dịch Callbot

I. Tổng quan

1. Vấn đề

Doanh nghiệp cần tiếp cận hàng nghìn khách hàng mỗi ngày để nhắc lịch hẹn, khảo sát mức độ hài lòng, hoặc thông báo khuyến mãi — nhưng đội ngũ nhân sự không đủ để gọi thủ công với quy mô lớn.
Gọi thủ công không nhất quán: chất lượng kịch bản phụ thuộc vào từng agent, thời gian gọi không được tối ưu, và kết quả khó theo dõi theo thời gian thực.
Không có cơ chế phản ứng tức thời với phản hồi của khách hàng (ví dụ: KH nhấn phím để đặt lại lịch) mà không cần nhân sự can thiệp.

2. Giải pháp

Xây dựng module Chiến dịch Callbot cho phép tạo và vận hành các chiến dịch gọi tự động hàng loạt bằng AI giọng nói (TTS), tích hợp nhận dạng ý định (intent recognition) để điều hướng kịch bản linh hoạt.
Hệ thống tự động gọi theo danh sách KH được lọc từ CRM, theo khung giờ tối ưu, ghi nhận kết quả và trả dữ liệu về CRM theo thời gian thực.

3. Đối tượng

Admin / Marketing Manager: Tạo và quản lý chiến dịch, cấu hình kịch bản, lên lịch gọi.
Marketing Ops / CX Team: Theo dõi báo cáo real-time, điều chỉnh chiến dịch đang chạy.
Người cấu hình Automation (Adaflow): Kích hoạt flow tự động dựa trên sự kiện của chiến dịch Callbot.

4. Tầm nhìn / Insight

Mở rộng thêm khả năng AI hiểu hội thoại tự do (NLU) thay vì chỉ nhận phím DTMF.
Hỗ trợ chiến dịch đa kênh: sau cuộc gọi Callbot thất bại, tự động chuyển sang gửi ZNS/SMS.
Phân tích sentiment phản hồi khách hàng từ dữ liệu ghi âm.
Trigger Adaflow khi kết quả cuộc gọi được cập nhật (đang phát triển).

II. Yêu cầu chức năng

1. Danh sách tính năng

Phát hiện hộp thư thoại (Voicemail Detection): Logic phát hiện voicemail qua cơ chế song song (tiếng bíp, im lặng và phân loại bằng LLM/từ khóa).
Bộ kết nối câu lấp liếm (Filler Connectors): Logic xử lý câu lấp liếm trì hoãn khi bot đang đợi LLM phản hồi (chế độ voice_ai và voice_record).
Nhận diện giới tính người nghe (Gender Recognition): Logic nhận diện giới tính và phát file ghi âm tương ứng theo giới tính của người nghe.
Cảm ứng giọng nói & Luồng lượt hội thoại (VAD Conversation Turn Flow): Logic điều khiển luồng lượt hội thoại (BASIC, VAD_LISTEN, VAD_INTERRUPT) và xử lý ngắt lời.
[TODO: Liệt kê thêm các tính năng/chức năng con khác]

2. Đặc tả chi tiết

Tính năng 1: Tạo / Sửa / Xóa chiến dịch

User story: Là một [Marketing Manager], tôi muốn [tạo chiến dịch Callbot với tên và mục tiêu rõ ràng] để [theo dõi và quản lý từng đợt gọi tự động một cách có tổ chức].

Use case 1.1 (Happy path – Tạo thành công): Nhập đầy đủ tên chiến dịch, chọn mục tiêu (Nhắc lịch hẹn / Khảo sát / Thông báo khuyến mãi / Khác), chọn kịch bản → Bấm “Tạo” → Hệ thống lưu chiến dịch ở trạng thái Draft.
Use case 1.2 (Exception – Bỏ trống tên): Bỏ trống tên chiến dịch → Bấm “Tạo” → Hệ thống báo lỗi validate, không cho tạo.
Use case 1.3 (Happy path – Xóa chiến dịch Draft): Chiến dịch đang ở trạng thái Draft → Bấm “Xóa” → Xác nhận → Hệ thống xóa.
Use case 1.4 (Exception – Xóa chiến dịch đang Active): Chiến dịch đang ở trạng thái Active → Nút “Xóa” bị vô hiệu hóa hoặc hiện thông báo “Không thể xóa chiến dịch đang chạy”.

Cài đặt tạo chiến dịch:

Field	Loại	Bắt buộc	Mô tả
Tên chiến dịch	Text	✅	Tối đa 255 ký tự. Phải là duy nhất trong workspace.
Mục tiêu	Dropdown	✅	Nhắc lịch hẹn, Khảo sát hài lòng, Thông báo khuyến mãi, Khác
Kịch bản hội thoại	Dropdown	✅	Chọn từ danh sách kịch bản đã tạo
Mô tả	Textarea	❌	Ghi chú nội bộ
Tags	Multi-select	❌	Phân loại chiến dịch

Tính năng 2: Quản lý Kịch bản hội thoại (Scenario)

User story: Là một [Marketing Ops], tôi muốn [xây dựng kịch bản hội thoại dạng cây phân nhánh] để [bot tự động điều hướng đúng luồng dựa trên phản hồi của khách hàng].

Use case 2.1 (Happy path – Tạo kịch bản phân nhánh): Thêm node “Chào hỏi” với nội dung TTS → Thêm nhánh “Khách hàng nhấn 1 (Xác nhận)” và “Khách hàng nhấn 2 (Hủy)” → Mỗi nhánh dẫn tới node tương ứng → Lưu kịch bản.
Use case 2.2 (Happy path – Cấu hình TTS): Chọn giọng đọc (Nam / Nữ, Bắc / Nam / Trung), điều chỉnh tốc độ và cao độ → Nghe preview → Lưu.
Use case 2.3 (Happy path – AI Intent Recognition): Node cấu hình “Nghe phản hồi tự do” → KH nói “Tôi muốn hủy” → Bot nhận dạng intent cancel → Điều hướng sang nhánh Hủy.

Cấu trúc node kịch bản:

Loại node	Mô tả
Message	Phát nội dung TTS một chiều, không chờ phản hồi
Question (DTMF)	Phát câu hỏi, chờ KH nhấn phím số để phân nhánh
Question (NLU)	Phát câu hỏi, chờ KH nói, AI nhận dạng intent để phân nhánh
Transfer	Chuyển cuộc gọi sang số điện thoại hoặc agent cụ thể
End	Kết thúc cuộc gọi với lời chào
Webhook	Gọi API bên ngoài để lấy/gửi dữ liệu trong lúc hội thoại

Tính năng 3: Import / Chọn tập khách hàng

User story: Là một [Marketing Manager], tôi muốn [chọn đúng tập khách hàng mục tiêu từ CRM] để [chiến dịch gọi đúng đối tượng, không gọi lặp hoặc gọi nhầm].

Use case 3.1 (Happy path – Lọc từ CRM): Chọn “Lấy từ CRM” → Cấu hình bộ lọc (ví dụ: Khách hàng có Deal đang ở giai đoạn “Tư vấn”, có SĐT, chưa được gọi trong 7 ngày) → Xem preview số lượng KH thỏa điều kiện → Xác nhận.
Use case 3.2 (Happy path – Import file): Tải lên file Excel/CSV có cột SĐT bắt buộc → Hệ thống validate và map cột → Hiển thị số lượng hợp lệ/lỗi → Xác nhận import.
Use case 3.3 (Exception – File có số điện thoại không hợp lệ): Import file → Hệ thống báo cáo danh sách số không hợp lệ → Cho phép tải file lỗi để xem xét và tiếp tục import phần hợp lệ.

Cài đặt tập khách hàng:

Tùy chọn nguồn	Mô tả
Lọc từ CRM	Áp dụng bộ lọc đa điều kiện AND/OR trên Contact trong CRM
Import file	Upload file Excel / CSV
Nhóm khách hàng sẵn có	Chọn từ Segment đã định nghĩa trước trong CRM

Nghiệp vụ: Hệ thống tự động loại bỏ số điện thoại trùng lặp trong cùng chiến dịch. Cho phép cấu hình giới hạn số lần gọi lại (retry) với KH không nghe máy.

Tính năng 4: Lên lịch gọi

User story: Là một [Marketing Ops], tôi muốn [chỉ gọi trong khung giờ làm việc hợp lý] để [tối đa tỷ lệ KH bắt máy và không gây phiền nhiễu ngoài giờ].

Use case 4.1 (Happy path – Lên lịch khung giờ): Chọn ngày bắt đầu / kết thúc → Chọn khung giờ cho phép (ví dụ: 8:00–11:30, 13:30–17:00) → Chọn ngày trong tuần → Lưu lịch.
Use case 4.2 (Happy path – Cài đặt retry): Cấu hình: KH không nghe máy → Gọi lại sau 30 phút, tối đa 3 lần/ngày.

Cài đặt lên lịch:

Field	Loại	Bắt buộc	Mô tả
Ngày bắt đầu	Date picker	✅	Không được ở quá khứ
Ngày kết thúc	Date picker	❌	Nếu để trống: chạy đến khi hết danh sách
Khung giờ gọi	Time range (multi)	✅	Có thể chọn nhiều khung giờ/ngày
Ngày trong tuần	Multi-select	✅	Thứ 2 – Chủ nhật
Số lần gọi lại (Retry)	Number	❌	Mặc định: 2 lần. Tối đa: 5 lần
Khoảng cách retry	Dropdown	❌	15 phút / 30 phút / 1 giờ / 2 giờ
Tốc độ gọi đồng thời	Number	❌	Số cuộc gọi xử lý cùng lúc (concurrent calls)

Tính năng 5: Báo cáo Real-time

User story: Là một [Marketing Manager], tôi muốn [xem ngay kết quả chiến dịch đang chạy] để [điều chỉnh kịp thời nếu tỷ lệ thành công thấp].

Các chỉ số báo cáo:

Chỉ số	Mô tả
Tổng số KH	Tổng số lượng KH trong chiến dịch
Đã gọi	Số KH đã được gọi ít nhất 1 lần
Thành công (Connected)	KH bắt máy và nghe hết kịch bản
Không nghe máy (No Answer)	Không có phản hồi trong thời gian chờ
Máy bận (Busy)	Đường dây bận
Thất bại (Failed)	Lỗi kỹ thuật, số không tồn tại
Chờ gọi	Số KH chưa được gọi
Thời lượng trung bình	Thời gian trung bình mỗi cuộc gọi thành công
Kết quả phân nhánh	Bao nhiêu KH chọn mỗi nhánh trong kịch bản

Báo cáo cập nhật theo thời gian thực (polling ≤ 30 giây hoặc websocket).

Tính năng 6: Vòng đời trạng thái chiến dịch

Draft → Active → Paused → Active → Ended
Draft → Deleted (chỉ khi đang Draft)

Trạng thái	Mô tả	Hành động có thể thực hiện
Draft	Vừa tạo, chưa chạy	Sửa, Xóa, Kích hoạt
Active	Đang gọi theo lịch	Tạm dừng, Kết thúc, Xem báo cáo
Paused	Tạm dừng, có thể tiếp tục	Tiếp tục, Kết thúc
Ended	Đã hoàn thành hoặc bị kết thúc thủ công	Xem báo cáo, Clone

3. Danh sách nghiệp vụ

Tên chiến dịch phải là duy nhất trong cùng workspace.
Không thể xóa chiến dịch đang ở trạng thái Active hoặc Paused.
Kịch bản phải có ít nhất 1 node End trước khi chiến dịch được kích hoạt.
Hệ thống không gọi cho cùng 1 SĐT quá 1 lần trong 24 giờ (có thể cấu hình).
SĐT nằm trong danh sách DNC (Do Not Call) không được gọi, bất kể cấu hình.
Khi chiến dịch Paused, các cuộc gọi đang xử lý được hoàn thành, các cuộc gọi chưa bắt đầu bị giữ lại.
Kết quả cuộc gọi (label, phím nhấn, phản hồi) được ghi nhận vào hồ sơ KH trong CRM.
Chiến dịch có thể được nhân bản (Clone) để tái sử dụng cấu hình.

4. Giao diện

Trang danh sách chiến dịch: Bảng với các cột Tên, Mục tiêu, Trạng thái, Tổng KH, Tiến độ (%), Ngày tạo. Bộ lọc theo Trạng thái và Mục tiêu.
Trang chi tiết chiến dịch: Tabs: Tổng quan Danh sách KH Báo cáo Lịch sử.
Trang báo cáo real-time: Dashboard với số liệu tổng hợp (cards), biểu đồ donut trạng thái cuộc gọi, bảng log các cuộc gọi gần nhất.
Màn hình tạo chiến dịch: Wizard 3 bước: (1) Thông tin cơ bản → (2) Chọn KH → (3) Lên lịch.

III. Yêu cầu phi chức năng

Khả năng mở rộng: Hệ thống phải xử lý được chiến dịch với ≥ 100,000 KH mà không ảnh hưởng hiệu năng.
Concurrent calls: Hỗ trợ cấu hình số cuộc gọi đồng thời theo gói dịch vụ (ví dụ: 50, 100, 200 concurrent calls).
Latency kết quả: Kết quả cuộc gọi được ghi nhận vào CRM trong vòng 10 giây sau khi cuộc gọi kết thúc.
Chất lượng TTS: Điểm MOS (Mean Opinion Score) của giọng đọc ≥ 4.0/5.0.
Uptime: Module Callbot phải có uptime ≥ 99.5%/tháng.
Bảo mật: Ghi âm cuộc gọi phải được mã hóa khi lưu trữ (at-rest). Truy cập ghi âm phải có kiểm soát phân quyền.
Tuân thủ: Không gọi ngoài khung giờ 8:00–21:00 theo quy định. Hỗ trợ danh sách DNC.
Logging: Ghi log đầy đủ mỗi cuộc gọi: thời điểm, số gọi, kết quả, node kịch bản cuối cùng.

IV. Dependency (liên quan & phụ thuộc)

UCALL Module – Campaign & PBX: Xử lý cuộc gọi thực tế, quản lý trung kế (trunk), hàng đợi gọi.
UCALL Module – Scenario Engine: Thực thi kịch bản hội thoại, TTS, DTMF, NLU.
Adaflow Trigger – Khách hàng chiến dịch Callbot: dev/adaflow/trigger_nodes/campaign/callbot_campaign.md
CRM – Contact Management: Nguồn dữ liệu KH, nơi ghi nhận kết quả cuộc gọi.
DNC List Service: Kiểm tra số điện thoại trước khi gọi.
Campaign Library: Lưu trữ và chia sẻ kịch bản dùng chung.

V. API Contract (Dev viết)

API 1: Tạo chiến dịch Callbot

Method & Endpoint: POST /api/v1/campaigns/callbot

Request Body:

{
  "name": "Nhắc lịch hẹn tháng 7",
  "objective": "appointment_reminder",
  "scenario_id": "scn_abc123",
  "description": "Chiến dịch nhắc lịch tái khám"
}

Response 201:

{
  "id": "camp_xyz789",
  "status": "draft",
  "created_at": "2026-07-01T09:00:00Z"
}

API 2: Kích hoạt chiến dịch

Method & Endpoint: POST /api/v1/campaigns/callbot/{campaign_id}/activate
Response 200: { "status": "active", "started_at": "2026-07-01T09:05:00Z" }

API 3: Lấy báo cáo real-time

Method & Endpoint: GET /api/v1/campaigns/callbot/{campaign_id}/report

Response 200:

{
  "total": 5000,
  "called": 3200,
  "connected": 2100,
  "no_answer": 800,
  "busy": 200,
  "failed": 100,
  "pending": 1800,
  "avg_duration_seconds": 45
}

VI. Test case (BA hoặc Tester viết)

Tạo chiến dịch:

TC1.1: Nhập đủ thông tin hợp lệ → Tạo thành công, chiến dịch ở trạng thái Draft.
TC1.2: Bỏ trống tên chiến dịch → Hệ thống báo lỗi validate.
TC1.3: Nhập tên trùng với chiến dịch đã có → Hệ thống báo trùng tên.

Kịch bản hội thoại:

TC2.1: Tạo kịch bản có 2 nhánh DTMF → Lưu thành công.
TC2.2: Kịch bản không có node End → Không cho phép kích hoạt chiến dịch.
TC2.3: KH nhấn phím không có trong kịch bản → Bot phát lại câu hỏi hoặc kết thúc theo cấu hình.

Chọn tập khách hàng:

TC3.1: Lọc từ CRM → Hệ thống hiển thị đúng số lượng KH thỏa điều kiện.
TC3.2: Import file CSV có 10 SĐT hợp lệ, 2 không hợp lệ → Hiển thị báo lỗi 2 dòng, import 10 dòng hợp lệ.
TC3.3: SĐT trong danh sách DNC → Bị loại trước khi gọi, không tính vào cuộc gọi thất bại.

Lên lịch & Vận hành:

TC4.1: Đặt khung giờ gọi 8:00–12:00 → Hệ thống không gọi ngoài khung giờ này.
TC4.2: KH không nghe máy lần 1 → Hệ thống retry sau thời gian đã cấu hình.
TC4.3: Bấm “Tạm dừng” → Hệ thống dừng gọi mới, chiến dịch chuyển sang Paused.
TC4.4: Chiến dịch Paused → Bấm “Tiếp tục” → Hệ thống tiếp tục gọi từ danh sách chờ.

Báo cáo:

TC5.1: Chiến dịch đang chạy → Số liệu báo cáo cập nhật trong vòng 30 giây.
TC5.2: Cuộc gọi thành công (KH bắt máy) → Kết quả ghi nhận đúng vào hồ sơ KH trong CRM.