Kết bạn Zalo & Gửi tin nhắn sau cuộc gọi Callbot

I. Tổng quan

Mô tả nghiệp vụ tính năng tự động gửi lời mời kết bạn Zalo và gửi tin nhắn Zalo cá nhân hóa sau khi cuộc gọi Callbot kết thúc, tích hợp truyền biến từ dữ liệu khách hàng chiến dịch (call_campaign_customer).

1. Vấn đề

Sau khi Callbot thực hiện cuộc gọi, doanh nghiệp cần kết nối ngay với khách hàng trên Zalo (kênh tương tác có tỷ lệ mở cao nhất) để gửi tài liệu, báo giá, hợp đồng hoặc thông tin tiếp theo.
Trước đây, nội dung Lời mời kết bạn và Gửi tin nhắn Zalo ở Bước 3 (Cấu hình) chỉ cho phép nhập văn bản tĩnh hoặc chỉ chèn được các thông số kỹ thuật của cuộc gọi (Trạng thái, Chất lượng, Thời lượng, Thời gian gọi, Ghi chú…).
Tin nhắn gửi đi mang tính chất chung chung, không xưng hô đúng tên khách hàng, không nhắc được các thông tin cá nhân hóa (mã đơn hàng, ngày hẹn, số tiền cần đóng, chi nhánh phụ trách…). Do đó, khách hàng dễ hiểu nhầm là tin nhắn spam, dẫn đến tỷ lệ chấp nhận kết bạn thấp và tỷ lệ tương tác sau cuộc gọi không cao.

2. Giải pháp

Cho phép người dùng truyền biến động từ danh sách Khách hàng chiến dịch Callbot (call_campaign_customer) vào cả Lời mời kết bạn và Gửi tin nhắn Zalo.
Các biến được trích xuất tự động từ file danh sách liên hệ đã nạp ở Bước 2 (Danh sách liên hệ) của chính chiến dịch đó.
Khi cuộc gọi kết thúc, hệ thống tự động gán dữ liệu thực tế của từng khách hàng vào nội dung tin nhắn và gửi ngay lập tức qua tài khoản Zalo cá nhân đã cấu hình.

3. Đối tượng

Admin / Campaign Manager / Sales Ops / CX Team: Người khởi tạo, cấu hình kịch bản và thiết lập chiến dịch gọi tự động.
Khách hàng cuối: Người nghe cuộc gọi từ Callbot và nhận tin nhắn chăm sóc cá nhân hóa trên Zalo.

4. Tầm nhìn / Insight (Mở rộng trong tương lai)

Cho phép người cấu hình Xem trước (Preview) nội dung tin nhắn mẫu với dữ liệu thực tế của 1 vài dòng khách hàng trong danh sách trước khi chạy chiến dịch.
Bổ sung biến thực thể (Entities) được AI bóc tách trực tiếp trong quá trình hội thoại (ví dụ: ngày hẹn khách chốt lại trong cuộc gọi, địa chỉ mới khách cung cấp) vào tin nhắn Zalo.

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

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

Bật/Tắt tính năng Kết bạn Zalo: Cấu hình điều kiện lọc nâng cao sau cuộc gọi và chọn tài khoản Zalo cá nhân gửi tin.
Lời mời kết bạn cá nhân hóa: Soạn mẫu lời mời kết bạn, hỗ trợ nút chèn biến (+) lấy dữ liệu từ khách hàng chiến dịch, có bộ đếm ký tự và cảnh báo độ dài 150 ký tự Zalo.
Tin nhắn Zalo cá nhân hóa: Soạn mẫu tin nhắn gửi ngay sau cuộc gọi, hỗ trợ nút chèn biến (+) lấy dữ liệu từ khách hàng chiến dịch, giới hạn 2.000 ký tự và hỗ trợ đính kèm tối đa 5 hình ảnh.
Bộ xử lý gán biến thời gian thực (Runtime Variable Resolver): Khớp biến theo record khách hàng, xử lý giá trị rỗng/null, và tự động cắt ngắn chuỗi bảo vệ API Zalo.

