Trigger Node - Integration - Khách hàng chiến dịch Callbot

I. Tổng quan

Node trigger Khách hàng chiến dịch Callbot khởi phát flow khi có sự kiện liên quan đến khách hàng trong một chiến dịch Callbot cụ thể: khi khách hàng mới được thêm vào chiến dịch, hoặc khi thông tin khách hàng hiện có trong chiến dịch được cập nhật và thỏa mãn điều kiện đã định.

1. Vấn đề

Các flow chăm sóc khách hàng, remarketing hoặc sau-cuộc-gọi thường cần phản ứng ngay tức thì khi có khách hàng mới vào chiến dịch Callbot, hoặc khi trạng thái/thông tin của khách hàng trong chiến dịch thay đổi (ví dụ: kết quả cuộc gọi, label được cập nhật).
Nếu không có trigger tích hợp, người vận hành phải tự kiểm tra và kích hoạt flow thủ công, gây trễ và không nhất quán trong luồng tự động.

2. Giải pháp

Cung cấp trigger Khách hàng chiến dịch Callbot với 2 hành động trigger:
- Khách hàng mới thêm vào chiến dịch: Khởi phát flow khi có khách hàng mới được thêm vào chiến dịch.
- Khách hàng được cập nhật thông tin: Khởi phát flow khi khách hàng của chiến dịch được cập nhật thông tin thỏa mãn điều kiện đã cấu hình.

3. Đối tượng

Người cấu hình automation: sales ops, marketing ops, CX team cần xây dựng flow phản ứng theo sự kiện của chiến dịch Callbot.
Admin vận hành chiến dịch cần tự động hóa các bước xử lý sau khi khách hàng vào chiến dịch hoặc sau khi thông tin khách hàng thay đổi.

4. Tầm nhìn/insight

Trong tương lai có thể mở rộng thêm các hành động trigger như Khi kết quả cuộc gọi được cập nhật, Khi khách hàng bị xóa khỏi chiến dịch, hoặc trigger có phạm vi theo nhóm chiến dịch thay vì từng chiến dịch đơn lẻ.

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

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

Loại node: Trigger.
Nhóm node: Integration.
2 hành động trigger:

#	Hành động trigger	Mô tả ngắn
1	`Khách hàng mới thêm vào chiến dịch`	Khởi phát flow khi một khách hàng mới được thêm vào chiến dịch Callbot
2	`Khách hàng được cập nhật thông tin`	Khởi phát flow khi khách hàng của chiến dịch được cập nhật và thỏa mãn điều kiện đã cấu hình

2. Đặc tả chi tiết

Hành động trigger 1: Khách hàng mới thêm vào chiến dịch

User story: Là một [Người cấu hình flow], tôi muốn [khởi phát flow tự động ngay khi có khách hàng mới được thêm vào chiến dịch Callbot] để [thực hiện ngay các bước tiếp theo như ghi nhận, thông báo hoặc phân loại mà không cần thao tác tay].

Use case 1.1 (Happy path – Trigger thành công): User cấu hình trigger Khách hàng mới thêm vào chiến dịch → Chọn chiến dịch Callbot đích → Cấu hình điều kiện lọc bổ sung nếu cần → Xuất bản flow → Khi có khách hàng mới được thêm vào chiến dịch và thỏa mãn điều kiện, hệ thống tạo flow run mới với dữ liệu khách hàng đó làm input đầu tiên.
Use case 1.2 (Happy path – Không cấu hình điều kiện lọc): Không cấu hình điều kiện lọc bổ sung → Flow được khởi phát với mọi khách hàng mới thêm vào chiến dịch, không phân biệt đặc điểm.
Use case 1.3 (Happy path – Cấu hình điều kiện lọc, khách hàng không thỏa điều kiện): Có cấu hình điều kiện lọc → Khách hàng mới được thêm vào chiến dịch nhưng không thỏa điều kiện → Hệ thống không khởi phát flow run cho khách hàng đó.
Use case 1.4 (Exception – Chưa chọn chiến dịch): Dropdown chiến dịch chưa được chọn → Node ở trạng thái lỗi cấu hình → Flow không được xuất bản.

Cài đặt:

