Recall hàng loạt qua Zalo ZNS

Customer Care mở queue "Bệnh nhân cần tái khám" (6 tháng không quay lại), chọn 30 BN, gửi batch Zalo ZNS template "Đã đến hẹn cạo vôi định kỳ". Hệ thống check consent (BN đồng ý nhận), lọc block list (BN chặn Zalo). BN reply qua Zalo → tự động đặt lịch hẹn. Nếu BN chặn Zalo, fallback sang SMS Brandname.

Ảnh minh hoạ

Luồng recall: Customer Care → filter 30 BN → select template → gửi ZNS batch → BN reply → tự động đặt lịch / fallback SMS

Bối cảnh

Phòng khám muốn chủ động recall BN để tái khám định kỳ (sạch vôi 6 tháng, kiểm tra implant 1 năm, etc.). Cách truyền thống là gọi điện, nhưng mất thời gian. DentIQ hỗ trợ gửi batch ZNS (Zalo Notification Service) — BN nhận thông báo trên Zalo → bấm reply → đặt lịch tự động. Nếu BN chặn Zalo, hệ thống tự động gửi SMS fallback.

ZNS là dịch vụ của Zalo cho phép phòng khám gửi template messages (không phải tin nhắn tự do). Cần BN cho phép (consent) và có account Zalo hợp lệ.

Diễn viên & quyền cần

