EzyOA có sẵn dịch vụ ZALO_SANDBOX, cho phép thay các endpoint Zalo OA thật bằng Zalo OA Sandbox trong môi trường phát triển. Sau khi kết nối, EzyOA có thể thực hiện OAuth/PKCE, đồng bộ người dùng, gửi tin nhắn, tải ảnh và nhận webhook có chữ ký mà không liên hệ hạ tầng Zalo.

Trước khi bắt đầu

Hướng dẫn này giả định rằng bạn đã tải EzyOA và Zalo Sandbox từ chợ EzyPlatform, cài đặt thành công cả admin plugin và web plugin của hai sản phẩm, sau đó khởi động lại EzyPlatform.

EzyOA và Zalo Sandbox sử dụng EzyChat cho các tính năng nhắn tin. Hãy bảo đảm EzyChat đã được cài đặt và hoạt động trước khi thiết lập kết nối.

Trong các ví dụ bên dưới, <WEB_URL> là địa chỉ web EzyPlatform, chẳng hạn http://localhost:8080 hoặc https://example.com. Không thêm dấu / ở cuối giá trị này.

Hướng dẫn giả định EzyOA và Zalo Sandbox chạy trên cùng một EzyPlatform. Nếu chúng chạy trên hai máy chủ khác nhau, hãy dùng địa chỉ Zalo Sandbox cho Service API URL và địa chỉ EzyOA cho callback URL cùng webhook URL.

Các giá trị cần khớp

Zalo Sandbox	EzyOA	Giá trị cần dùng
Zalo OA App ID	App ID	Hai trường phải giống nhau
Zalo OA App Secret Key	Secret Key	Hai trường phải giống nhau
Zalo OA Webhook Secret Key	Webhook Secret Key	Hai trường phải giống nhau
Auth Callback URLs	Authentication Callback URL	`<WEB_URL>/oa/ZALO_SANDBOX/auth-callback`
OA Webhook URLs	Webhook URL của EzyOA	`<WEB_URL>/api/v1/oa/ZALO_SANDBOX/webhook`
API base của sandbox	Service API URL	`<WEB_URL>/zalo-sandbox`

App Secret Key được dùng khi đổi authorization code hoặc refresh token lấy access token. Webhook Secret Key là khóa riêng để sandbox ký sự kiện và EzyOA xác minh chữ ký. Không nhập lẫn hai khóa này.

Cấu hình Zalo OA Sandbox

Đăng nhập trang quản trị, mở Zalo Sandbox → Settings và cấu hình:

Zalo OA App ID: nhập App ID dành cho môi trường thử nghiệm;
Zalo OA App Secret Key: nhập hoặc tạo ngẫu nhiên khóa ứng dụng;
Zalo OA Webhook Secret Key: nhập hoặc tạo ngẫu nhiên khóa ký webhook;
Zalo OA Access Token và Refresh Token: nhập hoặc tạo ngẫu nhiên;
Token Expire In Seconds: nhập thời gian hiệu lực dương, ví dụ 604800 cho 7 ngày;
Auth Callback URLs: thêm <WEB_URL>/oa/ZALO_SANDBOX/auth-callback;
OA Webhook URLs: thêm <WEB_URL>/api/v1/oa/ZALO_SANDBOX/webhook;
hai trường giả lập lỗi gửi tin: chọn None trong lần kết nối đầu tiên.

Có thể để trống Auth Code Challenge. Khi EzyOA bắt đầu cấp quyền, sandbox sẽ nhận và lưu challenge do EzyOA gửi.

Lưu cấu hình và giữ lại App ID, App Secret Key cùng Webhook Secret Key để nhập sang EzyOA. Nếu có nhiều URL, hãy phân tách bằng dấu phẩy. Callback URL phải khớp tuyệt đối, kể cả protocol, domain, port, path và dấu / cuối nếu có.

Cấu hình dịch vụ ZALO_SANDBOX trong EzyOA