2. Đặc tả chi tiết

2.1. Nguồn biến & Danh mục biến hỗ trợ (Variable Schema)

Yêu cầu cốt lõi: Danh mục các biến hỗ trợ chèn vào Lời mời kết bạn và Gửi tin nhắn Zalo ở Bước 3 phải đầy đủ và đồng bộ 100% với danh sách các trường trong Bộ lọc nâng cao tại Báo cáo chi tiết chiến dịch Callbot, bao gồm: (1) Biến của báo cáo khách hàng chiến dịch và (2) Biến của khách hàng được nạp ở Bước 2.

Khi người dùng bấm vào icon (+) tại ô Lời mời kết bạn hoặc Gửi tin nhắn Zalo, danh sách biến hiển thị đầy đủ các nhóm sau:

Nhóm biến	Nguồn dữ liệu	Chi tiết các biến (theo chuẩn Bộ lọc nâng cao Báo cáo chi tiết)
Báo cáo Khách hàng Chiến dịch (Report Attributes)	Các thuộc tính kết quả và tương tác của cuộc gọi	• `Trạng thái` (`status`): Thành công, Không nghe máy, Máy bận… • `Chất lượng` (`quality`): Tốt, Không tốt… • `Ý định / Nhãn dán` (`intent` / `tag`): Quan tâm, Không quan tâm, Hẹn gọi lại… • `Đã kiểm tra` (`is_checked`): Đã kiểm tra / Chưa kiểm tra • `Gọi thử` (`is_test_call`): Cuộc gọi thử / Cuộc gọi thật • `Thời lượng` (`duration`): Thời gian đàm thoại (giây) • `Ghi chú` (`note`): Tóm tắt nội dung AI hoặc nhân viên ghi chú • `Số cuộc gọi` (`call_count`): Số lần gọi cho khách hàng • `Thời gian gọi điện` (`call_time`): Thời điểm phát sinh cuộc gọi • `Nhân viên` (`agent`): Nhân viên phụ trách / liên kết • `Số điện thoại` (`phone_number`): SĐT của khách hàng
Khách hàng ở Bước 2 (Trường chuẩn)	Các thuộc tính định danh cơ bản của khách hàng	• `Tên` / `Họ và tên` (`name` / `customer_name`) • `Giới tính` (`gender`: Nam / Nữ / Không xác định) • `Số điện thoại phụ` (`secondary_phone`)
Khách hàng ở Bước 2 (Trường tùy chỉnh - Custom Fields) (Động theo từng chiến dịch)	Toàn bộ header các cột có trong file liên hệ đã nạp ở Bước 2 của chính chiến dịch đó	Tự động sinh theo file import của chiến dịch, ví dụ: • `<br>•` • `<br>•` • `<br>•` • `<br>•` • ``… (bất kỳ cột nào có trong file)

Quy tắc đồng bộ và phụ thuộc Bước 2:

Nếu chiến dịch đã nạp danh sách khách hàng ở Bước 2: Menu (+) hiển thị đầy đủ các biến Báo cáo cuộc gọi và toàn bộ các cột tùy chỉnh của file khách hàng.

Nếu chiến dịch chưa nạp danh sách ở Bước 2 (hoặc danh sách trống): Menu (+) hiển thị các trường chuẩn hệ thống + biến báo cáo cuộc gọi, kèm dòng ghi chú mờ: “Vui lòng nạp danh sách liên hệ ở Bước 2 để sử dụng các trường tùy biến từ file.”

2.2. Đặc tả cài đặt tại Bước 3 (Cấu hình)

