EzyOA cho phép sử dụng một chatbot thống nhất để tự động trả lời tin nhắn từ Zalo OA, Facebook Messenger, Telegram Bot và các dịch vụ OA mở rộng. Mỗi dịch vụ có thể sử dụng một hồ sơ chatbot riêng, nhờ đó doanh nghiệp có thể thiết lập vai trò, nội dung hướng dẫn và mô hình AI khác nhau cho từng kênh.

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

EzyOA không gọi trực tiếp một nhà cung cấp AI cụ thể. Hệ thống nhận tin nhắn từ nền tảng OA, chuẩn hóa dữ liệu và chuyển yêu cầu sang EzyChat. EzyChat tiếp tục chọn dịch vụ chatbot phù hợp để tạo câu trả lời.

flowchart LR
    User["Người dùng"] --> OA["Zalo OA / Messenger / Telegram"]
    OA -->|Webhook| EzyOA["EzyOA"]
    EzyOA --> Channel["Kênh hội thoại"]
    Channel --> Profile["Hồ sơ chatbot"]
    Profile --> Bot["Dịch vụ chatbot"]
    Bot --> EzyOA
    EzyOA -->|Gửi câu trả lời| OA
    OA --> User

Cách tổ chức này tách ba trách nhiệm:

Nền tảng OA chịu trách nhiệm giao tiếp với người dùng.
EzyOA xử lý webhook, định danh người dùng, lưu hội thoại và gửi tin.
EzyChat cùng dịch vụ chatbot chịu trách nhiệm tạo câu trả lời.

Chatbot phía sau có thể là OpenAI, Gemini, Claude, một mô hình self-hosted hoặc bất kỳ dịch vụ nào tuân theo giao diện chatbot của EzyChat. Nếu sử dụng EzyAI, phần kết nối tới các nhà cung cấp AI đã được cung cấp sẵn và chủ yếu cần cấu hình trên giao diện quản trị.

Điều kiện cần chuẩn bị

Trước khi cấu hình chatbot, hệ thống cần có:

EzyOA trên cả trang quản trị và web runtime.
EzyChat trên cả trang quản trị và web runtime.
Một dịch vụ chatbot đang hoạt động.
Một hồ sơ chat đã được kích hoạt.
Một dịch vụ OA đã nhận và gửi được tin nhắn.
Webhook của OA đã đăng ký đúng và có thể truy cập từ Internet.

Việc chatbot hoạt động không thay thế bước tích hợp OA. Nếu EzyOA chưa nhận được webhook từ Zalo, Messenger hoặc Telegram thì chatbot cũng không nhận được câu hỏi.

Tạo hồ sơ chatbot

Trong trang quản trị EzyChat, mở phần quản lý Hồ sơ chat và tạo một hồ sơ mới.

Các thông tin quan trọng gồm:

Tên hồ sơ: dùng để nhận biết mục đích của chatbot.
Dịch vụ chatbot: chọn bộ kết nối tới nhà cung cấp AI.
System message: mô tả vai trò, phạm vi kiến thức và cách trả lời.
Trạng thái: phải ở trạng thái hoạt động.

Ví dụ system message cho một OA hỗ trợ khách hàng:

Bạn là trợ lý chăm sóc khách hàng của doanh nghiệp.

Trả lời bằng tiếng Việt, ngắn gọn và lịch sự.
Chỉ tư vấn về sản phẩm, đơn hàng và chính sách hỗ trợ.
Nếu không đủ thông tin, hãy đề nghị người dùng cung cấp mã đơn hàng
hoặc liên hệ nhân viên chăm sóc khách hàng.
Không tự tạo ra giá bán, chính sách hoặc trạng thái đơn hàng.

Mỗi mục đích nên có một hồ sơ riêng. Chẳng hạn, OA bán hàng có thể sử dụng hồ sơ tư vấn sản phẩm, trong khi Telegram Bot nội bộ sử dụng hồ sơ hỗ trợ kỹ thuật.

EzyOA chỉ sử dụng hồ sơ đang hoạt động. Nếu hồ sơ bị vô hiệu hóa hoặc đã bị xóa, tin nhắn đến vẫn có thể được lưu nhưng chatbot sẽ không tạo câu trả lời.

Bật phản hồi tự động

Trong phần cài đặt EzyOA, bật tùy chọn Phản hồi tự động.

Đây là công tắc chung quyết định EzyOA có chạy kịch bản phản hồi khi nhận tin nhắn văn bản hay không. Khi tắt tùy chọn này:

Webhook vẫn có thể được tiếp nhận.
Người dùng và kênh hội thoại vẫn được tạo.
Tin nhắn đến vẫn có thể được lưu.
Chatbot không được gọi.
EzyOA không tự động gửi câu trả lời.

