Kiến trúc tổng quát

flowchart TD
    A[Hồ sơ chat] --> B[Khóa nhúng]
    A --> C[Cấu hình widget]
    A --> D[Cấu hình chatbot]
    A --> E[Quy tắc thông tin khách hàng]
    A --> F[Thành viên phụ trách]
    A --> G[Danh sách nguồn được phép]

    B --> H[Website hoặc iframe]
    H --> I[Tạo kênh hỗ trợ]
    I --> J[Gắn hồ sơ vào kênh]
    F --> J
    D --> K[Chatbot trả lời trong kênh]

Mô hình dữ liệu

Loại hồ sơ

• CHAT_WIDGET: cấu hình widget chat được nhúng vào website.
• CHATBOT: hồ sơ dành cho ngữ cảnh chatbot.

Trạng thái hồ sơ

stateDiagram-v2
    [*] --> ACTIVATED: Tạo mới
    ACTIVATED --> INACTIVATED: Ngừng sử dụng
    INACTIVATED --> ACTIVATED: Kích hoạt lại
    ACTIVATED --> [*]: Xóa
    INACTIVATED --> [*]: Xóa

Đang hoạt động

• Tải widget bằng khóa nhúng.
• Mở trang chat hỗ trợ theo hồ sơ.
• Tạo kênh hỗ trợ từ nguồn nhúng.
• Lấy cấu hình chatbot theo kênh.
• Kiểm tra thành viên đang phụ trách hồ sơ.

Ngừng hoạt động

• Xóa widget khỏi các website đã nhúng.
• Xóa các kênh đã tạo.
• Xóa thành viên hồ sơ.
• Ngừng các cuộc hội thoại đang tồn tại.
• Gỡ hồ sơ khỏi các kênh đã liên kết.

Xóa hồ sơ

• Thành viên hồ sơ.
• Kênh đang tham chiếu đến hồ sơ.
• Tin nhắn trong các kênh đó.

Danh sách hồ sơ chat

• ID.
• Tên hồ sơ.
• URL website.
• Loại hồ sơ.
• Khóa nhúng.
• Dịch vụ chatbot.
• Trạng thái.
• Các thao tác xem, lấy mã nhúng, sửa và xóa.

• Loại hồ sơ.
• Trạng thái.
• Từ khóa.
• Số bản ghi mỗi trang.

Tìm kiếm hồ sơ

• Tìm theo phần đầu tên hồ sơ.
• Tìm bằng khóa nhúng.
• Gợi ý hồ sơ khi nhập từ khóa.

• Nhấn Enter để thực hiện tìm kiếm.
• Xóa toàn bộ từ khóa để tự động tải lại danh sách.
• Từ khóa và các bộ lọc được đồng bộ vào URL trình duyệt.

Phân trang

• Trang đầu.
• Trang trước.
• Trang tiếp theo.
• Trang cuối.
• ID tăng dần.
• ID giảm dần.

Tạo hồ sơ

1. Nhận cấu hình từ biểu mẫu.
2. Sinh một khóa nhúng ngẫu nhiên.
3. Áp dụng loại mặc định nếu thiếu.
4. Áp dụng trạng thái mặc định nếu thiếu.
5. Lưu hồ sơ.
6. Ghi nhận thời gian tạo và cập nhật.
7. Chuyển người quản trị đến trang chi tiết.

Thông tin cơ bản

Tên hồ sơ

• Website bán hàng.
• Trang hỗ trợ kỹ thuật.
• Cổng khách hàng doanh nghiệp.
• Widget tư vấn sản phẩm.

URL website

• Được hiển thị trong danh sách và trang chi tiết.
• Được chuyển xuống cấu hình widget.
• Có thể được dùng làm đường dẫn liên quan trong trải nghiệm phía người dùng.

Khóa nhúng

• Tải đúng cấu hình widget.
• Mở trang hỗ trợ đúng hồ sơ.
• Xác định hồ sơ khi tạo kênh.
• Liên kết kênh chat với cấu hình tương ứng.

