Cơ chế hoạt động

sequenceDiagram
    participant A as Quản trị viên
    participant O as EzyOA
    participant P as API của OA
    participant C as EzyConnector
    participant W as Giao diện quản trị OA

    A->>O: Gửi danh sách người nhận
    O->>P: Thử gửi qua API chính thức
    P-->>O: Kết quả thành công và thất bại

    loop Từng người nhận thất bại
        O->>C: Gửi workflow qua socket
        C->>W: Tìm người nhận và mở hội thoại
        C->>W: Upload ảnh nếu có
        C->>W: Nhập nội dung và nhấn Enter
        W-->>C: Kết quả thao tác
        C-->>O: Thành công hoặc lỗi
    end

    O-->>A: Hiển thị tiến trình và danh sách chưa gửi được

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

• Dịch vụ Zalo OA đã được thêm và kích hoạt trong EzyOA.
• EzyChat và socket application đang hoạt động vì EzyConnector sử dụng kết nối socket để nhận nhiệm vụ.
• EzyConnector đã được cài trên Chrome.
• Extension đã đăng nhập vào đúng hệ thống EzyPlatform.
• Trạng thái kết nối của extension là connected.
• Quản trị viên đã đăng nhập giao diện quản trị Zalo OA trên cùng trình duyệt.
• Tài khoản đang đăng nhập Zalo OA có quyền gửi tin nhắn.
• Chrome cho phép extension truy cập trang https://oa.zalo.me/.

Chuẩn bị giao diện Zalo OA

1. Mở Chrome đang cài EzyConnector.
2. Đăng nhập vào Zalo OA.
3. Truy cập giao diện chat tại:

https://oa.zalo.me/chat

4. Chọn đúng OA cần gửi tin nếu tài khoản quản lý nhiều OA.
5. Giữ phiên đăng nhập hoạt động trong suốt quá trình gửi.

Gửi tin nhắn từ EzyOA

1. Mở phần quản lý EzyOA.
2. Chọn dịch vụ Zalo OA cần sử dụng.
3. Đi đến trang chi tiết dịch vụ.
4. Tìm khu vực Gửi tin nhắn.
5. Nhập danh sách mã người nhận.
6. Nhập nội dung tin nhắn.
7. Chọn ảnh nếu cần.
8. Chọn phạm vi gửi.
9. Đánh dấu Gửi qua trình mở rộng.
10. Nhấn Gửi.

Danh sách người nhận

• Dấu phẩy.
• Dấu xuống dòng.
• Kết hợp dấu phẩy và xuống dòng.

843412345678
849012345678
849876543210

Nội dung tin nhắn

Xin chào, đơn hàng của bạn đã được bàn giao cho đơn vị vận chuyển.

Xin chào, đơn hàng của bạn đã được bàn giao cho đơn vị vận chuyển.
04/10/2026 10:30:15

Gửi kèm ảnh

1. Tải ảnh từ URL.
2. Mở chức năng gửi ảnh trên giao diện OA.
3. Gán ảnh vào file input.
4. Chờ quá trình upload.
5. Nhập và gửi nội dung văn bản.

Gửi cho tất cả tài khoản OA

Gửi đến các tài khoản OA liên kết với người dùng

Extension xử lý một người nhận như thế nào?

1. Tìm tab Zalo OA đang mở hoặc mở trang chat.
2. Chuyển tab thành tab đang hoạt động.
3. Chờ giao diện sẵn sàng.
4. Điền mã người nhận vào ô tìm kiếm.
5. Chờ danh sách kết quả ổn định.
6. Phát hiện thông báo không tìm thấy người nhận nếu có.
7. Chọn hội thoại phù hợp.
8. Kiểm tra quyền tương tác với người nhận.
9. Chờ ô nhập tin nhắn xuất hiện.
10. Upload ảnh nếu yêu cầu có media.
11. Điền nội dung tin nhắn.
12. Nhấn Enter để gửi.
13. Trả kết quả về EzyOA.

Theo dõi quá trình gửi

