EzyOA là plugin kết nối EzyPlatform với các kênh Official Account và nền tảng nhắn tin. Plugin cung cấp một lớp tích hợp thống nhất để tiếp nhận webhook, quản lý người theo dõi, lưu lịch sử hội thoại, gửi tin nhắn và tự động phản hồi.
Qua cùng một mô hình xử lý, hệ thống hiện hỗ trợ:
  • Zalo Official Account.
  • Zalo OA Sandbox.
  • Facebook Messenger.
  • Telegram Bot.
  • Nhiều tài khoản hoặc bot cùng loại thông qua cơ chế kế thừa dịch vụ xử lý.

EzyOA giải quyết bài toán gì?

Mỗi nền tảng nhắn tin có cách xác thực, cấu trúc webhook, API gửi tin và quy tắc vận hành khác nhau. Nếu tích hợp trực tiếp vào ứng dụng nghiệp vụ, các khác biệt này dễ lan rộng ra toàn bộ hệ thống.
EzyOA đặt một lớp trung gian giữa EzyPlatform và nhà cung cấp:
flowchart LR
    User["Người dùng"] --> Provider["Zalo / Messenger / Telegram"]
    Provider -->|Webhook| WebRuntime["EzyOA Web Runtime"]
    WebRuntime --> Verify["Xác thực và chuẩn hóa"]
    Verify --> Events["Bộ điều phối sự kiện"]
    Events --> Conversation["Hội thoại và người dùng"]
    Events --> Scenario["Kịch bản phản hồi"]
    Scenario --> Chatbot["Chatbot hoặc nghiệp vụ"]
    Chatbot --> Sender["Bộ gửi tin"]
    Sender -->|Provider API| Provider

    Admin["Quản trị viên"] --> AdminModule["EzyOA Admin"]
    AdminModule --> Conversation
    AdminModule --> Sender
Ứng dụng nghiệp vụ có thể làm việc với các khái niệm chung như dịch vụ OA, người dùng OA, tin nhắn, thông báo và kịch bản phản hồi mà không phải tự xử lý toàn bộ đặc thù của từng nhà cung cấp.

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

EzyOA được chia thành ba lớp chính.

SDK dùng chung

SDK định nghĩa mô hình dữ liệu và các hợp đồng tích hợp:
  • Dịch vụ OA.
  • Cấu hình kết nối.
  • Người dùng OA.
  • Kênh hội thoại và lịch sử tin nhắn.
  • Mẫu thông báo.
  • Listener nhận sự kiện.
  • Kịch bản tạo câu trả lời.
  • Bộ gửi tin nhắn, thông báo và nội dung mở rộng.
Đây là lớp nền giúp phần quản trị và web runtime sử dụng cùng một quy ước.

Web runtime

Web runtime phụ trách các hoạt động cần diễn ra trên website:
  • Cung cấp webhook cho nhà cung cấp.
  • Tiếp nhận callback từ luồng OAuth.
  • Xác thực webhook.
  • Chuyển payload thành sự kiện nội bộ.
  • Lưu người dùng và tin nhắn nhận được.
  • Gọi kịch bản phản hồi tự động.
  • Gửi câu trả lời về đúng nền tảng.

Module quản trị

Module quản trị cung cấp giao diện và API dành cho nhân viên vận hành:
  • Thêm, sửa, kích hoạt hoặc vô hiệu hóa dịch vụ.
  • Chọn một dịch vụ làm kênh mặc định.
  • Theo dõi danh sách người dùng OA.
  • Liên kết người dùng OA với tài khoản trong hệ thống.
  • Xem lịch sử hội thoại.
  • Gửi tin cho một người hoặc nhiều người.
  • Quản lý nhân viên chăm sóc khách hàng.
  • Cấu hình mẫu thông báo và kịch bản phản hồi.
  • Kiểm thử kịch bản bằng tin nhắn mô phỏng.
Các API quản trị yêu cầu đăng nhập và được bảo vệ bằng quyền quản lý OA.

Mô hình dịch vụ

Mỗi kết nối được nhận diện bằng một mã dịch vụ. Cấu hình của dịch vụ có thể chứa:
  • Tên hiển thị.
  • Thông tin ứng dụng của nhà cung cấp.
  • URL dịch vụ và API.
  • Khóa truy cập hoặc khóa bí mật.
  • Thông tin phục vụ OAuth.
  • Kênh nhận thông báo.
  • Dịch vụ nền dùng để xử lý.
  • Trạng thái hoạt động.