Mã nhúng widget

<script
    src="https://chat.example.com/ezychat/js/embed.js"
    data-profile="EMBED_KEY"
    data-lang="default"
    data-style=""
    async>
</script>

• src trỏ tới script widget của hệ thống chat.
• data-profile chứa khóa của hồ sơ.
• data-lang chọn ngôn ngữ.
• data-style dành cho tùy chỉnh kiểu hiển thị.
• async giúp script không chặn quá trình tải trang chính.

Iframe hỗ trợ

<iframe
    src="https://chat.example.com/ezychat/support?profile=EMBED_KEY&lang=default&style="
    title="Support Chat"
    width="100%"
    height="700"
    frameborder="0"
    allow="clipboard-write">
</iframe>

• Sao chép đoạn iframe.
• Mở thử giao diện hỗ trợ trong tab mới.
• Dùng iframe trong trang nội bộ hoặc một bố cục tùy chỉnh.

Xác thực nguồn nhúng

1. Tìm hồ sơ theo khóa.
2. Kiểm tra hồ sơ đang hoạt động.
3. Lấy header Origin.
4. Nếu không có Origin, suy ra origin từ Referer.
5. Kiểm tra origin có nằm trong danh sách được phép hay không.

scheme://host[:port]

https://example.com
https://support.example.com
http://localhost:3000

Cấu hình giao diện widget

Kiểu nút

• Hình tròn.
• Hình vuông bo góc.
• Hình vuông.

Vị trí

• Bên phải.
• Bên trái.

Kích thước

• Nhỏ.
• Trung bình.
• Lớn.

Màu sắc

• Chọn màu bằng color picker.
• Nhập mã màu dạng hex.
• Chọn một trong các màu gợi ý.

• Màu chính của launcher.
• Gradient của nút.
• Màu nền tin nhắn do khách hàng gửi.

Ảnh launcher

Hiệu ứng launcher

Ảnh nhân viên hỗ trợ

Phương thức truyền tin

• Socket.
• HTTP.

• Bật: lưu phương thức SOCKET.
• Tắt: lưu phương thức HTTP.

Socket

• Nhận tin ngay lập tức.
• Gửi trạng thái đang nhập.
• Nhận trạng thái chatbot.
• Duy trì kết nối lâu dài.

HTTP

Thu thập thông tin khách hàng

• Yêu cầu nhập thông tin trước khi chat.
• Bắt buộc email.
• Bắt buộc số điện thoại.
• Mật khẩu và xác nhận mật khẩu trên biểu mẫu đăng ký.

• Tên hiển thị.
• Email.
• Số điện thoại.
• Mật khẩu tùy chọn.
• Xác nhận mật khẩu.

• Chế độ yêu cầu thông tin được bật.
• Trường tương ứng được cấu hình là bắt buộc.

Quyền đính kèm tệp

• Nút đính kèm.
• Ô chọn nhiều tệp.
• Chức năng tải tài nguyên trước khi gửi tin.

Cấu hình chatbot

• Dịch vụ chatbot.
• System message riêng.

1. Hệ thống tìm hồ sơ đang hoạt động gắn với kênh.
2. Nếu tìm thấy, dùng dịch vụ chatbot của hồ sơ.
3. Nếu không tìm thấy hồ sơ hoạt động, thử dùng cấu hình chatbot mặc định toàn hệ thống.
4. Lấy các tin gần nhất làm ngữ cảnh.
5. Dùng system message của hồ sơ nếu có.
6. Nếu system message của hồ sơ trống, dùng system message mặc định.
7. Gửi yêu cầu streaming đến dịch vụ chatbot.
8. Phát từng phần câu trả lời về client.
9. Lưu câu trả lời hoàn chỉnh thành tin nhắn.