Vai trò	Quyền cần	Tác vụ
Customer Care	`customer_care.manage`	Mở queue, filter BN, gửi ZNS batch, track status
Quản lý phòng khám	`communication.manage` hoặc quản trị	Cấu hình ZNS provider, cấp quyền template
Lễ tân	appointment.manage`	Xem booking từ ZNS reply, confirm hẹn

Quy trình từng bước

Mở Customer Care → Retention Operations (hoặc "Chăm sóc kỹ thuật số" tùy setup).
Filter queue "Bệnh nhân cần tái khám": ngành hàng = Tái khám định kỳ (Periodic recall), ngày cutoff = 6 tháng trước → xem danh sách BN.
Select BN muốn gửi (hoặc "Select all" nếu < 100 BN). Mỗi BN phải có:
- Số điện thoại hợp lệ (để ZNS/SMS).
- Consent = true (BN đồng ý nhận tin nhắn).
- Zalo account hoặc SĐT (để nhận ZNS).
Chọn template ZNS: "Đã đến hẹn cạo vôi định kỳ" (hoặc template khác tuỳ dịch vụ) → xem preview message.
Bấm "Gửi ZNS" → hệ thống kiểm tra:
- Consent của từng BN → nếu consent = false, bỏ qua BN đó.
- Block list (BN đã chặn Zalo) → nếu có, chuyển sang SMS fallback queue.
- Tính phí ZNS (nếu có) → confirm với user.
Confirm gửi → hệ thống enqueue batch job (idempotent key = clinic + branch + template + date để tránh duplicate).
Worker xử lý job: gửi ZNS từng BN, track delivery status (SENT / FAILED / DELIVERED).
BN nhận ZNS → bấm "Đặt lịch" hoặc "Reply" → click link trong ZNS → mở scheduler (calendar).
BN chọn ngày/giờ → confirm → hệ thống auto-create appointment với status `BOOKING_FROM_ZNS`.
Notification về lễ tân: phát sự kiện "Appointment booked from ZNS" → lễ tân xác nhận (confirm hoặc ask more info qua Zalo).
Fallback SMS (nếu ZNS fail hoặc block): hệ thống tự động gửi SMS Brandname kèm link booking khác → BN reply SMS hoặc click link.

Kết quả mong đợi

ZNS batch status: PENDING → SENT → tỷ lệ DELIVERED vs FAILED.
Customer Care tracking: mỗi BN hiển thị "ZNS sent", "Appointment booked", hoặc "Fallback SMS sent".
Appointment auto-created: từ ZNS reply → xuất hiện ở Reception queue hoặc Scheduler, trạng thái `BOOKING_FROM_ZNS` (đợi lễ tân confirm).
Audit trail: ghi nhận ai gửi, template nào, bao nhiêu BN, kết quả (delivered, failed, SMS fallback).
No duplicate: nếu gửi lại cùng batch (idempotent key trùng) → hệ thống trả về kết quả cũ, không gửi lại.
Realtime event: phát sự kiện "APPOINTMENT_BOOKED_FROM_CAMPAIGN" → frontend refresh reception queue, scheduler, customer care outcome.

Khi nào hỏng & cách xử lý

Tình huống	Dấu hiệu	Giải pháp
BN quá ít consent	Sau filter consent, chỉ còn 5 BN của 30	Tạo campaign ghi phút (opt-in drive) trước. Hoặc chọn BN khác hoặc SMS fallback toàn bộ.
ZNS gửi fail (FAILED status)	Batch report: "10 delivered, 5 failed"	Check nếu SĐT/Zalo account sai. Hoặc fallback SMS. Hoặc retry sau (job được schedule lại).
BN reply nhưng không tạo appointment	Customer Care thấy "ZNS delivered" nhưng không "Appointment booked"	BN đọc ZNS nhưng không click booking link. Hoặc BN click nhưng lỗi scheduler. Lễ tân gọi điện/Zalo kèm confirm lịch hẹn.
Nút "Gửi ZNS" bị disable	Button grey out	Check (1) select ≥ 1 BN, (2) template available, (3) clinic có ZNS provider config, (4) permission `customer_care.manage`.
SMS fallback không được gửi	Block list BN nhưng SMS không đến	Check (1) SMS provider cấu hình (Brandname/Twilio), (2) số điện thoại BN hợp lệ, (3) SMS credits còn.
Duplicate ZNS sent	BN nhận 2 tin nhắn cùng lúc	Idempotent key fail (server restart giữa gửi). Hệ thống sẽ fix bằng DB constraint (unique batch key). Hoặc manual de-dup nếu cần.

Dấu vết để lại (audit & branch ownership)

Khi gửi ZNS batch, DentIQ ghi lại:

CampaignLog (hoặc CommunicationBatchLog): người gửi, template, ngày/giờ, số BN, provider (ZNS), status (PENDING/SENT/COMPLETED/FAILED).
CommunicationEventLog: mỗi ZNS gửi đến từng BN, delivery status (DELIVERED / FAILED / BLOCKED), timestamp, fallback action (SMS sent).
AppointmentAuditLog: khi BN reply booking → appointment tạo tự động, source = "CAMPAIGN_ZNS".
Branch ownership (CI-01): ZNS batch branch = clinic đang active hoặc theo filter queue. Nếu customer-care ở chi nhánh A gửi batch cho BN ở chi nhánh B, hệ thống vẫn ghi chi nhánh B (tuỳ BN address).
Realtime event: phát `COMMUNICATION_CAMPAIGN_SENT`, `APPOINTMENT_BOOKED_FROM_CAMPAIGN` → frontend refresh retention queue, reception board, scheduler.

Quan trọng: Consent & Privacy

ZNS chỉ gửi được nếu BN consent = true. DentIQ kiểm tra mỗi BN. Nếu consent = false, hệ thống tự động bỏ qua BN đó. Điều này tuân theo GDPR / luật bảo vệ dữ liệu. Consent có thể được ghi nhận khi BN check tick "Tôi muốn nhận tin nhắn từ phòng khám" lúc tạo hồ sơ hoặc sau.

Tip: Template best practice

Template ZNS phải ngắn gọn, có lời kêu gọi hành động (CTA) rõ ràng: "Đặt lịch" button, link booking, hoặc "Reply CONFIRM". Tránh spam, chỉ gửi recall bổ ích. Clinic có thể tạo nhiều template (sạch vôi, kiểm tra implant, tẩy trắng, etc.) và chọn đúng template cho từng campaign.

Permission & role-based send

Vai trò	Có thể gửi?	Ghi chú
Customer Care (manage)	✓	Chính người chạy recall campaign.
Customer Care (read)	✗	Chỉ xem status, không gửi.
Clinic Admin	✓	Có thể gửi hoặc phê duyệt batch lớn.
Doctor / Receptionist	✗	Không có permission `customer_care.manage`.

Các batch scenarios

Periodic recall (6 tháng): "Đã đến hẹn cạo vôi định kỳ" template → mỗi tháng gửi 1 lần.
Post-implant check (12 tháng): "Kiểm tra tình trạng implant" → gửi sau 1 năm gắn.
Follow-up treatment (đang dở dang): "Lịch tái khám để hoàn thiện điều trị" → gửi sau stage đầu tiên.
Warranty recovery (BN gặp vấn đề): "Liên hệ để xử lý bảo hành miễn phí" → gửi khi claim active.