Nhảy tới nội dung
Uỷ quyền Ứng dụng (AppID) cho OA

Uỷ quyền Ứng dụng (AppID) cho OA

Ứng dụng (AppID) giống như “người đại diện” của Zalo Official Account (OA) khi gửi tin nhắn ZBS Template và gọi các API của Zalo. Để Ứng dụng được gửi tin thay cho OA, Quản trị viên OA chỉ cần uỷ quyền cho Ứng dụng một lần. Sau khi uỷ quyền, Quý khách sẽ nhận được cặp Access token và Refresh token để dùng khi gọi API.

Cách 1 · Khuyên dùng

Công cụ API Explorer

Không cần lập trình · làm ngay trên Zalo for Developers

  1. Chọn Ứng dụng và OA
  2. Cấp quyền cho Ứng dụng
  3. Nhận Access token và Refresh token
Cách 2

Giao thức OAuth v4

Dành cho đội kỹ thuật · tích hợp vào hệ thống

  1. Tạo đường dẫn yêu cầu cấp quyền
  2. Admin OA cấp quyền
  3. Đổi Authorization code lấy token

Trước khi bắt đầu​

Để việc uỷ quyền diễn ra suôn sẻ, Quý khách vui lòng kiểm tra đủ cả 4 điều kiện dưới đây:

Điều kiệnChi tiết
Ứng dụng đã liên kết ZBSỨng dụng (AppID) đã được liên kết vào tài khoản ZBS
OA đã liên kết ZBSOA đã được liên kết vào tài khoản ZBS
Quyền trên OAQuản trị viên (Admin) của OA
Quyền trên Ứng dụngQuản trị viên của Ứng dụng

Lưu ý: Tài khoản Zalo dùng để uỷ quyền cần vừa là Admin của OA, vừa là Quản trị viên của Ứng dụng. Nếu thiếu một trong hai quyền, OA sẽ không hiện trong danh sách để chọn.

Thời hạn của các loại mã​

Loại mãHiệu lựcCách dùng
Authorization code10 phútChỉ dùng 1 lần để đổi lấy Access token (Cách 2)
Access token25 giờĐính kèm khi gọi API gửi tin
Refresh token3 thángChỉ dùng 1 lần để lấy Access token mới, kèm một Refresh token mới

Mẹo nhỏ: Access token chỉ dùng được trong 25 giờ. Để việc gửi tin không bị gián đoạn, hệ thống của Quý khách nên dùng Refresh token để lấy Access token mới trước khi hết hạn, và nhớ lưu lại Refresh token mới sau mỗi lần cấp. Chi tiết xem tại Xác thực và ủy quyền cho Ứng dụng.

Cách 1 · Không cần lập trình

Uỷ quyền bằng công cụ API Explorer

Cách nhanh nhất để lấy token: Quý khách thao tác trực tiếp trên API Explorer của Zalo for Developers (menu Công cụ → API Explorer).

Bước 1 · Chọn Ứng dụng và loại token​

  1. Ở ô Chọn ứng dụng, chọn Ứng dụng Quý khách muốn uỷ quyền.
  2. Ở ô Loại access token, chuyển sang OA Access Token.
  3. Nhấn Lấy Access Token.
Khung Lấy Access Token trên API Explorer, đánh số 1–3 theo thứ tự thao tác

Số đỏ trên ảnh tương ứng với số thứ tự của từng thao tác ở trên.

Bước 2 · Chọn OA cần uỷ quyền​

Danh sách sẽ hiện các OA mà Quý khách đang là Admin. Nếu có nhiều OA, Quý khách gõ tên vào ô Tìm kiếm OA (1) để tìm nhanh, rồi chọn OA cần uỷ quyền (2).

Danh sách OA sau khi nhấn Lấy Access Token, đánh số 1 ở ô Tìm kiếm OA và số 2 ở danh sách OA được chọn

Chọn OA cần uỷ quyền cho Ứng dụng.

Một thông báo xác nhận sẽ hiện ra. Quý khách đọc qua và nhấn Tôi đã hiểu và muốn tiếp tục.

Hộp thoại Thông báo trước khi lấy OA Access Token mới

Thông báo xác nhận lấy token mới.