sequenceDiagram
    participant U as Khách hàng
    participant C as Kênh chat
    participant P as Hồ sơ chat
    participant B as Dịch vụ chatbot

    U->>C: Gửi câu hỏi
    C->>P: Lấy hồ sơ đang hoạt động
    P-->>C: Dịch vụ bot và system message
    C->>B: Gửi câu hỏi cùng lịch sử gần nhất
    B-->>C: Streaming nội dung trả lời
    C-->>U: Hiển thị nội dung đang sinh
    C->>C: Lưu câu trả lời hoàn chỉnh

Liên kết hồ sơ với kênh

1. Máy chủ xác thực khóa và origin.
2. Tìm hoặc tạo kênh hỗ trợ.
3. Gắn ID hồ sơ vào kênh.
4. Thêm khách hàng vào kênh.
5. Thêm đội hỗ trợ toàn cục.
6. Thêm các thành viên đang hoạt động của hồ sơ.
7. Có thể thêm chatbot.
8. Trả về thông tin kênh cho widget.

sequenceDiagram
    participant W as Widget
    participant V as Bộ kiểm tra hồ sơ
    participant P as Hồ sơ chat
    participant C as Dịch vụ kênh
    participant M as Thành viên

    W->>V: Gửi khóa nhúng và origin
    V->>P: Tìm hồ sơ đang hoạt động
    P-->>V: Cấu hình hồ sơ
    V->>V: Kiểm tra origin
    V->>C: Tìm hoặc tạo kênh hỗ trợ
    C->>C: Gắn hồ sơ vào kênh
    P->>M: Lấy thành viên đang hoạt động
    M->>C: Thêm thành viên vào kênh
    C-->>W: Trả về ID kênh

• Xác định nguồn của hội thoại.
• Dùng cấu hình chatbot tương ứng.
• Lọc danh sách chat theo hồ sơ.
• Kiểm tra thành viên chuyên trách.
• Hiển thị thông tin hồ sơ trong chi tiết kênh.

Thành viên hồ sơ

• Loại thành viên.
• ID thành viên.
• Vai trò.
• Trạng thái.
• Thời gian tạo và cập nhật.

• Người dùng.
• Quản trị viên.

• ACTIVATED: được đưa vào các kênh mới của hồ sơ.
• INACTIVATED: giữ bản ghi nhưng không được đưa vào kênh mới.

• Thêm thành viên.
• Sửa danh tính, vai trò hoặc trạng thái.
• Xóa phân công.
• Duyệt danh sách bằng cursor.

Trang chi tiết hồ sơ

• Thông tin cơ bản.
• Trạng thái.
• Khóa nhúng.
• Đoạn script nhúng.
• Đoạn iframe hỗ trợ.
• Cấu hình chatbot.
• Cấu hình giao diện.
• Cấu hình thu thập thông tin.
• Quyền đính kèm tệp.
• Danh sách thành viên.
• Thao tác sửa và xóa.

Cập nhật hồ sơ

• Khóa nhúng được giữ nguyên.
• Thời gian cập nhật được thay đổi.
• Các thuộc tính trong biểu mẫu được ghi đè vào hồ sơ.
• Quản trị viên được chuyển về trang chi tiết sau khi lưu.

Trang trí bằng nội dung

• Nhập từ biểu mẫu.
• Lưu vào hồ sơ.
• Hiển thị trên trang chi tiết.

Quan hệ dữ liệu