Mở EzyOA → OA Services, tìm dịch vụ có mã ZALO_SANDBOX, sau đó mở trang chỉnh sửa.

Trường EzyOA	Giá trị
Name	Tên dễ nhận biết, ví dụ `Zalo OA Sandbox`
Version	Không bắt buộc, có thể nhập `v4`
App ID	Giống Zalo OA App ID trong sandbox
Service URL	`<WEB_URL>/zalo-sandbox`
Service API URL	`<WEB_URL>/zalo-sandbox`
Secret Key	Giống Zalo OA App Secret Key trong sandbox
Webhook Secret Key	Giống Zalo OA Webhook Secret Key trong sandbox
Code Challenge	Bấm Random cạnh trường này
Code Verifier	Được tự động điền cùng Code Challenge
Status	Activated

Service API URL phải dừng ở /zalo-sandbox; không thêm /v4/oa/access_token hoặc endpoint cụ thể khác. Các trường Client Key, App UUID, logo, banner, notification channel và mẫu thông báo nhân viên không bắt buộc với kết nối cơ bản.

Nhấn Save và kiểm tra dịch vụ đang ở trạng thái Activated. Nếu muốn EzyOA dùng sandbox khi ứng dụng không chỉ định mã dịch vụ OA, hãy đặt ZALO_SANDBOX làm dịch vụ mặc định.

Lấy access token

Mở trang chi tiết ZALO_SANDBOX. EzyOA hiển thị Authentication Callback URL, Auth URL và nút Lấy access token.

Trước tiên, đối chiếu Authentication Callback URL trên trang này với Auth Callback URLs trong sandbox. Sau đó nhấn Lấy access token. Luồng xử lý diễn ra như sau:

sequenceDiagram
    participant A as Quản trị viên
    participant E as EzyOA
    participant S as Zalo OA Sandbox
    A->>S: Mở URL cấp quyền với App ID và code challenge
    S-->>E: Chuyển hướng callback kèm code và code challenge
    E->>E: Đối chiếu code challenge
    E->>S: Đổi code, code verifier và secret key lấy token
    S-->>E: Trả access token, refresh token và expires_in
    E->>E: Lưu token cùng thời điểm hết hạn
    E-->>A: Chuyển về trang chi tiết dịch vụ

Khi token hết hạn, EzyOA tự dùng refresh token để lấy lại token. Sandbox trả các giá trị token đã cấu hình và gia hạn thời điểm hết hạn, không nhất thiết xoay vòng token.

Chuẩn bị và đồng bộ người dùng

Zalo Sandbox chỉ cung cấp qua API những tài khoản EzyPlatform đã được gán vai trò người dùng OA sandbox:

Mở Zalo Sandbox → Users.
Nhấn nút thêm mới.
Tìm và chọn một tài khoản EzyPlatform đã tồn tại.
Bổ sung tên hiển thị, số điện thoại và ảnh đại diện nếu cần.
Lặp lại nếu cần nhiều người dùng.

Quay lại trang chi tiết ZALO_SANDBOX trong EzyOA và sử dụng chức năng lấy toàn bộ follower. EzyOA gọi API danh sách và chi tiết người dùng của sandbox để tạo hoặc cập nhật OA user tương ứng. OA user ID chính là UUID của tài khoản EzyPlatform.

Kiểm tra chiều EzyOA gửi sang sandbox

Trên trang chi tiết ZALO_SANDBOX, nhập UUID vào Recipient ID, nhập nội dung và gửi tin. Trong lần thử đầu, không chọn gửi cho tất cả người dùng.

EzyOA sẽ gọi:

<WEB_URL>/zalo-sandbox/v3.0/oa/message/cs

Mở Zalo Sandbox → Messages để kiểm tra tin vừa được ghi vào kênh chat OA.

Với tin có ảnh, EzyOA có thể tải ảnh lên <WEB_URL>/zalo-sandbox/v2.0/oa/upload/image, nhận attachment ID rồi đưa nó vào payload. Tính năng upload tài nguyên phải được bật trong web runtime.

Kiểm tra tin nhắn template

