Hướng dẫn lấy App ID, App Secret và OA Secret Key từ Zalo

Bạn cần App ID, App Secret và OA Secret Key để kết nối Zalo với phần mềm? Cả ba thông tin đều được lấy trong ứng dụng trên Zalo for Developers. Chúng không phải ba ô nằm trong trang thông tin doanh nghiệp của OA Manager.

Nếu chưa có tài khoản OA, hãy làm trước theo hướng dẫn đăng ký và xác thực Zalo OA. Sau khi có OA, bạn cần mở đúng ứng dụng doanh nghiệp được quyền quản lý. Nếu chưa có, xem cách tạo ứng dụng trên Zalo Developers.

1. Phân biệt App ID, App Secret, OA Secret Key và OA ID

• App ID / ID ứng dụng: mã xác định ứng dụng đang kết nối. Sao chép ở mục Cài đặt của ứng dụng, không lấy mã OA điền thay.
• App Secret / Khóa bí mật của ứng dụng: khóa dùng trong quá trình xác thực của ứng dụng, chẳng hạn khi hệ thống lấy hoặc làm mới thông tin truy cập. Khóa phải thuộc đúng App ID.
• OA Secret Key: khóa tại mục Webhook của ứng dụng, dùng để kiểm tra thông báo sự kiện Zalo gửi về hệ thống có hợp lệ hay không. Dù có chữ “OA”, vị trí lấy khóa này là trang Webhook trong Zalo for Developers.
• OA ID: mã của Official Account, xem ở OA Manager. Ví dụ OA Công ty Dybicom có mã 4133621167770884605; đây không phải App ID.

Access Token và Refresh Token là các mã truy cập được cấp trong một luồng kết nối. Không dùng chúng thay cho App Secret hoặc OA Secret Key. Nếu dịch vụ của bạn tự quản lý token sau khi cấp quyền, hãy làm theo luồng kết nối của dịch vụ thay vì tự tạo token rồi gửi qua tin nhắn.

2. Mở đúng ứng dụng trước khi lấy thông số

Đăng nhập Zalo Developers, mở danh sách ứng dụng rồi đối chiếu tên, App ID và hệ thống doanh nghiệp đang sử dụng. Nếu chưa có ứng dụng hoặc chưa biết tài khoản nào quản lý, làm theo hướng dẫn tạo và quản lý ứng dụng Zalo trước khi tiếp tục.

Khi đã mở đúng ứng dụng, giữ nguyên ứng dụng đó để lần lượt lấy App ID, App Secret và OA Secret Key. Đổi ứng dụng giữa chừng dễ làm bạn ghép ID của ứng dụng này với khóa của ứng dụng khác.

3. Lấy App ID và App Secret trong Cài đặt ứng dụng

1. Chọn đúng ứng dụng trong danh sách, sau đó mở Cài đặt.
2. Tìm ô ID ứng dụng. Sao chép đầy đủ dãy số và lưu dưới dạng văn bản nếu dùng bảng tính, để mã không bị chuyển thành số khoa học hoặc mất chữ số.
3. Ở ô Khóa bí mật của ứng dụng, dùng biểu tượng sao chép. Nếu cần xem giá trị, dùng nút hiển thị theo giao diện và thực hiện yêu cầu bảo mật của Zalo.
4. Chuyển khóa trực tiếp vào ô cấu hình bảo mật của hệ thống cần kết nối hoặc nơi lưu trữ an toàn do doanh nghiệp quy định.
5. Kiểm tra App ID và App Secret được lấy trong cùng ứng dụng; không để khoảng trắng, dấu ngoặc hoặc xuống dòng thừa.

Vị trí ID ứng dụng và Khóa bí mật tại Cài đặt. Ảnh hướng dẫn của Zalo Platforms đã che thông tin; đây không phải thông số ứng dụng của DYBICOM. Xem hướng dẫn Zalo. Mở ảnh kích thước đầy đủ.

Chuỗi dấu sao dùng để che khóa không phải giá trị để nhập. Cũng không cần đổi khóa chỉ vì muốn sao chép lại. Bạn có thể đối chiếu vị trí và nút sao chép trong hướng dẫn lấy App Secret Key của Zalo.

4. Lấy OA Secret Key tại mục Webhook

Webhook là cơ chế Zalo gửi sự kiện tới địa chỉ nhận của hệ thống, ví dụ khi có người nhắn tin hoặc một sự kiện cần xử lý. OA Secret Key giúp hệ thống kiểm tra tính hợp lệ của thông báo đó; nó không phải địa chỉ Webhook URL.

