Chiến dịch ZNS & SMS — Đặc tả tính năng

I. Tổng quan

1. Vấn đề

Doanh nghiệp cần gửi thông báo hàng loạt (xác nhận đơn hàng, nhắc thanh toán, khuyến mãi) đến khách hàng qua Zalo — kênh có tỷ lệ mở cao nhất Việt Nam — nhưng thiếu công cụ quản lý tập trung.
Template ZNS phải qua quy trình phê duyệt phức tạp của Zalo OA; nếu không quản lý bài bản, dễ gửi template chưa duyệt gây lỗi và tốn chi phí thừa.
Khi KH không dùng Zalo hoặc chưa follow OA, tin ZNS thất bại nhưng không có cơ chế tự động fallback sang SMS, dẫn đến bỏ sót tiếp cận.

2. Giải pháp

Xây dựng module Chiến dịch ZNS & SMS tích hợp Zalo OA API và SMS Gateway, cung cấp:
- Quản lý vòng đời template ZNS (tạo → gửi duyệt → approved → dùng trong chiến dịch).
- Gửi tin hàng loạt có cá nhân hóa (biến động) và lên lịch gửi.
- Tự động fallback sang SMS khi ZNS thất bại.
- Báo cáo delivery rate và chi phí theo từng chiến dịch.

3. Đối tượng

Admin / Marketing Manager: Tạo và quản lý template, tạo chiến dịch gửi tin.
Marketing Ops: Chọn tập KH, lên lịch gửi, theo dõi báo cáo.
Finance / Admin: Theo dõi chi phí gửi tin, tối ưu ngân sách.

4. Tầm nhìn / Insight

Tích hợp thêm kênh: Viber, Email marketing vào cùng module thông báo.
A/B testing template để tối ưu tỷ lệ mở.
Phân tích hành vi sau tin nhắn: KH click link → mua hàng (attribution).
Trigger Adaflow: “Khi tin ZNS được gửi thành công / thất bại” để xử lý logic tiếp theo.

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

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

| # | Tính năng | Mô tả | |:—|:—|:—| | 1 | Quản lý Template ZNS | Tạo, gửi duyệt, quản lý trạng thái template | | 2 | Quản lý Template SMS | Tạo và quản lý mẫu tin SMS Brandname | | 3 | Tạo chiến dịch gửi tin | Cấu hình chiến dịch broadcast ZNS/SMS | | 4 | Cá nhân hóa tin nhắn | Chèn biến động vào template | | 5 | Lên lịch gửi | Cấu hình thời gian gửi | | 6 | Xử lý Fallback ZNS → SMS | Tự động chuyển kênh khi ZNS thất bại | | 7 | Báo cáo chiến dịch | Delivery rate, open rate, chi phí |

2. Đặc tả chi tiết

Tính năng 1: Quản lý Template ZNS

User story: Là một [Marketing Manager], tôi muốn [quản lý tập trung các template ZNS đã được Zalo duyệt] để [dễ dàng tái sử dụng và tránh gửi template chưa hợp lệ].

Vòng đời Template ZNS:

Draft → Pending Review (gửi Zalo duyệt) → Approved / Rejected
Approved → Active (dùng trong chiến dịch)
Approved → Deprecated (ngừng sử dụng)

Use case 1.1 (Happy path – Tạo và gửi duyệt): Tạo template: Chọn loại template (Giao dịch / Khuyến mãi / OTP), nhập nội dung với biến động, chọn nút CTA → Bấm “Gửi duyệt Zalo” → Trạng thái chuyển sang Pending Review → Zalo phê duyệt → Trạng thái thành Approved.
Use case 1.2 (Rejected): Zalo từ chối template → Trạng thái Rejected kèm lý do → Người dùng sửa và gửi lại.
Use case 1.3 (Sử dụng template đã duyệt): Chỉ template ở trạng thái Approved mới xuất hiện trong dropdown khi tạo chiến dịch gửi tin.

Cài đặt tạo template ZNS:

Field	Loại	Bắt buộc	Mô tả
Tên template	Text	✅	Tên nội bộ để phân biệt
Loại template	Dropdown	✅	Giao dịch (Transaction) / Khuyến mãi (Promotion) / OTP
OA ID	Dropdown	✅	Chọn Zalo OA đã kết nối
Nội dung tin nhắn	Textarea	✅	Tối đa 4096 ký tự. Hỗ trợ biến ``
Nút hành động (CTA)	Repeater	❌	Tối đa 2 nút: văn bản + URL hoặc số điện thoại
Hình ảnh đính kèm	File upload	❌	Chỉ với template loại Khuyến mãi, tỷ lệ 16:9

Chính sách Zalo: Template loại “Giao dịch” ưu tiên được duyệt nhanh hơn “Khuyến mãi”. Template “Khuyến mãi” chỉ gửi được cho KH đã follow OA.

Tính năng 2: Quản lý Template SMS