EzyOA gửi thông báo template đến:

<WEB_URL>/zalo-sandbox/message/template

Sandbox tìm người nhận theo số điện thoại. Tài khoản EzyPlatform tương ứng cần có cùng số điện thoại với người dùng hoặc khách hàng phía EzyOA; template ID và JSON tham số cũng không được để trống. Sau khi gửi, mở Zalo Sandbox → Messages để kiểm tra dữ liệu template đã lưu.

Kết nối webhook từ sandbox về EzyOA

Webhook URL dành cho dịch vụ này là:

<WEB_URL>/api/v1/oa/ZALO_SANDBOX/webhook

URL này phải nằm trong Zalo Sandbox → Settings → OA Webhook URLs. Dịch vụ ZALO_SANDBOX trong EzyOA cũng phải ở trạng thái Activated.

Để kiểm tra:

Mở Zalo Sandbox → Users và chọn một người dùng thử.
Tại trang chi tiết, chọn webhook URL của EzyOA.
Nhập một tin nhắn văn bản rồi nhấn Send.
Kiểm tra kết quả xử lý người dùng hoặc hội thoại trong EzyOA.

Bạn cũng có thể gửi từ Zalo Sandbox → Messages bằng username của người dùng thử.

Sandbox ký request bằng App ID và Webhook Secret Key. EzyOA tính lại chữ ký từ raw request body và từ chối request nếu thông tin không khớp:

Zalo Sandbox App ID = EzyOA App ID
Zalo Sandbox Webhook Secret Key = EzyOA Webhook Secret Key

Nếu Webhook Secret Key trong EzyOA để trống, EzyOA coi request là dữ liệu kiểm thử thay vì xác minh chữ ký đầy đủ. Để kiểm tra sát môi trường thật, nên cấu hình cùng một webhook secret ở cả hai phía.

Kiểm tra kết nối hai chiều

Chiều	Cách kiểm tra
EzyOA → Zalo Sandbox	Gửi tin từ EzyOA và xem tại Zalo Sandbox → Messages
Zalo Sandbox → EzyOA	Phát webhook từ sandbox và kiểm tra kết quả xử lý trong EzyOA

Quy trình end-to-end tối thiểu:

Lấy access token từ trang chi tiết dịch vụ EzyOA.
Đồng bộ ít nhất một người dùng sandbox sang EzyOA.
Gửi tin từ EzyOA đến UUID người dùng đó.
Kiểm tra tin nhắn trong Zalo Sandbox.
Gửi webhook user_send_text từ sandbox về EzyOA.
Xác nhận EzyOA tiếp nhận webhook mà không báo sai chữ ký.

Giả lập lỗi

Để thử nhánh thất bại, mở Zalo Sandbox → Settings và chọn mã tại Send Message Response Error hoặc Send Message Template Response Error. Lưu cấu hình rồi gửi lại từ EzyOA.

Sandbox lưu request hợp lệ vào kênh chat trước khi áp dụng mã lỗi giả lập. Vì vậy, thấy tin nhắn trong sandbox không đồng nghĩa EzyOA đã nhận response thành công. Sau khi thử xong, chọn None và lưu lại.

Xử lý sự cố

Permission báo redirect URI không hợp lệ

Sao chép trực tiếp Authentication Callback URL từ trang chi tiết EzyOA sang Auth Callback URLs của sandbox. Khác protocol, port, path hoặc dấu / cuối đều làm validation thất bại.

Đổi token báo secret key không hợp lệ

Secret Key của EzyOA phải khớp Zalo OA App Secret Key trong sandbox. Không dùng Webhook Secret Key cho trường này.

Đổi token báo code verifier không hợp lệ

Tại trang chỉnh sửa dịch vụ EzyOA, bấm Random cạnh Code Challenge để tạo lại cả cặp PKCE rồi lưu. Không sửa riêng lẻ Code Challenge hoặc Code Verifier.

Access token không hợp lệ hoặc hết hạn

