Lấy số điện thoại và thông tin người dùng trong Zalo Mini App: quyền và cách xin đúng
Tất cả blog / Hướng dẫn / Lấy số điện thoại và thông tin người dùng trong Zalo Mini App: quyền và cách xin đúng
Lộc Nguyễn14 thg 11, 20269 phút đọc
Trong Zalo Mini App, anh chị lấy số điện thoại bằng hàm getPhoneNumber của zmp-sdk. Người dùng đồng ý trên màn hình xin quyền, mini app nhận một mã token, rồi máy chủ của doanh nghiệp đổi mã đó lấy số qua Zalo Open API. Mã chỉ dùng được một lần và hết hạn sau 2 phút.
Bài này giải thích luồng đó từng bước, vì sao bước đổi mã phải nằm ở máy chủ, xin quyền lúc nào thì đúng chính sách, và dữ liệu cá nhân cần lưu ý gì. Mọi tên hàm, tên tham số và con số tôi lấy từ tài liệu Zalo Mini App mở ngày 09/11/2026. Thứ tự: phân biệt định danh với số điện thoại, luồng ba bước, xin quyền đúng lúc, dữ liệu cá nhân, điểm bất lợi, câu hỏi thường gặp. Tôi không đưa mã mẫu dài; chỗ cần khoá bí mật tôi dùng chỗ giữ chỗ.
Định danh người dùng và số điện thoại là hai việc khác nhau
Nhiều đội làm mini app trộn hai việc này nên viết thừa luồng xin quyền. Tài liệu tách rõ như sau.
Định danh. Hàm getAccessToken lấy token xác thực người dùng. Tài liệu ghi từ phiên bản SDK 2.35.0, ứng dụng mặc định lấy được access token mà không cần người dùng bấm đồng ý; token này chỉ cho ra ID người dùng. ID là chuỗi riêng của từng người dùng trên mỗi Zalo App, không trùng giữa hai người.
Tên và ảnh đại diện. Hàm getUserInfo trả ID, tên, ảnh. Theo tài liệu, để tuân thủ Nghị định 13/2023/NĐ-CP, tên và ảnh phải được người dùng cho phép. Muốn xin luôn khi gọi, truyền tham số autoRequestPermission là true, hoặc gọi trước hàm authorize. Người dùng từ chối thì ứng dụng nhận lỗi mã -1401.
Số điện thoại. Hàm getPhoneNumber, và luôn qua máy chủ mới ra số.
Với cửa hàng chỉ cần nhận diện khách quay lại, ID người dùng thường đã đủ. Số điện thoại chỉ nên xin khi doanh nghiệp thật sự cần liên hệ lại, ví dụ xác nhận đơn hay đăng ký hội viên.
Luồng lấy số điện thoại từ đầu đến cuối
Luồng có ba bước và đi qua ba nơi: điện thoại của khách, mini app, máy chủ của doanh nghiệp.
Luồng lấy số điện thoại: người dùng đồng ý trên điện thoại, mini app nhận mã, máy chủ doanh nghiệp đổi mã lấy số.
Bước 1: mini app gọi getPhoneNumber
Mini app import hàm từ zmp-sdk rồi gọi getPhoneNumber(). Zalo hiện thông báo xin cấp quyền. Chỉ khi người dùng đồng ý, mini app mới nhận kết quả là một object có thuộc tính token. Theo tài liệu, token này chỉ truy xuất thông tin được một lần, hết hạn sau 2 phút.
Bước 2: gửi token lên máy chủ của doanh nghiệp
Mini app dùng fetch hoặc axios gửi token (kèm access token lấy từ getAccessToken) lên máy chủ của anh chị. Tài liệu nhấn mạnh: không làm bước này sẽ gặp lỗi khi gọi các API máy chủ với máy chủ ngay từ mini app. Việc gửi nên đi kèm header xác thực riêng của hệ thống anh chị, ví dụ JWT; tài liệu «Call API» khuyên dùng header thay cho cookie vì mini app không hỗ trợ LocalStorage, SessionStorage và Cookie.
Bước 3: máy chủ đổi token lấy số
Máy chủ gọi GET https://graph.zalo.me/v2.0/me/info với ba header: access_token (token của người dùng), code (token vừa nhận từ getPhoneNumber) và secret_key (khoá bí mật của Zalo App, lấy ở developers.zalo.me). Kết quả có dạng {"data":{"number":"849123456789"},"error":0,"message":"Success"}: số trả về ở định dạng mã quốc gia 84, không có số 0 đầu. Máy chủ chuẩn hoá về định dạng mà hệ thống của anh chị đang dùng rồi trả kết quả cho mini app.
Vì sao bước đổi mã phải ở máy chủ
Lý do nằm ở header secret_key. Khoá bí mật của Zalo App mà để trong mã mini app thì bất kỳ ai tải mini app đều đọc được. Trang «Các lỗi kỹ thuật thường gặp» gọi thẳng việc này là lỗ hổng bảo mật lớn, ngoài ra còn bị chặn bởi CORS hoặc chặn IP. Tài liệu liệt kê các API thuộc nhóm này: đổi token ra số điện thoại hoặc vị trí, gửi thông báo, toàn bộ nhóm Open API, và một số API của Checkout SDK. Cách sửa tài liệu đưa ra là mang logic gọi API ra máy chủ của anh chị.
Hệ quả cho doanh nghiệp nhỏ: muốn lấy số điện thoại, anh chị cần có một máy chủ nhỏ, có tên miền, chạy https. Không cần máy lớn, nhưng không có máy chủ thì không có cách làm đúng. Nếu chưa có, đó là phần việc đội tôi hay làm cùng mini app, xem trang liên hệ làm mini app.
Xin quyền đúng lúc
Nền tảng kiểm duyệt cả luồng xin quyền. Tài liệu getPhoneNumber ghi nền tảng sẽ từ chối xét duyệt mini app có luồng xin quyền chưa rõ ràng hoặc không nêu mục đích. Tôi rút ra bốn nguyên tắc từ tài liệu và chính sách:
Chỉ xin khi người dùng bắt đầu dùng tính năng cần đến số. Ví dụ lúc đặt hàng, lúc điền form đăng ký thẻ thành viên, lúc đăng ký tham dự sự kiện. Không xin ngay khi vừa mở mini app.
Nếu bắt buộc phải có số mới dùng được, hiển thị màn hình giới thiệu (onboarding) giải thích lý do cần số và dùng số vào việc gì.
Cho phép từ chối. Chính sách kiểm duyệt ghi người dùng bấm từ chối vẫn phải dùng được các tính năng không liên quan đến quyền đó.
Không giả giao diện xin quyền của nền tảng. Dùng đúng hộp thoại chuẩn.
Thêm hai chi tiết kỹ thuật cần biết. Thứ nhất, quyền «Số điện thoại» thuộc nhóm User Information Permission và cần cho phép từ cả Zalo lẫn người dùng; tài liệu ghi các quyền nhóm này chỉ có hiệu lực trong một khoảng thời gian rồi bị thu hồi, và nền tảng có tính năng cho người dùng ghi nhớ lựa chọn. Thứ hai, quyền do Zalo cho phép phải gửi yêu cầu ở trang quản lý, mô tả rõ lý do kèm hình ảnh; bộ phận kiểm duyệt xét khi duyệt phiên bản mới. Tài khoản Admin và Developer của Mini App dùng được ngay không cần chờ, nên anh chị dễ tưởng mọi thứ ổn cho tới khi người dùng thường báo lỗi.
Dữ liệu cá nhân: những điều doanh nghiệp phải tự lo
Số điện thoại là dữ liệu cá nhân. Tài liệu của Zalo nhắc Nghị định 13/2023/NĐ-CP về bảo vệ dữ liệu cá nhân ở hai chỗ: trang chính sách kiểm duyệt (mục kiểm định kỹ thuật) và trang getUserInfo. Chính sách kiểm duyệt còn nêu các điều sau, tôi dịch sát ý:
Chỉ yêu cầu các quyền cần thiết cho tính năng, không thu thập dữ liệu vượt phạm vi đã công bố.
Chỉ thu thập dữ liệu cá nhân khi có sự đồng ý rõ ràng và minh bạch.
Không chia sẻ dữ liệu với bên thứ ba khi chưa được người dùng cho phép.
Mini App có nội dung chính sách và điều khoản rõ ràng, nói rõ đơn vị kinh doanh nào chịu trách nhiệm.
Trang getUserInfo còn có trường isSensitive: nếu là true, tài khoản thuộc nhóm người dùng cần nhà phát triển xác minh và xử lý dữ liệu phù hợp pháp luật, ví dụ trẻ em hay người khuyết tật. Tôi không phải luật sư, nên phần nghĩa vụ pháp lý chi tiết anh chị hỏi người tư vấn pháp lý của doanh nghiệp; bài này chỉ chỉ ra chỗ tài liệu đã nhắc.
Điểm bất lợi và rủi ro khi lấy số điện thoại
Tỷ lệ đồng ý không do anh chị quyết. Người dùng có thể từ chối, và tài liệu không công bố tỷ lệ đồng ý trung bình. Tôi không dám hứa con số nào.
Token ngắn hạn. Hết hạn sau 2 phút và dùng một lần, nên máy chủ phải đổi ngay, và phải xử lý trường hợp token đã dùng.
Cần máy chủ và khoá bí mật. Khoá phải được giữ kín ở máy chủ, không đưa vào mã mini app, và ai quản lý khoá cũng phải được phân công rõ.
Chạy thử phải dùng chế độ Device. Trình duyệt và simulator không chạy được các luồng cần môi trường Zalo thật.
Quyền cần duyệt. Thiếu bước xin quyền thì người dùng thường gặp lỗi dù bản thử của anh chị chạy ổn.
Số có thể không đúng người. Điện thoại có thể là số của người khác trong gia đình hay số đã đổi chủ. Với tính năng quan trọng như xác nhận đơn lớn, nên có thêm bước xác nhận khác.
Câu hỏi thường gặp về lấy số điện thoại trong Zalo Mini App
Có lấy số điện thoại mà không hiện hộp xin phép được không?
Không. Theo tài liệu, khi gọi hàm, thông báo xin cấp quyền được hiển thị và chỉ khi người dùng đồng ý mới có số.
Có gọi graph.zalo.me trực tiếp từ mini app được không?
Không nên. Lời gọi cần secret_key, nên tài liệu yêu cầu thực hiện ở máy chủ của doanh nghiệp.
Số điện thoại trả về có số 0 đầu không?
Ví dụ trong tài liệu trả về dạng 849123456789, tức mã quốc gia 84 và không có số 0 đầu. Anh chị tự chuẩn hoá khi lưu.
Người dùng từ chối thì sao?
Chính sách kiểm duyệt yêu cầu người dùng vẫn dùng được các tính năng không liên quan tới quyền bị từ chối. Anh chị nên cho họ đường thay thế, ví dụ nhập số tay hoặc nhắn qua kênh khác.
Có cần xin Zalo cấp quyền trước không?
Có, với người dùng thường. Số điện thoại thuộc quyền cần cho phép từ Zalo và từ người dùng. Admin và Developer của Mini App thử được ngay.
Nguồn: docs.zaloplatforms.com/docs/MA (api/user/user-information/getPhoneNumber, getAccessToken, getUserInfo; intro/request-permission; intro/best-practices/authen-user, call-restful-api; getting-started/frequently-solved-issues; intro/censorship-overview) và miniapp.zaloplatforms.com/documents/zalo-mini-app-censorship-policy, kiểm ngày 09/11/2026.
Zalo Mini App có thanh toán phải tích hợp Checkout SDK của nền tảng. Có hai giải pháp: nền tảng làm trung gian xử lý với ZaloPay, MoMo, VNPay, PayME, hoặc tự xử lý giao dịch khi được duyệt. Điều kiện cần có gồm xác thực chủ sở hữu và máy chủ nhận kết quả.
Mini App phải qua hai việc trước khi mở cho mọi người dùng: xác thực chủ sở hữu và xét duyệt phiên bản. Theo chính sách, thời gian kiểm duyệt là 3 ngày làm việc. Hồ sơ cần chuẩn bị gồm giấy tờ xác thực, giấy phép con nếu ngành có điều kiện, và bản Testing đã chạy ổn.
Để tạo Zalo Mini App đầu tiên, anh chị cần bốn việc nối nhau: một Zalo App ở developers.zalo.me, một Mini App trong trang quản lý để lấy Mini App ID, một dự án mã nguồn tạo bằng Zalo Mini App Extension trên Visual Studio Code, rồi chạy thử trên điện thoại bằng chế độ Device hoặc bản Development.