Để 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.
Bài này đi theo đúng thứ tự đó, dựa trên tài liệu nhà phát triển của Zalo Mini App mà tôi mở hôm nay, 09/11/2026. Tôi viết cho hai nhóm: chủ doanh nghiệp muốn hiểu việc gì cần làm và ai làm, và lập trình viên mới muốn có đường đi ngắn nhất. Thứ tự các mục: cần chuẩn bị gì, bốn bước chính, chọn chế độ chạy thử, các lỗi hay gặp, phần xác thực trước khi phát hành, điểm bất lợi của việc tự làm, câu hỏi thường gặp. Tôi không ghi giá hay thời gian làm vì tài liệu không công bố những con số đó.
Cần chuẩn bị gì trước khi bắt đầu
Sơ đồ tổng quan trong tài liệu ghi bước đầu tiên là chuẩn bị tài khoản Zalo của người đại diện pháp luật của doanh nghiệp (gọi là Merchant). Tài khoản này dùng để đăng nhập developers.zalo.me. Bản phát hành thật phải xác thực chủ sở hữu, nên tôi khuyên chọn đúng người ngay từ đầu để đỡ phải đổi sau.
Danh sách chuẩn bị tôi hay đưa cho chủ doanh nghiệp:
- Tên hiển thị, điện thoại liên hệ, email liên hệ, danh mục Mini App và mô tả. Tài liệu liệt kê đây là các trường bắt buộc khi tạo ứng dụng.
- Tên, logo, banner, mô tả đã chốt. Tài liệu cảnh báo: đổi tên, mô tả, logo, banner, loại hình sở hữu hay danh mục sau khi tạo phải mở ticket hỗ trợ và chờ bộ phận kiểm duyệt xác nhận.
- Máy tính cài Visual Studio Code và điện thoại có ứng dụng Zalo.
- Một người giữ Khóa bí mật của Zalo App. Khóa này dùng ở bước phát triển, không dán vào mã chạy trên điện thoại.
Bốn bước từ tài khoản đến bản chạy thử
Mỗi bước dưới đây có trong mục «2.2 Triển khai» của tài liệu. Tôi tóm lại việc phải bấm và thứ nhận được ở cuối mỗi bước.
Bước 1: tạo Zalo App
Vào developers.zalo.me, đăng nhập bằng tài khoản Zalo, tạo ứng dụng mới hoặc dùng ứng dụng có sẵn. Tài liệu giải thích Zalo App là ứng dụng trên nền tảng Zalo, làm việc với API OAuth và các API dữ liệu; một Zalo App chứa được nhiều Mini App. Trong phần Cài đặt, chọn Kích hoạt ứng dụng để người dùng bên ngoài dùng được, và lưu lại Khóa bí mật.
Bước 2: tạo Mini App và lấy Mini App ID
Vào trang quản lý ứng dụng ở mini.zalo.me/developers, chọn Quản lý ứng dụng ở góc phải, chọn Zalo App vừa tạo, bấm Tạo Mini App, điền thông tin rồi bấm Tạo mới. Thứ nhận được là Mini App ID. Bước sau cần chính mã này.
Bước 3: tạo dự án trong Zalo Mini App Extension
Cài tiện ích Zalo Mini App Extension từ menu Extensions của Visual Studio Code hoặc từ Marketplace. Tiện ích này cho phép khởi tạo (init), khởi động (start), đóng gói (build) và xuất bản (deploy) dự án. Bấm Tạo Mới, rồi chọn template, thư mục lưu và tên dự án. Template trống có tuỳ chọn Vite 2 hoặc Vite 5, JavaScript hoặc TypeScript; ngoài ra có template do nền tảng cung cấp, dùng ZaUI và theo bộ Design Guidelines. Sau khi tạo xong, bấm Cấu hình và nhập Mini App ID để liên kết dự án.
Bước 4: chạy thử trên điện thoại
Trong menu Phát triển, chọn chế độ Device để chạy ứng dụng Zalo thật trên điện thoại. Điện thoại không cần cùng mạng với máy tính. Muốn gửi cho người khác xem, dùng chức năng Xuất bản với loại phiên bản Development hoặc Testing. Xuất bản xong, tiện ích báo Deploy Thành Công kèm mã QR và deep link để mở Mini App.
Chế độ chạy thử nào dùng lúc nào
Tài liệu mô tả năm chế độ khởi động. Tôi gom thành bảng để chọn nhanh:
| Chế độ | Chạy ở đâu | Dùng khi |
|---|---|---|
| Device | Ứng dụng Zalo trên điện thoại thật | Cần gọi getUserInfo, getPhoneNumber, followOA, openShareSheet như bản thật |
| Simulator | Hộp mô phỏng ngay trong Visual Studio Code | Sửa giao diện, xem DevTools trong một cửa sổ |
| Chrome/Edge Debugger | Phiên gỡ lỗi Chrome hoặc Edge | Cần đặt breakpoint, chạy từng dòng |
| Trình duyệt mặc định | Trình duyệt web của máy | Xem nhanh giao diện |
| Không sử dụng | Chỉ chạy máy chủ hot reload | Tự chọn cách xem trước |
Điểm tôi muốn anh chị nhớ: phần «lỗi thường gặp» của tài liệu nói rõ trình duyệt và simulator chỉ cho xem giao diện, không chạy được các luồng như getAccessToken hay createOrder, vì các luồng này cần môi trường thật bên trong ứng dụng Zalo. Muốn thử đăng nhập hay thanh toán, phải dùng chế độ Device.
Các lỗi hay gặp khi mới làm
Danh sách dưới đây rút từ trang «Các lỗi kỹ thuật thường gặp», kiểm 09/11/2026:
- Mở bản thử bằng tài khoản không phải Developer hay Admin. Zalo báo «Trang này không tìm thấy hoặc không hợp lệ». Bản Development và Testing chỉ mở được bằng tài khoản có vai trò trong Mini App.
- Gọi API từ máy chủ của anh chị bị chặn CORS. Mini App chạy trên hệ thống domain của Zalo, nên máy chủ phải trả header
Access-Control-Allow-Originđúng một giá trị, không phải nhiều giá trị cách nhau bởi dấu phẩy, và phải đáp ứng cả phương thức OPTIONS. - Gọi API không có tên miền, không có https hoặc chứng chỉ SSL hết hạn. Đây cũng là nguyên nhân hay gặp khi ảnh không hiển thị.
- Gọi API máy chủ với máy chủ từ trong Mini App, ví dụ đổi token ra số điện thoại hoặc gửi thông báo. Tài liệu coi đây là lỗ hổng bảo mật vì phải kèm khóa bí mật; cách sửa là đưa logic đó sang máy chủ của anh chị.
- Chạy ổn với Admin nhưng lỗi với người dùng thường. Thường do chưa xin cấp quyền cho các API như
getPhoneNumber,getLocation,openMediaPicker, nhóm Native Storage. Admin và Developer dùng được tất cả để tiện tích hợp, người dùng thường thì không. - Hết lượt xuất bản. Mỗi Mini App có hạn mức 300 lượt mỗi tháng với bản Development và 60 lượt mỗi tháng với bản Testing.
- Gói quá nặng. Mỗi phiên bản tối đa 10 MB cho cả ứng dụng và 3 MB cho mỗi tệp. Ảnh, video nên để trên máy chủ hoặc CDN của anh chị.
Khi cần xem lỗi trên bản đã phát hành, tài liệu hướng dẫn thêm tham số zDebug=true vào deep link để hiện công cụ gỡ lỗi.
Xác thực trước khi phát hành
Tạo xong bản chạy thử chưa phải là xong. Tài liệu ghi xác thực Mini App là bước định danh chủ sở hữu hợp pháp; nó không cản việc xây dựng nhưng bắt buộc hoàn tất trước khi phát hành. Có hai phương thức, chọn một: qua Official Account đã xác thực của doanh nghiệp (thời gian xử lý 3 ngày làm việc), hoặc nộp bộ tài liệu KYB khi chưa có OA hoặc OA chưa xác thực (3 đến 5 ngày làm việc kể từ khi nhận đủ tài liệu). Ngành nghề có điều kiện cần thêm giấy phép con. Chi tiết từng hạng mục kiểm duyệt và cách soát trước khi gửi, anh chị xem thêm ở chuyên mục hướng dẫn trên blog.
Điểm bất lợi khi tự làm lần đầu
- Chạy thử đúng nghĩa cần điện thoại thật. Simulator không thay được chế độ Device với đăng nhập, thanh toán, số điện thoại.
- Thông tin ứng dụng khó sửa sau khi tạo. Mỗi lần đổi tên hay mô tả là một ticket, nên điền kỹ từ đầu.
- Cần máy chủ riêng cho nhiều tính năng. Đổi token, nhận kết quả thanh toán, lưu đơn hàng đều làm ở máy chủ. Mini App chỉ là phần giao diện.
- Có hạn mức xuất bản và dung lượng. Làm việc theo nhóm nhiều người dễ chạm 60 lượt Testing mỗi tháng nếu xuất bản bừa bãi.
- Có khối lượng hồ sơ ngoài mã nguồn. Xác thực, xin quyền API, soát chính sách là việc của chủ doanh nghiệp, không thay được bằng viết mã.
Nếu anh chị muốn có sản phẩm chạy sớm và không muốn tự xử lý các phần trên, tài liệu của Zalo có mục liên hệ đối tác giải pháp, và đội của tôi cũng nhận làm; anh chị có thể xem các trường hợp đã làm hoặc để lại nhu cầu ở trang liên hệ làm mini app.
Câu hỏi thường gặp về tạo Zalo Mini App
Có cần biết lập trình mới tạo được Zalo Mini App không?
Tạo Zalo App và Mini App trên trang quản lý thì không cần. Phần giao diện và logic thì cần lập trình viên, hoặc nhờ đối tác. Template có sẵn giúp dự án có khung ban đầu.
Một Zalo App tạo được bao nhiêu Mini App?
Tài liệu ghi một Zalo App có thể chứa nhiều Mini App. Con số giới hạn cụ thể không có trong trang tôi đã mở, nên anh chị xem lại trang quản lý khi tạo.
Dự án dùng framework nào?
Template trống của Extension dùng Vite, bản 2 hoặc bản 5, với JavaScript hoặc TypeScript. Template mẫu của nền tảng dùng ZaUI. Lệnh cài thư viện SDK trong tài liệu là npm install zmp-sdk.
Chạy thử có cần điện thoại cùng mạng wifi với máy tính không?
Không. Tài liệu ghi điện thoại không cần cùng mạng với máy tính khi dùng chế độ Device.
Chạy thử xong, bao lâu thì công khai được?
Phụ thuộc xác thực và kiểm duyệt. Trang chính sách ghi thời gian kiểm duyệt là 3 ngày làm việc, không tính thứ Bảy, Chủ Nhật và ngày lễ. Thời gian của anh chị còn cộng thêm phần sửa theo phản hồi nếu bị từ chối.
Nguồn: tài liệu Zalo Mini App, docs.zaloplatforms.com/docs/MA (mục intro/getting-started, intro/overview, devtools/ext/install, ext/init, ext/start, ext/deploy, getting-started/frequently-solved-issues, api/intro) và miniapp.zaloplatforms.com/documents (chính sách kiểm duyệt), kiểm ngày 09/11/2026.