User story: Là một [Marketing Manager], tôi muốn [tạo và quản lý mẫu SMS Brandname] để [gửi tin nhắn thương hiệu đến KH khi ZNS thất bại hoặc khi cần tiếp cận qua SMS trực tiếp].

Use case 2.1: Tạo template SMS với Brandname đã đăng ký → Nhập nội dung (tối đa 160 ký tự/1 tin) → Lưu và kích hoạt ngay (không cần duyệt từ bên thứ ba).
Use case 2.2: Nội dung dài hơn 160 ký tự → Hệ thống thông báo số lượng tin sẽ bị tính (ví dụ: 2 tin SMS), hiển thị chi phí ước tính.

Cài đặt template SMS:

Field	Loại	Bắt buộc	Mô tả
Tên template	Text	✅	Tên nội bộ
Brandname	Dropdown	✅	Chọn từ danh sách Brandname đã đăng ký với nhà mạng
Nội dung	Textarea	✅	Tối đa 500 ký tự (tự tính số SMS sẽ bị charge)
Biến động	—	❌	Hỗ trợ ``

Tính năng 3: Tạo chiến dịch gửi tin

User story: Là một [Marketing Ops], tôi muốn [tạo chiến dịch broadcast đến tập KH đã lọc với template phù hợp] để [tiếp cận đúng đối tượng đúng thời điểm].

Use case 3.1 (Happy path): Tạo chiến dịch → Chọn loại kênh (ZNS / SMS / ZNS với fallback SMS) → Chọn template đã duyệt → Chọn tập KH → Map biến động → Lên lịch gửi → Xác nhận và kích hoạt.
Use case 3.2 (Preview trước khi gửi): Hệ thống hiển thị preview tin nhắn đã điền biến động với dữ liệu mẫu của 1 KH → Người dùng xác nhận đúng nội dung.

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

Field	Loại	Bắt buộc	Mô tả
Tên chiến dịch	Text	✅
Kênh gửi	Dropdown	✅	ZNS / SMS / ZNS + Fallback SMS
Template	Dropdown	✅	Chỉ hiển thị template `Approved` (với ZNS) hoặc `Active` (với SMS)
Tập khách hàng	Chọn / Lọc	✅	Bộ lọc CRM hoặc import file
Mapping biến động	Bảng mapping	✅ nếu có biến	Map biến `` → Field trong CRM
Thời gian gửi	Datetime picker	✅	Gửi ngay hoặc lên lịch
Giới hạn tốc độ	Number	❌	Tin/giây (để tránh vượt quota Zalo)

Tính năng 4: Cá nhân hóa tin nhắn (Biến động)

Ví dụ template ZNS với biến:

Xin chào ,
Đơn hàng  của bạn đã được xác nhận.
Tổng tiền:  VNĐ.
Giao hàng dự kiến: .

Bảng mapping biến động:

Biến trong template	Ánh xạ từ CRM field
``	Contact → Họ và tên
``	Deal → Mã đơn hàng
``	Deal → Tổng giá trị
``	Deal → Ngày giao hàng

Nghiệp vụ: Nếu biến không có giá trị cho một KH cụ thể, hệ thống có thể: (a) bỏ qua biến đó (để trống), (b) dùng giá trị mặc định đã cấu hình, hoặc (c) bỏ qua KH đó và ghi log.

Tính năng 5: Xử lý Fallback ZNS → SMS

User story: Là một [Marketing Manager], tôi muốn [tin nhắn tự động chuyển sang SMS nếu ZNS thất bại] để [đảm bảo KH vẫn nhận được thông báo dù không dùng Zalo].

Các trường hợp ZNS thất bại trigger Fallback:

Lý do thất bại ZNS	Hành động
KH chưa follow Zalo OA (với template Khuyến mãi)	Gửi SMS thay thế
SĐT không liên kết tài khoản Zalo	Gửi SMS thay thế
Quota ZNS vượt giới hạn	Hàng đợi → Thử lại sau / gửi SMS
Lỗi hệ thống Zalo (5xx)	Retry 3 lần → Fallback SMS

Use case 5.1: Gửi ZNS → Nhận callback FAILED từ Zalo API → Trong vòng 60 giây, hệ thống tự động gửi SMS thay thế với nội dung đã được cấu hình sẵn → Ghi nhận trong báo cáo là “ZNS thất bại / SMS thành công”.

Tính năng 6: Báo cáo chiến dịch

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

Chỉ số	ZNS	SMS
Tổng gửi	✅	✅
Gửi thành công (Delivered)	✅	✅
Gửi thất bại	✅	✅
Đã mở (Opened)	✅	❌
Click CTA	✅	❌
Fallback sang SMS	✅	—
Chi phí ước tính	✅	✅
Chi phí thực tế	Theo invoice Zalo	Theo invoice nhà mạng

3. Danh sách nghiệp vụ