• Tổng số người nhận cần gửi qua extension.
• Số người nhận đã xử lý.
• Số lượt thành công.
• Số lượt thất bại.
• Thời gian còn lại trước lượt gửi tiếp theo.
• Nút hủy quá trình gửi.

• Không đóng trang EzyOA.
• Không tải lại trang.
• Không đăng xuất khỏi Zalo OA.
• Hạn chế thao tác thủ công trên tab Zalo OA.
• Không đóng Chrome hoặc tắt EzyConnector.

Hủy quá trình gửi

• Người nhận đã xử lý nhưng gặp lỗi.
• Người nhận chưa được xử lý do quá trình bị hủy.

Các lỗi thường gặp

Extension không kết nối

• Yêu cầu chờ lâu rồi thất bại.
• Không có thao tác nào diễn ra trên Chrome.

• Mở popup EzyConnector.
• Kiểm tra trạng thái connected.
• Đăng nhập lại extension.
• Kiểm tra EzyChat socket application.
• Kiểm tra URL quản trị và WebSocket URL.
• Xác nhận extension đăng nhập bằng đúng tài khoản quản trị đang gửi tin.

Không tìm thấy người nhận

• Mã người nhận có chính xác không.
• Mã có thuộc đúng OA đang mở không.
• Người dùng có tồn tại trong dữ liệu EzyOA không.
• Giao diện Zalo OA có tìm được mã đó khi thao tác thủ công không.

Người nhận đã hết thời hạn tương tác

Phiên đăng nhập Zalo OA hết hạn

Giao diện OA thay đổi

• Ô tìm kiếm.
• Danh sách kết quả.
• Ô nhập tin nhắn.
• Nút chọn ảnh.
• Nội dung thông báo lỗi.

Ảnh không tải được

• URL ảnh không sử dụng HTTPS.
• URL yêu cầu đăng nhập hoặc cookie riêng.
• Máy chạy Chrome không truy cập được URL.
• Tệp quá lớn.
• Định dạng tệp không được giao diện OA chấp nhận.

API gửi được nhưng extension không chạy

Khuyến nghị vận hành an toàn

• Chỉ cài extension từ nguồn tin cậy.
• Dùng tài khoản riêng cho nhân viên được phép gửi tin.
• Không chia sẻ tài khoản quản trị giữa nhiều người.
• Chỉ cấp quyền quản lý OA cho người thực sự cần.
• Luôn sử dụng HTTPS và WSS ngoài môi trường phát triển.
• Không đưa access token hoặc mật khẩu vào log.
• Kiểm tra một nhóm người nhận nhỏ trước khi gửi số lượng lớn.
• Giữ nội dung đúng chính sách của nền tảng OA.
• Theo dõi danh sách gửi thất bại thay vì gửi lại toàn bộ danh sách.
• Không thao tác đồng thời trên tab OA trong khi workflow đang chạy.

Quy trình kiểm tra đề xuất

1. Gửi một tin nhắn văn bản tới một tài khoản thử nghiệm.
2. Kiểm tra tin có được gửi qua API hay không.
3. Dùng một trường hợp API không gửi được để kiểm tra luồng extension.
4. Thử gửi tin kèm một ảnh nhỏ.
5. Kiểm tra trường hợp sai mã người nhận.
6. Kiểm tra trường hợp hết thời hạn tương tác.
7. Gửi thử cho một nhóm nhỏ từ 3–5 người.
8. Kiểm tra số thành công, số thất bại và danh sách chưa gửi được.
9. Thử hủy giữa chừng để xác nhận hệ thống giữ lại đúng danh sách chưa xử lý.

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

• Máy tính của quản trị viên đang hoạt động.
• Chrome đang mở.
• EzyConnector đang kết nối.
• Phiên đăng nhập OA còn hiệu lực.
• Cấu trúc giao diện web của nhà cung cấp chưa thay đổi.
• Chính sách tương tác và gửi tin của nền tảng.
• Chất lượng kết nối giữa backend, socket application và extension.

Kết luận