Mục cấu hình	Kiểu dữ liệu	Bắt buộc	Ràng buộc & Mô tả
Kết bạn Zalo	Toggle (Bật/Tắt)	❌	Bật để kích hoạt quy trình gửi Zalo sau cuộc gọi.
Điều kiện thực hiện hành động	Dropdown filter	✅	Mặc định: “Lọc nâng cao”. Thiết lập điều kiện cuộc gọi (ví dụ: Trạng thái là Thành công, Ý định là Quan tâm…).
Tài khoản Zalo cá nhân	Dropdown	✅	Chọn tài khoản Zalo cá nhân đã liên kết trên hệ thống phụ trách kết bạn và gửi tin.
Lời mời kết bạn	Checkbox + Textarea	❌	Soạn nội dung gửi kèm lời mời kết bạn. • Giới hạn: Tối đa 150 ký tự (giới hạn cứng của Zalo cá nhân). • Có nút `(+)` chèn biến. • Có bộ đếm ký tự tĩnh: `X / 150 ký tự`.
Gửi tin nhắn Zalo	Checkbox + Textarea	❌	Soạn nội dung tin nhắn gửi sau cuộc gọi. • Giới hạn: Tối đa 2.000 ký tự. • Có nút `(+)` chèn biến. • Có bộ đếm ký tự: `X / 2.000 ký tự`. • Chú thích: “Bao gồm các tài khoản Zalo vừa gửi lời mời kết bạn và các tài khoản Zalo đã kết bạn”.
Tải ảnh đính kèm	File Upload (Multiple)	❌	Chỉ hiển thị khi tick chọn “Gửi tin nhắn Zalo”. Cho phép tải tối đa 5 ảnh (định dạng: JPG, PNG, WEBP; dung lượng $\le 5\text{MB}$/ảnh).

2.3. Các Use Case

Use case 1: Cấu hình lời mời kết bạn và tin nhắn có chứa biến khách hàng

Actor: Người cấu hình chiến dịch.
Tiền điều kiện: Chiến dịch đã nạp file liên hệ ở Bước 2 gồm các cột: Họ tên, SĐT, Mã HĐ, Số tiền.
Luồng:
1. Người dùng bật toggle Kết bạn Zalo $\rightarrow$ Chọn tài khoản Zalo Mai.
2. Tick chọn Lời mời kết bạn $\rightarrow$ Nhập: "Chào " $\rightarrow$ Bấm (+) $\rightarrow$ Chọn [Họ tên] $\rightarrow$ Nhập tiếp: ", bên em liên hệ gửi thông tin hợp đồng " $\rightarrow$ Bấm (+) $\rightarrow$ Chọn [Mã HĐ].
3. Tick chọn Gửi tin nhắn Zalo $\rightarrow$ Bấm (+) chèn các biến [Họ tên], [Số tiền] vào mẫu tin nhắn chi tiết $\rightarrow$ Tải 1 ảnh hướng dẫn thanh toán.
4. Bấm Hoàn thành để lưu chiến dịch.

Use case 2: Hệ thống gửi Zalo sau khi cuộc gọi hoàn tất (Runtime)

Actor: Hệ thống Callbot & Zalo Service.
Tiền điều kiện: Cuộc gọi kết thúc và thỏa mãn điều kiện lọc.
Luồng:
1. Hệ thống tìm bản ghi khách hàng tương ứng của cuộc gọi trong bảng call_campaign_customer.
2. Hệ thống thế các giá trị thực tế của khách hàng vào các placeholder.
3. Nếu cột dữ liệu nào của khách hàng bị trống $\rightarrow$ Tự động thế bằng chuỗi rỗng "" và dọn khoảng trắng kép.
4. Nếu chuỗi lời mời kết bạn dài hơn 150 ký tự $\rightarrow$ Cắt lấy đúng 150 ký tự đầu tiên.
5. Thực hiện gửi:
  - Với khách chưa kết bạn: Gửi lời mời kết bạn kèm nội dung cá nhân hóa, đồng thời gửi ngay lập tức tin nhắn Zalo (dạng tin nhắn từ người lạ).
  - Với khách đã là bạn bè: Bỏ qua lời mời kết bạn, gửi trực tiếp tin nhắn Zalo kèm ảnh đính kèm.