Lưu ý trước khi tiếp tục: Lấy token mới có thể khiến Access token và Refresh token đang dùng của cặp Ứng dụng – OA này hết hiệu lực. Nếu hệ thống đang gửi tin bằng token cũ, Quý khách nhớ cập nhật token mới ngay sau khi lấy.

Bước 3 · Cấp quyền cho Ứng dụng​

Trang Yêu cầu cấp quyền truy cập Official Account sẽ mở trong một cửa sổ mới. Quý khách kiểm tra lại Ứng dụng và OA ở đầu trang (1) đã đúng chưa. Muốn đổi OA khác, chỉ cần nhấn mũi tên bên cạnh tên OA.

Trang Yêu cầu cấp quyền truy cập Official Account, đánh dấu cặp Ứng dụng và OA

Trang cấp quyền liệt kê các quyền Ứng dụng yêu cầu OA cấp.

Kéo xuống cuối trang, tick ô đồng ý Điều khoản sử dụng (1) rồi nhấn Cấp quyền (2).

Cuối trang cấp quyền, đánh dấu ô đồng ý điều khoản và nút Cấp quyền

Đồng ý điều khoản và cấp quyền.

Bước 4 · Nhận Access token và Refresh token​

Quay lại API Explorer, Quý khách sẽ thấy Access token và Refresh token của OA ở hai ô tương ứng trong khung Lấy Access Token. Nhấn biểu tượng sao chép bên cạnh mỗi ô để lưu lại.

Xong rồi! Ứng dụng đã có thể gọi API thay cho OA của Quý khách. Danh sách OA đã uỷ quyền cho Ứng dụng xem tại Zalo for Developers.

Giữ token an toàn: Access token và Refresh token cho phép gửi tin thay mặt OA. Quý khách vui lòng không chia sẻ token qua email, chat hoặc lưu trong mã nguồn công khai.

Cách 2 · Dành cho đội kỹ thuật

Uỷ quyền bằng giao thức OAuth v4

Phù hợp khi hệ thống của Quý khách cần tự động lấy và làm mới token, hoặc khi Quý khách dùng Ứng dụng của bên thứ ba.

  1. Tạo code verifier và code challenge theo phương thức PKCE.
  2. Thiết lập đường dẫn yêu cầu cấp quyền trên Zalo for Developers: khai báo Callback URL, code challenge và chọn các quyền cần OA cấp.
  3. Gửi đường dẫn cho Admin OA. Admin chọn OA và bấm Cấp quyền; Zalo chuyển hướng về Callback URL kèm Authorization code và OA ID.
  4. Gọi API https://oauth.zaloapp.com/v4/oa/access_token (kèm khoá bí mật của Ứng dụng) để đổi Authorization code lấy Access token và Refresh token.

Tham số, mã mẫu và cách làm mới token, đội kỹ thuật xem chi tiết tại Xác thực và ủy quyền cho Ứng dụng và Hướng dẫn lấy khóa bí mật của ứng dụng.

Câu hỏi thường gặp​

Không thấy OA cần uỷ quyền trong danh sách?

Thường là do tài khoản Zalo đang dùng chưa phải Admin của OA đó. Quý khách nhờ Admin hiện tại thêm Quý khách làm Quản trị viên theo Quản lý Admin OA, rồi tải lại trang API Explorer là được.

Không thấy Ứng dụng ở ô Chọn ứng dụng?

Tài khoản Zalo đang dùng chưa phải Quản trị viên của Ứng dụng. Quý khách nhờ Quản trị viên hiện tại của Ứng dụng thêm Quý khách vào Ứng dụng trên Zalo for Developers.

Một OA có uỷ quyền cho nhiều Ứng dụng được không?

Được ạ. Số Ứng dụng một OA được uỷ quyền phụ thuộc vào gói dịch vụ OA; Quý khách xem thêm tại Bảng giá Zalo OA.

Đã uỷ quyền nhưng không chọn được OA khi tạo mẫu tin?

Bước tiếp theo​

Có Access token rồi, Quý khách có thể bắt đầu:

2. Hướng dẫn gửi API ZBS Template Message

Bài viết liên quan​

Cần hỗ trợ thêm?

Gửi yêu cầu qua Mẫu hỗ trợ Zalo Business Solutions. Đội ngũ chăm sóc khách hàng sẽ phản hồi trong vòng 24 giờ làm việc.