Field	Tab	Loại	Bắt buộc	Mô tả
Chọn hành động trigger	Trigger	Dropdown / List	✅	Chọn `Khách hàng mới thêm vào chiến dịch`.
Chiến dịch Callbot	Cài đặt	Dropdown	✅	Chọn chiến dịch Callbot cần theo dõi. Hệ thống chỉ hiển thị các chiến dịch hợp lệ đang tồn tại.
Kích hoạt khi khách hàng mới đáp ứng các điều kiện sau – `Điều kiện thỏa mãn`	Cài đặt	Dropdown	❌	Chọn logic áp dụng cho nhiều điều kiện: Tất cả (AND) hoặc Bất kỳ (OR).
→ Mỗi hàng điều kiện	Cài đặt	Row	❌	Trường lọc → Toán tử (`là`, `khác`, `chứa`, …) → Giá trị (cố định). Ví dụ: `Label là Lạnh`.
Nút `+`	Cài đặt	—	—	Thêm hàng điều kiện mới vào bộ lọc.

Bộ lọc điều kiện cho phép thu hẹp tập khách hàng sẽ kích hoạt trigger. Nếu không cấu hình điều kiện, flow được khởi phát với toàn bộ khách hàng mới thêm vào chiến dịch.

Đầu ra (dữ liệu truyền vào flow):

Thông tin khách hàng vừa được thêm vào chiến dịch (các field được cấu hình trong Bước 2 – Danh sách khách hàng của chiến dịch).
ID khách hàng trong chiến dịch.
Thời điểm được thêm vào chiến dịch.

Hành động trigger 2: Khách hàng được cập nhật thông tin

User story: Là một [Người cấu hình flow], tôi muốn [khởi phát flow khi khách hàng trong chiến dịch Callbot được cập nhật thông tin thỏa mãn điều kiện đã định] để [tự động phản ứng với thay đổi trạng thái hoặc dữ liệu khách hàng theo thời gian thực].

Use case 2.1 (Happy path – Trigger thành công): User cấu hình trigger Khách hàng được cập nhật thông tin → Chọn chiến dịch → Cấu hình điều kiện (ví dụ: Label là Lạnh) → Xuất bản flow → Khi khách hàng trong chiến dịch được cập nhật và sau khi cập nhật thỏa mãn điều kiện, hệ thống tạo flow run mới.
Use case 2.2 (Happy path – Không cấu hình điều kiện lọc): Không cấu hình điều kiện → Flow được khởi phát với mọi cập nhật thông tin khách hàng trong chiến dịch.
Use case 2.3 (Happy path – Khách hàng được cập nhật nhưng không thỏa điều kiện): Khách hàng được cập nhật thông tin → Sau khi cập nhật không thỏa điều kiện đã cấu hình → Hệ thống không khởi phát flow run.
Use case 2.4 (Exception – Chưa chọn chiến dịch): Dropdown chiến dịch chưa được chọn → Node ở trạng thái lỗi cấu hình → Flow không được xuất bản.

Cài đặt:

Field	Tab	Loại	Bắt buộc	Mô tả
Chọn hành động trigger	Trigger	Dropdown / List	✅	Chọn `Khách hàng được cập nhật thông tin`.
Chiến dịch Callbot	Cài đặt	Dropdown	✅	Chọn chiến dịch Callbot cần theo dõi. Hệ thống chỉ hiển thị các chiến dịch hợp lệ đang tồn tại.
Sau khi cập nhật, khách hàng thỏa mãn yêu cầu sau – `Điều kiện thỏa mãn`	Cài đặt	Dropdown	❌	Chọn logic áp dụng cho nhiều điều kiện: Tất cả (AND) hoặc Bất kỳ (OR).
→ Mỗi hàng điều kiện	Cài đặt	Row	❌	Trường lọc → Toán tử (`là`, `khác`, `chứa`, …) → Giá trị (cố định). Ví dụ: `Label là Lạnh`.
Nút `+`	Cài đặt	—	—	Thêm hàng điều kiện mới vào bộ lọc.

Điều kiện lọc được đánh giá dựa trên giá trị sau khi cập nhật của khách hàng, không phải giá trị trước khi cập nhật. Tức là chỉ những khách hàng có trạng thái thỏa mãn điều kiện ở thời điểm hiện tại mới kích hoạt trigger.

Đầu ra (dữ liệu truyền vào flow):

Thông tin khách hàng sau khi được cập nhật (các field được cấu hình trong Bước 2 – Danh sách khách hàng của chiến dịch).
ID khách hàng trong chiến dịch.
Thời điểm cập nhật.

3. Danh sách nghiệp vụ

