zalo-mini-app

name	zalo-mini-app
description	Build Zalo Mini Apps - lightweight React web apps running inside the Zalo super-app. Use for Zalo Mini App setup, zmp-cli/devtools, ZaUI 1.11.x components, zmp-sdk APIs, permissions, token-based phone number flow, user info, storage, local file storage, camera/media, document preview, payment/Checkout, Open APIs, partner APIs, KYB/eKYC, publication, testing, and Zalo design guidelines.

Zalo Mini App Development

Build Mini Apps for the Zalo platform using React, ZaUI, zmp-sdk, Zalo Mini App CLI/Extension, and platform Open APIs.

Docs baseline: official Zalo Mini App docs checked on 2026-06-24.

Quick Start

npm install -g zmp-cli
zmp create my-app
cd my-app
zmp start

Core packages:

npm install zmp-ui zmp-sdk

import { App, Page, Button, Input, Modal } from "zmp-ui";
import "zmp-ui/zaui.css";
import { getUserInfo, authorize } from "zmp-sdk/apis";

Current package versions observed on 2026-06-24:

• zmp-sdk: 2.51.x
• zmp-ui: 1.11.x
• zmp-cli: 4.0.x

Always verify package types in the installed project when implementing exact props or SDK return types.

References

Setup & Release

• getting-started.md - Create app, auth, permissions, CLI/Extension, test, publish
• design-guidelines.md - Zalo design standards and review checklist
• web-design-guidelines.md - Accessibility, mobile UX, forms, performance
• react-best-practices.md - Waterfalls, bundle size, re-renders, JS performance

SDK APIs

• api-overview.md - API groups, import patterns, error handling
• api-user.md - authorize, getUserInfo, token-based getPhoneNumber, getAccessToken
• api-storage.md - Storage APIs and legacy aliases
• api-ui.md - toast, navigation bar, webview, routing
• api-device.md - location, camera, media picker, document, QR/NFC, network
• api-local-file-storage.md - Local File Storage APIs
• api-permission-biometric.md - permissions and biometric auth
• api-advertising-widgets.md - ads and function/OA widgets
• api-zalo.md - OA, chat, sharing, profile, shortcuts

Payment / Backend APIs

• payment-checkout.md - Payment integration, order, callback, status, refund
• open-apis.md - Open APIs, partner APIs, signature verification, KYB notes
• ekyc-apis.md - eKYC API map and secure integration notes

ZaUI Components

• zaui-overview.md - Component list and design tokens
• zaui-layout.md - App, Page, Header, Router, BottomNavigation, Box utilities
• zaui-display.md - Avatar, Icon, List, Swiper, Calendar, Text
• zaui-form.md - Button, Input, Select, DatePicker, OTP, Slider
• zaui-overlay.md - Modal, Sheet, ActionSheet, SnackbarProvider

Critical Current Patterns

Phone Number: Token Flow, Not Direct Number

import { getPhoneNumber } from "zmp-sdk/apis";

const { token } = await getPhoneNumber({});
// Send token to backend immediately.
// Backend exchanges token with Zalo Open API to get the actual phone number.
// Token is single-use and short-lived.

Do not expect getPhoneNumber to return { number } in current docs.

Location: Token Flow, Not Direct Coordinates

import { getLocation } from "zmp-sdk/apis";

const { token } = await getLocation();
// Send token to backend for Zalo Open API exchange.

Do not expect getLocation to return direct { latitude, longitude } in current docs.

Local File Storage: LFSStorage Namespace

import { LFSStorage } from "zmp-sdk/apis";

const { support } = await LFSStorage.isSupportLFS();
const { savedPath } = await LFSStorage.saveFile({ filePath: "local-temp-path" });

Use filePath / savedPath, not old tempFilePath helpers.

Media Picker: Current Shape

import { openMediaPicker } from "zmp-sdk/apis";

const { data } = await openMediaPicker({
  type: "photo",
  maxSelectItem: 5,
  serverUploadUrl: "https://example.com/upload"
});

Use maxSelectItem, not maxSelection.

Basic Page Layout

import { App, Page, Header, List, Icon, BottomNavigation } from "zmp-ui";

export default function Root() {
  return (
    <App>
      <Page>
        <Header title="Home" />
        <List>
          <List.Item title="Item" suffix={<Icon icon="zi-chevron-right" />} />
        </List>
      </Page>
      <BottomNavigation fixed>
        <BottomNavigation.Item key="home" label="Home" icon={<Icon icon="zi-home" />} />
      </BottomNavigation>
    </App>
  );
}

Resources

• Docs: https://miniapp.zaloplatforms.com/documents/
• API: https://miniapp.zaloplatforms.com/documents/api/
• ZaUI: https://miniapp.zaloplatforms.com/documents/zaui/
• Payment: https://miniapp.zaloplatforms.com/documents/payment/
• Open APIs: https://miniapp.zaloplatforms.com/documents/open-apis/
• Mini App Center: https://miniapp.zaloplatforms.com/