3. Danh sách nghiệp vụ (Business Rules)

BR-01 (Phạm vi biến tùy biến): Danh mục biến tùy biến trong menu (+) phải được lấy động theo đúng cấu trúc các cột trong file khách hàng nạp ở Bước 2 của chính chiến dịch đang cấu hình, không lấy lẫn sang chiến dịch khác.
BR-02 (Xử lý giá trị rỗng - Null / Empty Fallback): Khi một trường dữ liệu trong dòng của khách hàng bị trống hoặc mang giá trị null, hệ thống tự động thay thế bằng chuỗi rỗng "", đồng thời tự động chuẩn hóa các khoảng trắng thừa kép ( $\rightarrow$ ` `) để đảm bảo câu văn liền mạch.
BR-03 (Ràng buộc độ dài Zalo & Truncation):
- Lời mời kết bạn: Giới hạn tối đa 150 ký tự (giới hạn cứng của API Zalo cá nhân). Sau khi ghép dữ liệu thực tế, nếu tổng độ dài chuỗi $> 150$ ký tự, hệ thống cắt lấy đúng 150 ký tự đầu để đảm bảo API Zalo không từ chối gửi lệnh.
- Gửi tin nhắn Zalo: Giới hạn tối đa 2.000 ký tự. Cho phép đính kèm tối đa 5 ảnh.
BR-04 (Thời điểm gửi tin nhắn Zalo): Tin nhắn Zalo được gửi ngay lập tức sau khi cuộc gọi kết thúc thành công và thỏa điều kiện lọc (gửi cùng lúc với lời mời kết bạn đối với tài khoản chưa kết bạn, không cần chờ khách hàng bấm xác nhận đồng ý kết bạn).
BR-05 (Thao tác Editor):
- Biến được chèn chính xác tại vị trí con trỏ chuột (cursor position) trong ô textarea.
- Định dạng hiển thị biến trong Editor tuân thủ theo chuẩn component UI mà Frontend đang dùng trên hệ thống.
- Popup menu (+) có ô tìm kiếm nhanh (Search) ở đầu danh sách để dễ dàng tìm kiếm khi file có nhiều cột.
BR-06 (Bảo toàn dữ liệu khi đổi file ở Bước 2): Nếu người dùng quay lại Bước 2 và import một file Excel mới làm thay đổi cấu trúc cột, các biến đã chèn ở Bước 3 không còn tồn tại trong file mới sẽ được xử lý như một trường rỗng (thay bằng "") khi chạy thực tế.

4. Giao diện (UI/UX)

Vị trí icon (+): Nằm ở góc dưới bên phải bên trong khung của cả 2 ô textarea: Lời mời kết bạn và Gửi tin nhắn Zalo.
Cảnh báo độ dài Lời mời kết bạn: Hiển thị dòng chữ nhỏ màu xám dưới ô nhập:
“Lưu ý: Zalo giới hạn lời mời kết bạn tối đa 150 ký tự. Khi hệ thống gán dữ liệu khách hàng thực tế, nếu vượt quá 150 ký tự nội dung sẽ tự động bị cắt ngắn.”
Bộ đếm ký tự: Cập nhật số lượng ký tự theo thời gian thực khi người dùng gõ phím hoặc chèn biến (tính theo độ dài chuỗi template).

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