1. Giữ nguyên ứng dụng vừa lấy App ID và App Secret.
2. Chọn Webhook trong menu của ứng dụng.
3. Tìm ô có nhãn OA Secret Key, không sao chép nhầm ô Webhook URL phía trên.
4. Nếu khóa đang được che, dùng chức năng hiển thị theo giao diện, sao chép nguyên giá trị rồi lưu vào nơi cấu hình bảo mật được yêu cầu.
5. Che lại khóa khi xong và kiểm tra không đưa khóa vào ảnh chụp, nội dung website hoặc kho mã công khai.

OA Secret Key nằm tại mục Webhook của ứng dụng và là ô khác với Webhook URL. Ảnh từ hướng dẫn Webhook của Zalo; các khóa đang được che. Xem hướng dẫn Zalo. Mở ảnh kích thước đầy đủ.

Nếu màn hình chưa có ô khóa, đừng lấy App Secret điền thay và đừng bấm Reset chỉ để thử. Đối chiếu hướng dẫn Webhook của Zalo và yêu cầu của hệ thống tích hợp. Có trường hợp cần hoàn thiện thiết lập Webhook trước; URL phải lấy từ hệ thống thực sự tiếp nhận sự kiện, không tự điền địa chỉ trang chủ cho đủ ô.

Chỉ cần lấy khóa thì không đổi URL, bật/tắt sự kiện hoặc thay bộ lọc cú pháp của một kết nối đang hoạt động. Những tùy chọn đó thay đổi dữ liệu hệ thống nhận được; người triển khai cần kiểm tra theo chức năng đang dùng.

5. Ví dụ lấy nhầm thông số giữa hai ứng dụng

Giả sử doanh nghiệp có ứng dụng A cho website và B cho một hệ thống khác. Bạn lấy App ID của A nhưng mở B để sao chép App Secret hoặc OA Secret Key. Từng ô đều có giá trị, nhưng bộ thông tin bị ghép sai.

Cách làm đúng là mở A, đối chiếu tên và App ID, lấy App Secret tại Cài đặt rồi chuyển sang Webhook của chính A để lấy OA Secret Key. Khi ghi vào nơi lưu trữ bảo mật, ghi kèm tên ứng dụng, App ID, hệ thống sử dụng và người phụ trách. Không đưa khóa thật vào bảng theo dõi công khai chỉ để dễ nhận biết.

Với OA Công ty Dybicom, mã OA 4133621167770884605 chỉ giúp xác định đúng tài khoản doanh nghiệp khi cấp quyền. Nó không làm cho các khóa của một ứng dụng khác trở thành đúng.

6. Không thấy ứng dụng, không thấy khóa hoặc kết nối báo lỗi

• Danh sách ứng dụng trống: kiểm tra tài khoản đăng nhập, hỏi người đang quản lý ứng dụng; đừng vội tạo nhiều ứng dụng trùng mục đích.
• Có quyền OA nhưng không quản lý được ứng dụng: quyền Admin OA và quyền quản lý ứng dụng là hai phạm vi riêng. Nhờ người quản lý đúng tài nguyên kiểm tra quyền của bạn.
• Ứng dụng chưa hoạt động hoặc thiếu quyền API: xem phần trạng thái và quyền API trong hướng dẫn quản lý ứng dụng Zalo. Có khóa không tự làm các quyền còn thiếu xuất hiện.
• App Secret không hợp lệ: kiểm tra đúng cặp App ID/khóa, ký tự thừa và việc khóa đã bị thay sau lần sao chép hay chưa.
• Hệ thống không xác thực được sự kiện: kiểm tra OA Secret Key thuộc ứng dụng nào và cấu hình đang dùng ở hệ thống nhận; không kết luận chỉ từ việc “đã lưu khóa”.

Khi nhờ hỗ trợ, gửi App ID, OA ID, bước thao tác và thông báo lỗi đã che dữ liệu bí mật. Không gửi App Secret, OA Secret Key, token hoặc mật khẩu qua bình luận công khai.

7. Nếu khóa đã lộ hoặc cần thay đổi

Trước khi đổi khóa, xác định các dịch vụ đang dùng ứng dụng và ai chịu trách nhiệm cập nhật. Thực hiện thay khóa theo chức năng Zalo cung cấp, cập nhật những nơi dùng khóa cũ rồi kiểm tra lại kết nối và sự kiện. Đổi OA Secret Key ảnh hưởng phần kiểm tra Webhook; không coi nó là thao tác giống hệt đổi App Secret.

Người chỉ phụ trách trả lời khách hoặc đăng bài thường không cần nắm các khóa này. Bạn có thể dùng hướng dẫn quản lý Zalo OA để giao đúng công việc mà không chia sẻ tài khoản đăng nhập.

Khi đã có đúng bộ thông tin và được doanh nghiệp cho phép tích hợp, chuyển sang hướng dẫn cấu hình kết nối Zalo OA trong CMS. Bài đó chỉ rõ URL callback, Webhook và quy trình cấp quyền, lưu cấu hình, kiểm tra thông báo trên Dybi.