Người dùng phải chọn một hành động trigger hợp lệ; nếu chưa chọn thì node ở trạng thái chưa cấu hình.
Chiến dịch được chọn phải đang tồn tại và hợp lệ; chiến dịch đã bị xóa không được hiển thị trong dropdown.
Field bắt buộc (Chiến dịch) chưa được điền thì node bị đánh dấu lỗi cấu hình và flow không được xuất bản.
Điều kiện lọc là tùy chọn; nếu không cấu hình, trigger phản ứng với toàn bộ sự kiện của loại đó trong chiến dịch đã chọn.
Mỗi flow run được tạo ra sẽ gắn với một khách hàng cụ thể; dữ liệu khách hàng đó là input đầu tiên của flow.
Trigger không tự retry; nếu flow run thất bại, hệ thống ghi nhận lỗi trong run detail, không kích hoạt lại tự động.
Nếu flow ở trạng thái paused hoặc inactive, trigger không khởi phát run mới kể cả khi có sự kiện đáp ứng điều kiện.

4. Giao diện

Card node hiển thị nhãn Callbot, tóm tắt Hành động trigger đang chọn và tên Chiến dịch đang liên kết.
Panel cấu hình bên phải gồm 3 tab: Trigger, Cài đặt, Đầu ra.
- Tab Trigger: Thanh tìm kiếm + danh sách 2 hành động trigger; hành động đang chọn được highlight.
- Tab Cài đặt: Form cấu hình tương ứng với hành động trigger đang chọn (chọn chiến dịch, cấu hình điều kiện lọc).
- Tab Đầu ra: Hiển thị schema output của trigger để node sau có thể tham chiếu.

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

Độ trễ: Trigger phải khởi phát flow run trong vòng tối đa 5 giây kể từ khi sự kiện xảy ra trong hệ thống.
Logging: Mọi lần trigger được kích hoạt phải được ghi log đầy đủ: thời điểm sự kiện, chiến dịch liên quan, khách hàng, hành động trigger và kết quả (run được tạo thành công hay bị bỏ qua do không thỏa điều kiện).
Tính nhất quán: Danh sách chiến dịch trong panel phải được đồng bộ từ hệ thống UCALL theo thời gian thực hoặc có cơ chế refresh để tránh hiển thị dữ liệu cũ.
Tránh lặp: Hệ thống cần có cơ chế đảm bảo không tạo run trùng lặp nếu cùng một sự kiện được phát nhiều lần do lỗi hệ thống.

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

flow.md
node_overview.md
Action Node - Chiến dịch Callbot
Module Chiến dịch Callbot của UCALL (quản lý campaign, danh sách khách hàng)

V. API Contract (Dev viết)

Chưa chốt API chi tiết.

Dự kiến trigger sẽ subscribe vào event stream nội bộ của module Chiến dịch Callbot với structure chung:

{
  "trigger": "CALLBOT_CUSTOMER_ADDED | CALLBOT_CUSTOMER_UPDATED",
  "campaign_id": "string",
  "customer": {
    "id": "string",
    "phone_number": "string",
    "fields": {}
  },
  "event_at": "datetime"
}

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

Hành động trigger 1 – Khách hàng mới thêm vào chiến dịch:

TC1.1: Thêm khách hàng mới vào chiến dịch → Flow run được tạo, input là dữ liệu khách hàng vừa thêm.
TC1.2: Cấu hình điều kiện Label là Lạnh, thêm khách hàng có label Lạnh → Flow run được tạo.
TC1.3: Cấu hình điều kiện Label là Lạnh, thêm khách hàng có label Nóng → Flow run không được tạo.
TC1.4: Không cấu hình điều kiện, thêm khách hàng bất kỳ → Flow run được tạo.
TC1.5: Chưa chọn chiến dịch → Node ở trạng thái lỗi cấu hình, flow không xuất bản.
TC1.6: Flow ở trạng thái paused, thêm khách hàng mới → Không tạo flow run.

Hành động trigger 2 – Khách hàng được cập nhật thông tin:

TC2.1: Cập nhật thông tin khách hàng, sau cập nhật thỏa điều kiện Label là Lạnh → Flow run được tạo.
TC2.2: Cập nhật thông tin khách hàng, sau cập nhật không thỏa điều kiện → Flow run không được tạo.
TC2.3: Không cấu hình điều kiện, cập nhật bất kỳ thông tin khách hàng → Flow run được tạo.
TC2.4: Chưa chọn chiến dịch → Node ở trạng thái lỗi cấu hình, flow không xuất bản.
TC2.5: Điều kiện Thỏa mãn = Tất cả, 2 điều kiện, cả 2 đều thỏa sau cập nhật → Flow run được tạo.
TC2.6: Điều kiện Thỏa mãn = Tất cả, 1 điều kiện thỏa, 1 không thỏa → Flow run không được tạo.
TC2.7: Flow ở trạng thái paused, khách hàng được cập nhật → Không tạo flow run.