Việc tắt phản hồi tự động phù hợp khi cần bảo trì chatbot hoặc chuyển toàn bộ hội thoại sang nhân viên chăm sóc khách hàng.

Gắn chatbot với dịch vụ OA

Mở trang chi tiết của dịch vụ OA cần tích hợp. Trong phần Kịch bản, thực hiện:

Chọn chat_bot tại trường phản hồi tin nhắn văn bản.
Chọn hồ sơ chatbot tại trường Mã hồ sơ chat.
Lưu cấu hình.

Trường mã hồ sơ sử dụng ID nội bộ của hồ sơ, không phải khóa nhúng dùng cho widget trên website. Giao diện hỗ trợ tìm và chọn hồ sơ thay vì yêu cầu nhập ID thủ công.

Tham số hồ sơ được lưu riêng theo từng dịch vụ OA. Vì vậy có thể cấu hình:

Dịch vụ OA	Hồ sơ chatbot
Zalo OA bán hàng	Tư vấn sản phẩm
Messenger	Chăm sóc khách hàng
Telegram Bot	Hỗ trợ kỹ thuật

Có một điểm quan trọng: loại kịch bản phản hồi văn bản là cấu hình dùng chung của EzyOA, còn hồ sơ chatbot là cấu hình riêng của từng dịch vụ. Khi chọn chat_bot, nên mở lần lượt từng dịch vụ OA và bảo đảm mỗi dịch vụ đều có một hồ sơ hợp lệ.

Nếu một dịch vụ không có mã hồ sơ, hồ sơ không hoạt động hoặc dịch vụ chatbot không khả dụng, EzyOA sẽ không tạo câu trả lời tự động cho dịch vụ đó.

Luồng xử lý tin nhắn

Khi người dùng gửi một tin nhắn văn bản, EzyOA xử lý theo luồng sau:

sequenceDiagram
    participant U as Người dùng
    participant P as Nền tảng OA
    participant O as EzyOA
    participant C as EzyChat
    participant B as Chatbot

    U->>P: Gửi tin nhắn
    P->>O: Gửi webhook
    O->>O: Xác định dịch vụ và người dùng
    O->>O: Tạo hoặc lấy kênh hội thoại
    O->>O: Kiểm tra phản hồi tự động
    O->>C: Gửi hồ sơ, lịch sử và câu hỏi
    C->>B: Yêu cầu tạo câu trả lời
    B-->>C: Trả nội dung
    C-->>O: Hoàn thành câu trả lời
    O->>P: Gửi tin nhắn phản hồi
    P-->>U: Hiển thị câu trả lời
    O->>O: Lưu lịch sử nếu được cấu hình

Yêu cầu gửi tới chatbot bao gồm:

Hồ sơ chatbot đã chọn cho dịch vụ OA.
System message của hồ sơ.
Tin nhắn hiện tại của người dùng.
Một phần lịch sử gần nhất trong cùng kênh hội thoại.
Định danh người hỏi.
Định danh kênh hội thoại.

Nhờ sử dụng kênh hội thoại, chatbot có thể duy trì ngữ cảnh giữa nhiều lượt trao đổi của cùng một người dùng.

Quản lý ngữ cảnh hội thoại

Số lượng tin nhắn được đưa vào ngữ cảnh phụ thuộc vào giới hạn chatbot trong EzyChat.

Nếu giới hạn là N, EzyOA lấy tối đa N - 1 tin nhắn gần nhất trong kênh rồi thêm câu hỏi hiện tại. Tổng số tin nhắn chuyển cho chatbot vì thế không vượt quá giới hạn đã cấu hình.

Giới hạn quá thấp có thể làm chatbot quên nội dung vừa trao đổi. Giới hạn quá cao làm tăng:

Số token gửi tới mô hình.
Chi phí gọi AI.
Thời gian phản hồi.
Nguy cơ đưa dữ liệu không còn cần thiết vào yêu cầu.

Nên bắt đầu với một giới hạn vừa phải, sau đó điều chỉnh dựa trên độ dài hội thoại thực tế.

Để lịch sử chứa cả hai phía của cuộc trò chuyện, nên bật lưu tin nhắn phản hồi của OA. Nếu chỉ lưu tin nhắn đến mà không lưu câu trả lời, ngữ cảnh ở lượt tiếp theo có thể thiếu phần chatbot đã trả lời trước đó.

Định dạng câu trả lời

Chatbot có thể trả về Markdown, nhưng các nền tảng OA không sử dụng chung một chuẩn Markdown. Trước khi gửi, EzyOA chuyển câu trả lời thành văn bản thuần.

Quá trình này loại bỏ hoặc đơn giản hóa các thành phần như:

Heading.
Dấu nhấn mạnh.
Blockquote.
Danh sách.
Liên kết Markdown.
Hình ảnh Markdown.
Khối mã và mã nội tuyến.
Thẻ HTML.

Ví dụ:

## Kết quả

Bạn có thể xem [hướng dẫn](https://example.com/guide).

được chuyển thành nội dung gần tương đương:

Kết quả

Bạn có thể xem hướng dẫn.

Do URL của liên kết Markdown có thể bị loại bỏ, system message nên yêu cầu chatbot xuất URL trực tiếp nếu người dùng cần bấm vào liên kết:

Khi cung cấp liên kết, hãy viết đầy đủ URL thay vì dùng Markdown.

Kịch bản chatbot mặc định tạo phản hồi văn bản. Nó không tự động biến Markdown, ảnh hoặc file do mô hình mô tả thành media message của OA.

Trạng thái đang nhập

Nếu dịch vụ OA hỗ trợ trạng thái đang nhập và đã cấu hình khoảng thời gian gửi trạng thái, EzyOA có thể phát tín hiệu “đang nhập” trong lúc chatbot tạo nội dung.

Tín hiệu được gửi:

Trước khi bắt đầu gọi chatbot.
Theo chu kỳ trong quá trình nhận dữ liệu phản hồi dạng stream.

Lỗi khi gửi trạng thái đang nhập không làm hỏng toàn bộ câu trả lời. Tuy nhiên, không phải nền tảng OA nào cũng hỗ trợ chức năng này giống nhau.

Những loại tin nhắn được chatbot xử lý

Kịch bản chatbot hiện chỉ được gọi khi webhook chứa nội dung văn bản hợp lệ và dịch vụ cho phép phản hồi.

EzyOA có thể tiếp nhận và lưu ảnh, file, video hoặc âm thanh nếu bật chức năng lưu media, nhưng media đứng riêng không được chuyển thành câu hỏi cho chatbot trong kịch bản mặc định.

Một tin nhắn chỉ chứa ảnh, file hoặc sticker vì thế có thể được lưu mà không nhận được phản hồi tự động. Nếu muốn chatbot phân tích hình ảnh hay tài liệu, cần xây dựng một kịch bản mở rộng có khả năng:

Tải hoặc đọc media.
Kiểm tra loại và kích thước file.
Chuyển media sang dịch vụ AI đa phương thức.
Tạo phản hồi phù hợp với từng nền tảng OA.

Kiểm tra tích hợp

Sau khi hoàn tất cấu hình, nên kiểm tra lần lượt từng dịch vụ OA:

Gửi một tin nhắn văn bản từ tài khoản người dùng thật.
Kiểm tra nền tảng đã gọi webhook thành công.
Kiểm tra người dùng và kênh hội thoại đã được tạo.
Xác nhận chatbot trả lời đúng vai trò của hồ sơ.
Gửi thêm một câu hỏi liên quan đến câu trước để kiểm tra ngữ cảnh.
Kiểm tra tin nhắn đến và câu trả lời đã được lưu.
Lặp lại trên từng OA có cấu hình hồ sơ khác nhau.

Một kịch bản kiểm tra đơn giản:

Người dùng: Bên bạn có hỗ trợ giao hàng không?
Chatbot: Có. Bạn vui lòng cho biết tỉnh hoặc thành phố nhận hàng.

Người dùng: Tôi ở Đà Nẵng.
Chatbot: ...

Nếu câu trả lời thứ hai hiểu “Đà Nẵng” là địa chỉ giao hàng, lịch sử hội thoại đã được đưa vào ngữ cảnh đúng cách.

Xử lý sự cố thường gặp

Hiện tượng	Nguyên nhân có thể	Cách kiểm tra
Tin nhắn được lưu nhưng không có phản hồi	Phản hồi tự động đang tắt	Kiểm tra cài đặt chung của EzyOA
Không thấy kịch bản chatbot	EzyChat hoặc thành phần chatbot chưa được nạp	Kiểm tra các plugin phụ thuộc trên admin và web runtime
Đã chọn chatbot nhưng không trả lời	Chưa chọn hồ sơ cho dịch vụ OA	Mở trang chi tiết OA và kiểm tra mã hồ sơ
Hồ sơ đã chọn nhưng vẫn im lặng	Hồ sơ không hoạt động	Kiểm tra trạng thái hồ sơ trong EzyChat
Không gọi được AI	Dịch vụ chatbot không khả dụng hoặc cấu hình sai	Kiểm tra API key, endpoint, model và dịch vụ gắn với hồ sơ
Chatbot không nhớ câu trước	Lịch sử không được lưu hoặc giới hạn ngữ cảnh quá thấp	Kiểm tra cấu hình lưu phản hồi và giới hạn tin nhắn
Tin nhắn ảnh không được trả lời	Kịch bản mặc định chỉ hỏi chatbot bằng văn bản	Dùng kịch bản đa phương thức tùy chỉnh
Không nhận được tin nhắn nào	Webhook hoặc cấu hình OA chưa hoạt động	Kiểm tra webhook, secret, token và trạng thái dịch vụ
Nhiều OA cùng ngừng trả lời	Kịch bản phản hồi là cấu hình chung	Kiểm tra lựa chọn kịch bản và công tắc phản hồi tự động
Câu trả lời mất định dạng hoặc liên kết	Nội dung được chuyển sang văn bản thuần	Điều chỉnh system message để tạo nội dung phù hợp với OA

Bảo mật và vận hành

Khi đưa chatbot vào môi trường thực tế, nên áp dụng các nguyên tắc sau:

Không đặt API key, access token hoặc webhook secret trong system message.
Không ghi thông tin xác thực vào source code hoặc tài liệu công khai.
Xác thực webhook theo cơ chế của từng nền tảng.
Chỉ công khai webhook qua HTTPS.
Giới hạn dữ liệu nhạy cảm được đưa vào lịch sử chatbot.
Không bật lưu raw webhook nếu không có nhu cầu vận hành rõ ràng.
Thiết kế system message để chatbot không tự tạo giá, chính sách hoặc dữ liệu nghiệp vụ.
Bổ sung cơ chế chuyển cho nhân viên khi chatbot không đủ thông tin.
Theo dõi lỗi, thời gian phản hồi, chi phí token và tỷ lệ câu hỏi không được trả lời.
Kiểm tra chính sách lưu trữ dữ liệu của nhà cung cấp AI trước khi gửi hội thoại khách hàng ra bên ngoài.

Giới hạn cần lưu ý

Tích hợp mặc định có các giới hạn chính:

Chỉ tự động phản hồi tin nhắn có nội dung văn bản.
Mỗi dịch vụ OA chọn một hồ sơ chatbot cho kịch bản này.
Chỉ hồ sơ đang hoạt động mới được sử dụng.
Kịch bản chatbot là lựa chọn chung, trong khi hồ sơ được cấu hình riêng theo dịch vụ.
Câu trả lời được gửi dưới dạng văn bản thuần.
Hệ thống không tự biến nội dung AI thành ảnh, file, nút bấm hoặc template đặc thù của từng OA.
Nếu chatbot không khả dụng hoặc trả về nội dung rỗng, EzyOA không gửi tin nhắn thay thế.
Việc chatbot được cấu hình đúng không bảo đảm webhook và token của nền tảng OA đã hoạt động.

Kết luận

Luồng tích hợp chatbot của EzyOA được thiết kế để một hệ thống AI có thể phục vụ nhiều kênh nhắn tin mà không phải triển khai lại logic cho từng nền tảng. EzyOA đảm nhiệm webhook, người dùng, kênh hội thoại và gửi nhận tin; EzyChat quản lý hồ sơ và ngữ cảnh; dịch vụ chatbot tạo câu trả lời.

Để tích hợp thành công, cần bảo đảm bốn lớp cùng hoạt động: kết nối OA, phản hồi tự động, hồ sơ chatbot và dịch vụ AI. Sau đó, mỗi OA có thể sử dụng một hồ sơ riêng để cung cấp trải nghiệm phù hợp với đúng nhóm người dùng và mục đích nghiệp vụ.

Hướng dẫn tích hợp chat bot vào các dịch vụ OA của EzyOA

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

Điều kiện cần chuẩn bị

Tạo hồ sơ chatbot

Bật phản hồi tự động

Gắn chatbot với dịch vụ OA

Luồng xử lý tin nhắn

Quản lý ngữ cảnh hội thoại

Định dạng câu trả lời

Trạng thái đang nhập

Những loại tin nhắn được chatbot xử lý

Kiểm tra tích hợp

Xử lý sự cố thường gặp

Bảo mật và vận hành

Giới hạn cần lưu ý

Kết luận

Table Of Contents

Hướng dẫn tích hợp chat bot vào các dịch vụ OA của EzyOA

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

Điều kiện cần chuẩn bị

Tạo hồ sơ chatbot

Bật phản hồi tự động

Gắn chatbot với dịch vụ OA

Luồng xử lý tin nhắn

Quản lý ngữ cảnh hội thoại

Định dạng câu trả lời

Trạng thái đang nhập

Những loại tin nhắn được chatbot xử lý

Kiểm tra tích hợp

Xử lý sự cố thường gặp

Bảo mật và vận hành

Giới hạn cần lưu ý

Kết luận

Table Of Contents

Sign In

Register

Forgot Password

Send Successfully