Một dịch vụ chỉ nhận webhook khi tồn tại trong cấu hình và đang ở trạng thái kích hoạt. Điều này cho phép ngắt một kênh ở tầng quản trị mà không cần gỡ plugin.

Nhiều tài khoản cùng loại

EzyOA không giới hạn mỗi nền tảng ở một cấu hình duy nhất. Ví dụ, hệ thống có thể tạo:
  • Một bot Telegram cho bộ phận hỗ trợ.
  • Một bot khác cho bán hàng.
  • Nhiều Facebook Page.
  • Nhiều Zalo OA cho các thương hiệu khác nhau.
Mỗi cấu hình có mã riêng nhưng tham chiếu đến một dịch vụ xử lý nền như Telegram, Messenger hoặc Zalo. 
flowchart TD
    Base["Dịch vụ xử lý Telegram"] --> Support["TELEGRAM_SUPPORT"]
    Base --> Sales["TELEGRAM_SALES"]
    Base --> Internal["TELEGRAM_INTERNAL"]

    Support --> ConfigA["Token và webhook riêng"]
    Sales --> ConfigB["Token và webhook riêng"]
    Internal --> ConfigC["Token và webhook riêng"]
Khi dịch vụ được gọi lần đầu, EzyOA có thể tạo bộ xử lý từ dịch vụ nền và kế thừa các listener, bộ gửi mẫu và thành phần mở rộng tương ứng.

Luồng tiếp nhận webhook

Webhook dùng một cấu trúc URL thống nhất theo mã dịch vụ:
/api/v1/oa/{code}/webhook
Khi nhận request, EzyOA thực hiện các bước sau:
sequenceDiagram
    participant P as Nền tảng nhắn tin
    participant W as Webhook EzyOA
    participant S as Dịch vụ OA
    participant L as Listener
    participant D as Dữ liệu hội thoại
    participant R as Kịch bản phản hồi

    P->>W: Gửi webhook
    W->>W: Tìm dịch vụ đang hoạt động
    W->>S: Xác thực request và payload

    alt Xác thực thất bại
        S-->>W: Phản hồi lỗi
        W-->>P: HTTP lỗi
    else Sự kiện hợp lệ
        W->>S: Xử lý tin nhắn
        S->>L: Phát sự kiện theo loại
        L->>D: Lưu người dùng và tin nhắn
        L->>R: Tạo câu trả lời nếu được bật
        R->>S: Nội dung phản hồi
        S->>P: Gửi tin nhắn trả lời
        W-->>P: Xác nhận thành công
    else Sự kiện được bỏ qua
        W-->>P: Xác nhận thành công
    end
Việc trả thành công cho một sự kiện bị bỏ qua là có chủ đích. Nhà cung cấp không cần gửi lại các webhook mà hệ thống đã nhận nhưng không có hành động phù hợp.

Xác thực webhook

EzyOA không áp dụng một cách xác thực duy nhất cho mọi nền tảng. Mỗi bộ xử lý chịu trách nhiệm kiểm tra request theo cơ chế của nhà cung cấp, chẳng hạn:
  • Chữ ký của payload.
  • Secret token trong HTTP header.
  • Verify token trong bước đăng ký webhook.
  • Tham số xác minh của nhà cung cấp.
Payload chỉ được chuyển sang listener sau khi vượt qua bước kiểm tra tương ứng. Vì vậy, endpoint webhook có thể được công khai trên Internet nhưng request vẫn phải được xác thực trước khi tác động đến dữ liệu.
Để bảo đảm an toàn khi triển khai:
  • Luôn sử dụng HTTPS.
  • Không đưa app secret, bot token hoặc access token vào source code.
  • Dùng secret webhook riêng cho từng dịch vụ.
  • Thu hồi và cấp lại token ngay khi nghi ngờ bị lộ.
  • Chỉ kích hoạt dịch vụ sau khi cấu hình hoàn chỉnh.

Luồng OAuth

Các nền tảng yêu cầu cấp quyền có thể chuyển người quản trị về callback:
/oa/{code}/auth-callback

