Tổng quan

flowchart LR
    I[Trang giới thiệu] --> S[Swagger]
    I --> O[Chat OA]
    I --> U[Chat người dùng]
    O <-->|Tin nhắn trong kênh OA| U
    U <-->|Kênh chat trực tiếp| U2[Người dùng khác]
    U -->|Webhook user_send_*| H[Webhook của ứng dụng]

Trang giới thiệu

• Tài liệu Zalo Sandbox API: trang Swagger mô tả các endpoint mô phỏng Zalo OA.
• Giao diện chat OA: mở /zalo-sandbox/oa/chat.
• Giao diện chat người dùng: mở /zalo-sandbox/user/chat.

Giao diện chat OA

Danh sách người dùng OA

• Tìm kiếm (biểu tượng kính lúp): lọc người dùng OA theo từ khóa. Hệ thống lần lượt thử khớp chính xác username, số điện thoại, email, UUID, sau đó tìm theo tiền tố từ khóa.
• Thêm người dùng OA (biểu tượng thêm người): mở hộp thoại tìm những người dùng chưa phải người dùng OA và gán vai trò cho họ. Người vừa thêm được đưa lên đầu danh sách và mở hội thoại ngay.

Hội thoại

• nhập văn bản và nhấn Enter hoặc nút gửi;
• chèn biểu tượng cảm xúc từ bảng emoji;
• gửi ảnh, video hoặc tệp bất kỳ.

Giao diện chat người dùng

Đăng nhập

• Nếu giá trị chỉ gồm 9 đến 11 chữ số (sau khi bỏ khoảng trắng, dấu chấm, dấu gạch), hệ thống coi đó là số điện thoại. Số chưa có 0 ở đầu sẽ được thêm 0; hệ thống không tự thêm +84.
• Các giá trị khác được gửi nguyên văn như tên đăng nhập.

Đăng ký

• số điện thoại hợp lệ và chưa được đăng ký;
• họ và tên không rỗng, tối đa 128 ký tự;
• mật khẩu dài từ 6 đến 128 ký tự và khớp với ô nhập lại.

Danh sách hội thoại

Nhắn tin

• gửi văn bản bằng Enter hoặc nút gửi;
• gửi 👍 khi nhấn nút gửi lúc ô nhập đang trống;
• chèn biểu tượng cảm xúc từ bảng emoji;
• gửi ảnh hoặc video (biểu tượng hình ảnh) và tệp bất kỳ (biểu tượng kẹp giấy).

Nhắn tin với OA

Cài đặt và đăng xuất

Cập nhật dữ liệu gần thời gian thực

• một mốc chung cho kênh OA, dùng bởi màn hình chat OA;
• một mốc riêng cho từng người dùng, dùng bởi màn hình chat người dùng.

sequenceDiagram
    participant A as Người gửi
    participant S as Zalo Sandbox
    participant B as Trình duyệt người nhận
    A->>S: Gửi tin nhắn
    S->>S: Lưu tin, cập nhật mốc thời gian
    loop Mỗi giây
        B->>S: GET state
        S-->>B: updatedAt
    end
    B->>S: Mốc thay đổi, tải tin nhắn mới

Danh sách API phục vụ các màn hình

Một kịch bản thử nghiệm

1. Mở /zalo-sandbox, chọn Giao diện chat người dùng và đăng ký một tài khoản mới.
2. Trong mục Zalo Sandbox - OA, gửi một tin văn bản và một ảnh.
3. Kiểm tra ứng dụng nhận được webhook user_send_text và user_send_image với chữ ký hợp lệ.
4. Mở Giao diện chat OA ở tab khác; người dùng vừa đăng ký xuất hiện trong danh sách cùng các tin vừa gửi.
5. Trả lời từ màn hình chat OA, hoặc từ ứng dụng thông qua /v3.0/oa/message/cs; tin trả lời hiện ở màn hình chat người dùng sau khoảng một giây.
6. Đăng ký thêm một tài khoản thứ hai, dùng Tạo cuộc trò chuyện để nhắn tin trực tiếp giữa hai tài khoản.

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

• Các màn hình chat OA và phần lớn API phía OA không yêu cầu đăng nhập; chỉ nên dùng trong môi trường thử nghiệm.
• Mốc thời gian thay đổi được lưu trong bộ nhớ của một tiến trình. Khi chạy nhiều instance, trình duyệt có thể không nhận được thay đổi xảy ra ở instance khác. Khi khởi động lại, mỗi trang đang mở sẽ làm mới dữ liệu một lần.
• Tin nhắn gửi qua socket của ezychat hoặc qua plugin khác không cập nhật mốc thời gian, nên chỉ hiển thị khi có thay đổi khác hoặc khi tải lại trang.
• Tương tác 👍 trên từng tin nhắn và các biểu tượng trang trí (sticker, danh thiếp, định dạng văn bản...) chưa có chức năng.
• Đăng nhập qua mã QR chỉ là hình minh họa.
• Người dùng mới đăng ký chỉ được gán vai trò người dùng OA khi lần đầu nhắn cho OA.