Muốn gọi Zalo Official Account API từ CRM, chatbot, hệ thống chăm sóc khách hàng hoặc ứng dụng nội bộ, bạn cần một OA access token hợp lệ. Token không nên được sao chép tùy tiện từ trình duyệt hay lưu cố định trong mã nguồn. Luồng chuẩn là để quản trị viên OA cấp quyền cho Zalo App, nhận authorization code, rồi đổi code thành access token và refresh token tại backend.
Bài viết hướng dẫn Cách generate access token Zalo OA theo OAuth Authorization Code kết hợp PKCE, có ví dụ Node.js, cURL, cách refresh token và xử lý lỗi. Giao diện hoặc tên trường trên Zalo Developer có thể được điều chỉnh theo thời điểm, vì vậy hãy đối chiếu thêm cấu hình hiển thị trong ứng dụng của bạn khi triển khai.
Nội dung chính
Cách generate access token Zalo OA hoạt động như thế nào?
Zalo OA access token là chuỗi ủy quyền cho phép ứng dụng đại diện một Official Account gọi các API đã được cấp quyền. Tùy phạm vi được phê duyệt, ứng dụng có thể đọc thông tin OA, quản lý người quan tâm, xử lý hội thoại hoặc thực hiện các chức năng vận hành khác.
Một luồng Cách generate access token Zalo OA gồm năm thành phần:
- Zalo OA: Tài sản doanh nghiệp cần được truy cập.
- Zalo App: Ứng dụng có App ID và Secret Key trên Zalo for Developers.
- Quản trị viên OA: Người đồng ý cấp quyền cho ứng dụng.
- Callback URL: Endpoint HTTPS nhận authorization code.
- Backend: Nơi đổi code, lưu token và tự động làm mới.
Quy trình tổng quát:
Tạo code_verifier và code_challenge
↓
Mở trang cấp quyền Zalo OA
↓
Nhận authorization code tại callback
↓
Gửi code + code_verifier tới token endpoint
↓
Nhận access_token + refresh_token + expires_in
cùng zalo web.
Cách generate access token Zalo OA qua 4 bước chuẩn OAuth v4
Quy trình dưới đây áp dụng cho Zalo Official Account API phiên bản OAuth v4, dùng cơ chế Authorization Code kết hợp PKCE để bảo vệ luồng cấp quyền.
Bước 1: Tạo ứng dụng và liên kết Zalo OA
Đăng nhập Zalo for Developers, tạo ứng dụng mới rồi lưu lại App ID và Secret Key. Trong mục Official Account của ứng dụng, chọn liên kết OA mà bạn muốn truy cập API, sau đó khai báo Redirect URI (địa chỉ nhận mã ủy quyền). Ứng dụng cần được kích hoạt và OA phải ở trạng thái đã xác thực để gọi được các API gửi tin.
Bước 2: Sinh code_verifier và code_challenge (PKCE)
Tạo một chuỗi ngẫu nhiên từ 43 đến 128 ký tự làm code_verifier. Băm chuỗi này bằng SHA-256, mã hóa Base64 URL-safe để có code_challenge. Ví dụ Node.js:
const crypto = require('crypto');
const codeVerifier = crypto.randomBytes(48).toString('base64url');
const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');Mở đường dẫn cấp quyền có dạng https://oauth.zaloapp.com/v4/oa/permission?app_id=APP_ID&redirect_uri=REDIRECT_URI&code_challenge=CODE_CHALLENGE&state=STATE. Chủ sở hữu OA đăng nhập, chọn OA và bấm cho phép. Zalo sẽ chuyển hướng về Redirect URI kèm tham số code và oa_id. Mã này chỉ dùng được một lần và hết hạn sau vài phút nên cần đổi sang access token ngay.
Gửi yêu cầu POST tới https://oauth.zaloapp.com/v4/oa/access_token với header secret_key là Secret Key của ứng dụng, Content-Type là application/x-www-form-urlencoded, và body gồm code, app_id, grant_type=authorization_code, code_verifier. Ví dụ cURL:
curl -X POST "https://oauth.zaloapp.com/v4/oa/access_token" \
-H "secret_key: SECRET_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "code=AUTH_CODE&app_id=APP_ID&grant_type=authorization_code&code_verifier=CODE_VERIFIER"Phản hồi thành công trả về access_token (hiệu lực khoảng 25 giờ), refresh_token (hiệu lực khoảng 3 tháng) và expires_in. Lưu cả hai token vào nơi an toàn phía máy chủ, tuyệt đối không nhúng vào mã nguồn front-end.
Làm mới access token bằng refresh token
Khi access token hết hạn, không cần yêu cầu chủ OA cấp quyền lại. Gọi lại endpoint /v4/oa/access_token với body refresh_token=REFRESH_TOKEN&app_id=APP_ID&grant_type=refresh_token và header secret_key. Zalo trả về cặp token mới, đồng thời refresh token cũ sẽ bị vô hiệu, vì vậy hệ thống phải cập nhật ngay giá trị mới sau mỗi lần làm mới. Nên lập lịch làm mới trước khi hết hạn khoảng 1 giờ và khóa tiến trình để tránh hai luồng cùng refresh một lúc.
Lỗi thường gặp khi generate access token Zalo OA
- Invalid code / code expired: authorization code đã dùng hoặc quá hạn, hãy chạy lại bước 3.
- Invalid code_verifier: code_verifier gửi lên không khớp với code_challenge đã dùng, kiểm tra lại cách băm SHA-256 và Base64 URL-safe.
- Invalid secret_key: header secret_key sai hoặc thuộc ứng dụng khác.
- Lỗi 18005 invalid token: access token hết hạn hoặc bị thu hồi, hãy dùng refresh token để lấy token mới.
- Redirect URI mismatch: địa chỉ chuyển hướng chưa được khai báo đúng trong cấu hình ứng dụng.
Câu hỏi thường gặp
Access token Zalo OA dùng được bao lâu? Khoảng 25 giờ, sau đó cần làm mới bằng refresh token có hiệu lực khoảng 3 tháng.
Một ứng dụng có thể lấy token cho nhiều OA không? Có, mỗi OA sẽ có cặp token riêng, hệ thống cần lưu token theo oa_id.
Có nên lấy token thủ công trên trang Developer không? Chỉ nên dùng để thử nghiệm; với hệ thống chạy thật hãy tự động hóa luồng ở trên để token luôn được làm mới đúng hạn.
Xem thêm hướng dẫn liên quan
- SMS OTP là gì Zalo? Cách xác thực và bảo vệ tài khoản
- SDK Zalo developer: Tổng quan và cách tích hợp hiệu quả
- Lỗi 400 API Zalo: Nguyên nhân, kiểm tra và cách khắc phục
- Xem toàn bộ chuyên mục Zalo Developer
Nguồn tham khảo: Zalo Developers
Vương Minh – người dẫn dắt và đứng sau sự thành công của ZALO Web cùng với đội ngũ kĩ sư ưu tú nhất. Với khát vọng tạo ra một sản phẩm công nghệ “Make in Vietnam” đủ sức cạnh tranh sòng phẳng với các đối thủ quốc tế, ông Minh cùng các cộng sự tại Zalo Group đã không ngừng cải tiến để Zalo không chỉ là app nhắn tin mà còn là một hệ sinh thái làm việc đa nền tảng. Zalo Web chính là minh chứng cho triết lý đó: tinh gọn, tốc độ và thấu hiểu sâu sắc thói quen của người dùng Việt.