Độ trễ xử lý (Latency): Việc khớp biến và phát lệnh gửi tin nhắn qua Zalo Bot phải hoàn tất trong vòng $\le 5$ giây kể từ khi cuộc gọi Callbot kết thúc.
Độ an toàn dữ liệu: Không lưu log lộ lọt thông tin nhạy cảm của khách hàng trong log hệ thống (tuân thủ mã hóa dữ liệu cá nhân PII).
Ghi log & Truy vết (Logging): Ghi nhận chi tiết kết quả gửi Zalo (thành công/thất bại, lý do thất bại như chặn tin nhắn người lạ, SĐT chưa đăng ký Zalo, v.v.) vào mục Báo cáo chi tiết cuộc gọi.

IV. Dependency (Liên quan & Phụ thuộc)

Module Chiến dịch Callbot (Campaign Service): Cung cấp cấu trúc schema các cột của khách hàng ở Bước 2 (call_campaign_customer).
Zalo Integration Service / Extension: Thực thi hành động gửi lời mời kết bạn và tin nhắn qua Zalo cá nhân.
Báo cáo chi tiết Callbot: Nơi hiển thị trạng thái và lịch sử gửi Zalo của từng khách hàng.

V. API Contract (Dự kiến)

1. API Lưu cấu hình chiến dịch (Bước 3)

Endpoint: PUT /api/v1/campaigns/callbot/{campaign_id}/config

Request Body (trích đoạn phần Zalo):

{
  "zalo_friend_action": {
    "is_enabled": true,
    "account_id": "zalo_acc_mai_01",
    "filter_condition": {
      "status": "connected",
      "intent": "interested"
    },
    "invitation": {
      "is_enabled": true,
      "content_template": "Chào , bên em gọi từ chi nhánh . Xin phép kết bạn để gửi thông tin nhé!"
    },
    "message": {
      "is_enabled": true,
      "send_timing": "immediate",
      "content_template": "Chào , em gửi chi tiết hợp đồng  với số tiền  VNĐ.",
      "image_urls": [
        "https://cdn.ucall.vn/uploads/hd_template.png"
      ]
    }
  }
}

VI. Test Cases (Kiểm thử & Nghiệm thu)

Mã TC	Mô tả trường hợp kiểm thử	Dữ liệu đầu vào	Kết quả mong đợi
TC01	Trích xuất đúng biến từ Bước 2	File Bước 2 có cột: `Tên KH`, `Mã HĐ`, `Ghi chú 1`	Menu `(+)` ở cả 2 ô hiển thị chính xác các trường này
TC02	Chèn biến vào vị trí con trỏ	Đặt con trỏ sau chữ `"Chào "`, bấm chọn biến `[Tên KH]`	Chuỗi hiển thị thành `"Chào [Tên KH]"`
TC03	Khách hàng có đủ dữ liệu biến	Khách hàng có `Tên KH = "Trần Văn B"`	Tin nhắn gửi đi: `"Chào Trần Văn B"`
TC04	Khách hàng bị trống dữ liệu biến	Khách hàng có cột `Tên KH = ""`	Biến được thay bằng `""`, chuỗi gửi đi: `"Chào"` (đã xóa khoảng trắng thừa kép)
TC05	Lời mời kết bạn vượt quá 150 ký tự	Chuỗi sau khi ghép biến thực tế dài 165 ký tự	Hệ thống tự động cắt đúng 150 ký tự đầu tiên, gửi thành công qua Zalo API
TC06	Gửi tin nhắn ngay lập tức	Khách hàng chưa kết bạn vừa kết thúc cuộc gọi đạt điều kiện	Hệ thống gửi lời mời kết bạn và gửi luôn tin nhắn Zalo ngay sau cuộc gọi
TC07	Khách hàng đã là bạn bè từ trước	SĐT khách hàng đã có trong danh bạ Zalo cá nhân	Bỏ qua bước kết bạn, gửi trực tiếp tin nhắn Zalo kèm ảnh đính kèm
TC08	Chiến dịch chưa nạp khách hàng ở Bước 2	Chiến dịch mới tạo, chưa upload file ở Bước 2	Menu `(+)` hiển thị các trường chuẩn hệ thống + thông báo nhắc nạp file