erDiagram
    CHAT_PROFILE ||--o{ CHAT_PROFILE_MEMBER : "có thành viên"
    CHAT_PROFILE ||--o{ CHANNEL : "cấu hình cho"
    CHANNEL ||--o{ MESSAGE : "chứa"
    CHAT_PROFILE ||--o{ DATA_META : "có metadata"

    CHAT_PROFILE {
        long id
        string type
        string embedKey
        string name
        string webUrl
        string status
        string chatBotServiceName
        string chatTransportType
        string systemMessage
    }

    CHAT_PROFILE_MEMBER {
        long chatProfileId
        string memberType
        long memberId
        string roleName
        string status
    }

    CHANNEL {
        long id
        long chatProfileId
        string status
    }

    DATA_META {
        string metaKey
        string metaValue
    }

Bảo mật

Khóa nhúng không phải bí mật tuyệt đối

• Hồ sơ phải đang hoạt động.
• Kiểm tra origin.
• Xác thực người dùng khi tạo hoặc truy cập kênh.
• Kiểm tra thành viên kênh.
• Giới hạn upload.
• Kiểm tra quyền gửi tin.

Origin và Referer

Không dùng URL website thay cho allowlist

Giới hạn và điểm cần lưu ý

Chưa có giao diện quản lý origin

• Không có trường nhập origin.
• Không có API quản trị origin.
• Không thấy lời gọi lưu origin.

Cấu hình “yêu cầu thông tin người dùng” chưa được lưu

• Checkbox được gửi từ giao diện nhưng không được lưu.
• Giá trị đọc lại luôn rỗng hoặc không đúng mong đợi.
• Widget bỏ qua biểu mẫu thông tin và đăng ký khách ngẫu nhiên.
• Hai tùy chọn bắt buộc email và điện thoại chỉ có tác dụng khi cờ tổng được bật, nên cũng có thể mất tác dụng.

Loại hồ sơ chưa chỉnh sửa được

• Form không có trường loại.
• Request lưu không có loại.
• Hồ sơ mới luôn dùng CHAT_WIDGET.
• Không thể tạo CHATBOT từ màn hình hiện tại.

Không thể thay hoặc thu hồi khóa nhúng

• Tạo lại khóa.
• Thu hồi khóa cũ.
• Dùng song song nhiều khóa.
• Đặt thời hạn cho khóa.

Xóa hồ sơ có nguy cơ để lại quan hệ mồ côi

• Bị từ chối.
• Để lại dữ liệu tham chiếu tới ID không còn tồn tại.
• Làm các kênh rơi về cấu hình chatbot mặc định.

Chưa kiểm tra dữ liệu cấu hình chuyên biệt

• Tên không rỗng.
• URL website hợp lệ.
• Màu đúng định dạng.
• Dịch vụ chatbot tồn tại.
• Trạng thái thuộc tập cho phép.
• Kiểu nút, vị trí và kích thước hợp lệ.
• ID nội dung trang trí tồn tại.
• Quan hệ hợp lệ giữa “yêu cầu thông tin” và “bắt buộc email/điện thoại”.

Thông tin đăng nhập được cấu hình chưa đầy đủ

• Request quản trị không có trường tương ứng.
• Biểu mẫu không có tùy chọn này.
• Converter không lưu giá trị này.
• Response widget cũng không trả cấu hình đó.

Các trường AI chưa được quản lý

Dịch vụ bot trống trên hồ sơ hoạt động

Thành viên chỉ được sao chép lúc tạo kênh

Khuyến nghị vận hành

1. Đặt tên thể hiện rõ website hoặc nhóm nghiệp vụ.
2. Chọn dịch vụ chatbot nếu cần.
3. Cấu hình system message theo phạm vi sử dụng.
4. Chọn giao diện launcher phù hợp.
5. Quyết định dùng HTTP hay socket.
6. Cấu hình yêu cầu thông tin khách hàng.
7. Quyết định có cho phép tải tệp không.
8. Kích hoạt hồ sơ.
9. Thêm thành viên phụ trách.
10. Cấu hình allowlist origin trước khi công khai khóa.
11. Sao chép mã nhúng và thử trên môi trường kiểm thử.
12. Kiểm tra kênh mới được gắn đúng hồ sơ và thành viên.

1. Chuyển hồ sơ sang INACTIVATED.
2. Gỡ mã nhúng khỏi website.
3. Kiểm tra các kênh đang hoạt động.
4. Thu hồi thành viên kênh nếu cần.
5. Chỉ xóa vật lý sau khi xử lý các quan hệ liên quan.

Kết luận

• Khóa nhúng riêng.
• Giao diện riêng.
• Phương thức truyền tin riêng.
• Chatbot và system message riêng.
• Quy tắc thu thập thông tin riêng.
• Chính sách đính kèm tệp riêng.
• Danh sách nhân viên phụ trách riêng.