sequenceDiagram
    participant A as Quản trị viên
    participant P as Nhà cung cấp
    participant E as EzyOA
    participant C as Kho cấu hình

    A->>P: Cho phép ứng dụng truy cập
    P->>E: Callback kèm mã xác thực
    E->>E: Kiểm tra dịch vụ và trạng thái
    E->>P: Đổi mã lấy access token
    P-->>E: Access token
    E->>C: Lưu thông tin truy cập an toàn
    E-->>A: Chuyển về trang chi tiết dịch vụ
Callback chỉ được xử lý khi mã dịch vụ hợp lệ và dịch vụ không ở trạng thái vô hiệu hóa. Quy trình cụ thể như đổi token, làm mới token hoặc đăng ký Page phụ thuộc vào nền tảng.

Quản lý người dùng và hội thoại

Khi người dùng gửi tin lần đầu, EzyOA tìm người dùng dựa trên cặp:
mã dịch vụ + mã người dùng tại nhà cung cấp
Nếu chưa tồn tại, plugin lấy thông tin hồ sơ từ nhà cung cấp và tạo bản ghi người dùng OA. Dữ liệu có thể bao gồm:
  • Tên hiển thị.
  • Số điện thoại hoặc email nếu nền tảng cung cấp.
  • Ảnh đại diện.
  • Trạng thái theo dõi.
  • Liên kết tới tài khoản người dùng hoặc quản trị viên trong EzyPlatform.
Mỗi người dùng được gắn với một kênh hội thoại. Tin nhắn đến sau đó được lưu vào đúng kênh để giao diện quản trị và chatbot có thể truy xuất lịch sử.
Tùy theo cấu hình, hệ thống có thể lưu thêm:
  • Payload webhook nguyên bản.
  • Mã tin nhắn của nhà cung cấp.
  • Hình ảnh hoặc tệp đính kèm.
  • Mẫu phản hồi đã được sử dụng.
  • Tin nhắn do hệ thống tự động gửi.
Việc lưu payload và media có thể được tắt để giảm dung lượng hoặc đáp ứng chính sách dữ liệu của dự án.

Phản hồi tự động và chatbot

Sau khi lưu tin nhắn đến, EzyOA có thể chuyển nội dung qua một kịch bản phản hồi. Kịch bản được chọn theo cấu hình của từng dịch vụ.
flowchart TD
    Incoming["Tin nhắn mới"] --> Enabled{"Cho phép tự động phản hồi?"}
    Enabled -- Không --> SaveOnly["Chỉ lưu hội thoại"]
    Enabled -- Có --> Scenario["Chọn kịch bản"]
    Scenario --> Rule["Kịch bản nghiệp vụ"]
    Scenario --> Bot["Chatbot"]
    Rule --> Response["Nội dung phản hồi"]
    Bot --> History["Nạp lịch sử hội thoại"]
    History --> Response
    Response --> Media{"Có media?"}
    Media -- Không --> Text["Gửi tin văn bản"]
    Media -- Có --> Rich["Gửi nội dung và media"]
    Text --> SaveResponse["Lưu phản hồi nếu được bật"]
    Rich --> SaveResponse
Kịch bản chatbot có thể:
  • Sử dụng lịch sử gần nhất của kênh làm ngữ cảnh.
  • Chọn hồ sơ chatbot riêng cho từng dịch vụ.
  • Gửi trạng thái đang nhập nếu nền tảng hỗ trợ.
  • Chuyển kết quả Markdown sang văn bản phù hợp với kênh.
  • Trả về cả nội dung và media.
Nếu không có kịch bản phù hợp, chatbot không khả dụng hoặc không tạo được nội dung, EzyOA vẫn lưu tin nhắn đến nhưng không tự gửi câu trả lời.

Gửi tin nhắn và thông báo

EzyOA phân biệt hai nhóm thao tác chính:
  • Tin nhắn hội thoại: phù hợp với trao đổi trực tiếp với người dùng.
  • Thông báo theo mẫu: phù hợp với các nền tảng hoặc trường hợp yêu cầu template.