Chỉ template ZNS ở trạng thái Approved mới được dùng trong chiến dịch.
Không được gửi tin khuyến mãi ZNS cho KH chưa follow Zalo OA — cần kiểm tra trước khi gửi.
Tần suất gửi ZNS cho cùng một SĐT không vượt quá giới hạn của Zalo OA (thường 4 tin/ngày, tùy loại template).
SMS Brandname phải được đăng ký với nhà mạng trước khi sử dụng.
Tin nhắn không được gửi ngoài khung giờ 7:00–21:00 theo quy định.
Mỗi lần gửi chiến dịch phải ghi nhận đầy đủ: template đã dùng, số phiên bản, timestamp gửi.
Chi phí được tính theo số tin gửi thành công (không tính tin thất bại với ZNS, tính cả thất bại với SMS tùy nhà mạng).

4. Giao diện

Trang Template: Tab “ZNS” và “SMS”, bảng danh sách template với cột Tên, Loại, Trạng thái, Ngày duyệt. Nút “Tạo template mới” và “Gửi duyệt lại”.
Trang chiến dịch: Wizard tạo chiến dịch 4 bước: (1) Thông tin → (2) Template & Kênh → (3) Tập KH & Mapping biến → (4) Lên lịch & Xác nhận.
Trang báo cáo: Cards tổng hợp + biểu đồ delivery funnel (Gửi → Thành công → Mở → Click).

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

Throughput: Hệ thống phải xử lý ≥ 10,000 tin ZNS/phút và ≥ 5,000 SMS/phút.
Latency callback: Xử lý callback kết quả gửi từ Zalo API trong ≤ 5 giây.
Fallback time: Khi ZNS thất bại, SMS fallback phải được kích hoạt trong ≤ 60 giây.
Retry policy: ZNS lỗi tạm thời (503): retry tối đa 3 lần với exponential backoff (30s, 1m, 2m).
Quota management: Tự động throttle tốc độ gửi để không vượt quota ZNS OA của từng tài khoản.
Audit trail: Lưu log đầy đủ mỗi tin gửi: template version, SĐT đích, thời gian gửi, kết quả.

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

Zalo OA API: Gửi tin ZNS, quản lý template, nhận callback delivery.
SMS Gateway (eSMS / VNPT / FPT Telecom hoặc tương đương): Gửi SMS Brandname.
CRM – Contact Management: Nguồn dữ liệu KH và biến động.
Campaign Library: Chia sẻ template giữa các chiến dịch.
Adaflow: Trigger và action node liên quan đến ZNS/SMS.
dev/campaign/zns_sms/template.md — Đặc tả riêng cho module Template.

V. API Contract (Dev viết)

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

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

Request Body:

{
  "name": "Khuyến mãi Flash Sale 7/7",
  "channel": "zns_with_sms_fallback",
  "template_id": "tpl_zns_001",
  "contact_filter": { "tag": "loyal_customer" },
  "variable_mapping": {
    "ten_khach_hang": "contact.full_name",
    "ma_khuyen_mai": "static:FLASHSALE7"
  },
  "scheduled_at": "2026-07-07T08:00:00+07:00"
}

Response 201: { "id": "camp_zns_001", "status": "scheduled", "estimated_recipients": 3500 }

API 2: Webhook callback từ Zalo

Method & Endpoint: POST /api/v1/webhooks/zalo/delivery (Zalo gọi vào)

Payload:

{
  "message_id": "zns_msg_001",
  "phone": "0901234567",
  "status": "received",
  "timestamp": 1720310400
}

API 3: Lấy báo cáo chiến dịch

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

Response 200:

{
  "total_sent": 3500,
  "delivered": 3100,
  "failed_zns": 400,
  "fallback_sms_sent": 350,
  "fallback_sms_delivered": 340,
  "opened": 2200,
  "clicked_cta": 800,
  "estimated_cost_vnd": 3500000
}

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

Template ZNS:

TC1.1: Tạo template với biến `` → Gửi duyệt Zalo → Trạng thái chuyển Pending Review.
TC1.2: Zalo từ chối → Trạng thái Rejected, hiển thị lý do từ chối từ Zalo.
TC1.3: Template Pending Review không xuất hiện trong dropdown tạo chiến dịch.

Tạo chiến dịch & Cá nhân hóa:

TC2.1: Template có biến ``, KH có field “Họ và tên” = “Nguyễn Văn A” → Preview hiển thị đúng “Nguyễn Văn A”.
TC2.2: KH không có dữ liệu cho biến → Hệ thống dùng giá trị mặc định hoặc ghi log bỏ qua.

Fallback:

TC3.1: KH không dùng Zalo → ZNS trả về FAILED → Trong 60 giây, SMS được gửi → Báo cáo ghi “SMS fallback: Thành công”.
TC3.2: Cả ZNS và SMS đều thất bại → Báo cáo ghi “Thất bại hoàn toàn” kèm lý do.

Giới hạn & Tuân thủ:

TC4.1: Lên lịch gửi lúc 22:00 → Hệ thống cảnh báo ngoài khung giờ cho phép và từ chối lên lịch.
TC4.2: Gửi vượt quota Zalo OA → Hệ thống throttle và hàng đợi, không bị lỗi batch.