Kiểm tra Access Token trong sandbox không bị thay đổi sau khi EzyOA nhận token. Chạy lại Lấy access token để đồng bộ và cập nhật thời hạn.

Không đồng bộ được người dùng

Kiểm tra tài khoản đã được thêm tại Zalo Sandbox → Users, access token còn hiệu lực và Service API URL đúng là <WEB_URL>/zalo-sandbox.

Webhook trả về 404 hoặc sai chữ ký

Kiểm tra dịch vụ ZALO_SANDBOX đang Activated và URL dùng web domain, không dùng admin domain. Nếu sai chữ ký, đối chiếu App ID, Webhook Secret Key và bảo đảm proxy không thay đổi raw JSON body.

EzyOA không kết nối được đến sandbox

Trong container hoặc trên hai máy khác nhau, localhost không nhất thiết trỏ đến web EzyPlatform. Hãy dùng hostname mà runtime EzyOA thực sự truy cập được.

Checklist hoàn tất

EzyChat, EzyOA và Zalo Sandbox đều hoạt động.
ZALO_SANDBOX đã được kích hoạt trong EzyOA.
Service API URL kết thúc bằng /zalo-sandbox.
App ID và hai loại secret khớp đúng trường ở hai phía.
Callback URL EzyOA hiển thị đã có trong danh sách cho phép của sandbox.
Webhook URL EzyOA đã có trong danh sách webhook của sandbox.
Code Challenge và Code Verifier là một cặp được tạo cùng lúc.
EzyOA đã lấy access token thành công.
Ít nhất một người dùng sandbox đã được đồng bộ.
Tin nhắn từ EzyOA xuất hiện trong Zalo Sandbox.
Webhook từ Zalo Sandbox được EzyOA chấp nhận.
Các trường giả lập lỗi đã được đưa về None sau kiểm thử.

Khi hoàn thành các mục trên, EzyOA đã kết nối với Zalo OA Sandbox và có thể dùng sandbox thay endpoint Zalo OA thật trong quá trình phát triển và kiểm thử tích hợp.

Hướng dẫn kết nối EzyOA plugin đến Zalo Sandbox plugin

Trước khi bắt đầu

Các giá trị cần khớp

Cấu hình Zalo OA Sandbox

Cấu hình dịch vụ ZALO_SANDBOX trong EzyOA

Lấy access token

Chuẩn bị và đồng bộ người dùng

Kiểm tra chiều EzyOA gửi sang sandbox

Kiểm tra tin nhắn template

Kết nối webhook từ sandbox về EzyOA

Kiểm tra kết nối hai chiều

Giả lập lỗi

Xử lý sự cố

Permission báo redirect URI không hợp lệ

Đổi token báo secret key không hợp lệ

Đổi token báo code verifier không hợp lệ

Access token không hợp lệ hoặc hết hạn

Không đồng bộ được người dùng

Webhook trả về 404 hoặc sai chữ ký

EzyOA không kết nối được đến sandbox

Checklist hoàn tất

Table Of Contents

Hướng dẫn kết nối EzyOA plugin đến Zalo Sandbox plugin

Trước khi bắt đầu

Các giá trị cần khớp

Cấu hình Zalo OA Sandbox

Cấu hình dịch vụ ZALO_SANDBOX trong EzyOA

Lấy access token

Chuẩn bị và đồng bộ người dùng

Kiểm tra chiều EzyOA gửi sang sandbox

Kiểm tra tin nhắn template

Kết nối webhook từ sandbox về EzyOA

Kiểm tra kết nối hai chiều

Giả lập lỗi

Xử lý sự cố

Permission báo redirect URI không hợp lệ

Đổi token báo secret key không hợp lệ

Đổi token báo code verifier không hợp lệ

Access token không hợp lệ hoặc hết hạn

Không đồng bộ được người dùng

Webhook trả về 404 hoặc sai chữ ký

EzyOA không kết nối được đến sandbox

Checklist hoàn tất

Table Of Contents

Sign In

Register

Forgot Password

Send Successfully