Plugin hỗ trợ:
  • Gửi văn bản.
  • Gửi văn bản kèm media.
  • Gửi nội dung theo mẫu.
  • Gửi thông báo theo mẫu và tham số.
  • Gửi cho một người nhận.
  • Gửi lần lượt cho toàn bộ người dùng của một dịch vụ.
  • Thống kê số lần gửi thành công và thất bại.
Khi gửi hàng loạt, người dùng được đọc theo từng nhóm nhỏ thay vì tải toàn bộ danh sách vào bộ nhớ. Tuy nhiên, quá trình hiện vẫn là gửi tuần tự đến từng người nhận; đây không phải hệ thống chiến dịch phân tán hoặc hàng đợi broadcast độc lập.
Một số luồng nghiệp vụ có thể thử gửi tin nhắn trước, sau đó chuyển sang thông báo nếu loại tin đầu tiên không khả dụng. Kết quả của từng phương thức gửi được lưu riêng để ứng dụng gọi có thể biết chính xác thao tác nào thành công.

Tích hợp theo sự kiện

Ngoài thao tác trực tiếp từ trang quản trị, EzyOA cung cấp các event handler để module khác yêu cầu:
  • Gửi tin nhắn.
  • Gửi thông báo.
  • Gửi tin nhắn hoặc thông báo theo cơ chế dự phòng.
  • Lưu liên kết giữa tài khoản nội bộ và người dùng OA.
  • Lấy metadata của tin nhắn gần nhất.
  • Đăng ký kịch bản phản hồi.
  • Lấy các lệnh thanh toán phục vụ hội thoại.
Nhờ đó, các module thương mại điện tử, hỗ trợ khách hàng hoặc workflow nội bộ có thể gửi thông báo qua OA mà không phụ thuộc trực tiếp vào API của Zalo, Meta hay Telegram.

Khả năng mở rộng

Kiến trúc EzyOA có nhiều điểm mở rộng:
  • Thêm một loại dịch vụ nhắn tin mới.
  • Bổ sung listener cho sự kiện mới.
  • Thêm kịch bản phản hồi.
  • Tạo bộ gửi tin theo template.
  • Tạo bộ gửi thông báo theo template.
  • Thêm transport riêng thông qua extension.
  • Bổ sung cách lưu avatar hoặc media.
  • Kết nối chatbot hoặc engine nghiệp vụ khác.
Một tích hợp mới cần tự triển khai những phần đặc thù của nhà cung cấp như xác thực, phân tích payload, lấy thông tin người dùng và gọi API gửi tin. Các phần quản lý cấu hình, điều phối sự kiện, hội thoại và trang quản trị có thể tiếp tục dùng chung.

Những giới hạn cần lưu ý

EzyOA là lớp tích hợp và quản lý hội thoại, không thay thế toàn bộ hạ tầng chăm sóc khách hàng hoặc marketing automation.
Một số giới hạn quan trọng:
  • Khả năng gửi tin phụ thuộc vào chính sách của từng nhà cung cấp.
  • Không phải nền tảng nào cũng hỗ trợ đầy đủ media, typing indicator hoặc notification template.
  • Gửi hàng loạt không đồng nghĩa với một hệ thống campaign quy mô lớn.
  • Dịch vụ ở trạng thái vô hiệu hóa sẽ không nhận webhook.
  • Tự động phản hồi chỉ hoạt động khi được bật và có kịch bản hợp lệ.
  • Payload hoặc loại sự kiện không được hỗ trợ có thể được xác nhận nhưng không xử lý.
  • Plugin không tự bỏ qua các giới hạn như cửa sổ hội thoại, quyền ứng dụng, hạn mức API hay quy trình duyệt template của nhà cung cấp.
  • Việc kết nối thêm nền tảng mới vẫn cần một adapter triển khai theo hợp đồng của EzyOA.

Kết luận

EzyOA cung cấp một lớp giao tiếp thống nhất giữa EzyPlatform và các nền tảng nhắn tin phổ biến. Plugin tập trung các vấn đề khó của tích hợp OA—webhook, xác thực, token, người dùng, hội thoại, template và phản hồi tự động—vào một kiến trúc có thể cấu hình và mở rộng.
Thiết kế này đặc biệt phù hợp với hệ thống cần vận hành nhiều OA, Page hoặc bot, đồng thời muốn giữ phần nghiệp vụ độc lập với API riêng của từng nhà cung cấp.