zmp-sdk 2.45.2 → 2.46.0-beta.2

package/apis/index.d.ts

@@ -880,14 +880,28 @@ type AsyncProgressCallback = {
     fail?: ((err: AsyncCallbackFailObject) => void) | undefined;
 };
 type GetLocationReturns = {
-    /** latitude */
+    /**
+     * @deprecated
+     */
     latitude?: string;
-    /** longitude */
+    /**
+     * @deprecated
+     */
     longitude?: string;
-    /** timestamp */
+    /**
+     * @deprecated
+     */
     timestamp?: string;
-    /** provider */
+    /**
+     * @deprecated
+     */
     provider?: string;
+    /**
+     * Là một chuỗi ký tự dùng để truy xuất thông tin vị trí thông qua server. Mỗi Token được cung cấp, bạn sẽ có thể truy xuất thông tin được 1 lần với thời gian hết hạn sau 2 phút.
+     *
+     * @minimumVersion Zalo App: 23.02.01
+     * @minimumVersion ZMP SDK: 2.29.0
+     */
     token?: string;
 };
 type CameraParams = {
@@ -896,19 +910,39 @@ type CameraParams = {
     videoElement: HTMLVideoElement;
 };
 interface SystemInfo {
-    /** Mini app version */
+    /**
+     * Phiên bản đang được sử dụng của Zalo Mini App này.
+     */
     version: string;
-    /** SDK version */
+    /**
+     * Phiên bản đang sử dụng của ZMP SDK.
+     */
     apiVersion: string;
-    /** Zalo version */
+    /**
+     * Phiên bản của ứng dụng Zalo trên thiết bị.
+     */
     zaloVersion: string;
-    /** Client platform */
-    platform: string;
-    /** Language set in Zalo */
+    /**
+     * Thông tin hệ điều hành của thiết bị.
+     */
+    platform: "android" | "iOS" | "wp" | "unknown" | "";
+    /**
+     * Ngôn ngữ hiển thị của thiết bị.
+     */
     language: string;
-    /** Language set in Zalo */
+    /**
+     * Ngôn ngữ hiển thị của ứng dụng Zalo trên thiết bị.
+     * @minimumVersion Zalo iOS: 22.03.01.r2
+     * @minimumVersion Zalo Android: 21.09.01
+     * @minimumVersion ZMP SDK: 2.17.3
+     */
     zaloLanguage: string;
-    /** Theme set in Zalo */
+    /**
+     * Theme hiện tại của ứng dụng Zalo trên thiết bị.
+     * @minimumVersion Zalo iOS: 22.03.01.r2
+     * @minimumVersion Zalo Android: 21.09.01
+     * @minimumVersion ZMP SDK: 2.17.3
+     */
     zaloTheme: string;
 }
 type SetStorageReturns = {
@@ -918,23 +952,70 @@ type GetStorageReturns = {
     [key: string]: any;
 };
 type StorageInfo = {
+    /**
+     * Không gian hiện tại bị chiếm (tính bằng KB)
+     * @minimumVersion 2.43.0
+     */
     currentSize: number;
+    /**
+     * Giới hạn kích thước không gian (tính bằng KB)
+     * @minimumVersion 2.43.0
+     */
     limitSize: number;
 };
 type RemoveStorageReturns = {
     errorKeys: string[];
 };
+type UserInfo = {
+    /**
+     * Chuỗi định danh người dùng theo Zalo App. Chuỗi này là duy nhất cho mỗi người dùng trên mỗi Zalo App. Các Mini App cùng chung một Zalo App ID sẽ có thể dùng chuỗi này để định danh người dùng. Có thể sử dụng ID này để gửi thông báo tới người dùng qua OA chung của Zalo Mini App, tham khảo tại [đây](https://mini.zalo.me/documents/open-apis/notifications/send/).
+     */
+    id: string;
+    /**
+     * Tên hiển thị của người dùng.
+     */
+    name: string;
+    /**
+     * Ảnh đại diện người dùng.
+     */
+    avatar: string;
+    /**
+     * Chuỗi định danh người dùng theo Official Account. Có thể sử dụng ID này để gửi tin nhắn cho người dùng (xem [cách gửi tin nhắn với idByOA](https://mini.zalo.me/documents/intro/send-message-oa-to-user/)). Chuỗi có giá trị nếu thỏa 1 trong các điều kiện dưới đây:
+     * - Mini App đã được xác thực bởi Official Account, chi tiết xem [tại đây](https://mini.zalo.me/blog/thong-bao-huong-dan-xac-thuc-mini-app-qua-zalo-oa/#3.b).
+     * - Zalo App phải được liên kết với Official Account và người dùng đã follow Official Account đó.
+     *
+     * @minimumVersion 2.23.3
+     */
+    idByOA?: string;
+    /**
+     * Trạng thái theo dõi Official Account đã được liên kết với Zalo App.
+     *
+     * @minimumVersion 2.23.3
+     */
+    followedOA?: boolean;
+    /**
+     * Trả về 1 trong 2 giá trị:
+     * - `true`: tài khoản này thuộc nhóm người dùng cần nhà phát triển Mini App xác minh và áp dụng các cơ chế xử lý dữ liệu phù hợp theo quy định Pháp luật, có thể bao gồm nhưng không giới hạn người đã chết hoặc mất tích, người không biết chữ, người khuyết tật, trẻ em,…
+     * - `false`: tài khoản này thuộc nhóm người dùng bình thường.
+     *
+     * @minimumVersion 2.28.0
+     */
+    isSensitive?: boolean;
+};
 type GetUserInfoReturns = {
-    userInfo: {
-        id: string;
-        name: string;
-        avatar: string;
-        idByOA?: string;
-        isSensitive?: boolean;
-        followedOA?: boolean;
-    };
+    /**
+     * Thông tin người dùng.
+     */
+    userInfo: UserInfo;
 };
 type GetNetworkTypeReturns = {
+    /**
+     * Kiểu kết nối mạng hiện tại với các giá trị:
+     * - `none`: Không có mạng.
+     * - `wifi`: Mạng Wi-Fi.
+     * - `cellular`: Mạng di động (2g/3g/4g).
+     * - `unknown`: Mạng không xác định (Android).
+     */
     networkType: NetworkType;
 };
 type iBeaconInfo = {
@@ -956,13 +1037,42 @@ type ScanQRCodeReturns = {
     content: string;
 };
 type OpenPostFeedReturns = {
+    /**
+     * Trạng thái chia sẻ:
+     * - `0`: User nhấn hủy/cancel bài viết.
+     * - `1`: Đăng bài viết thành công.
+     */
     status: 0 | 1;
+    /**
+     * Trạng thái bài chia sẻ:
+     * - `0`: Công khai.
+     * - `1`: Chỉ mình tôi.
+     * - `2`: Chia sẻ cho danh sách bạn.
+     */
     shareType: 0 | 1 | 2;
+    /**
+     * Số lượng user nhận được bài chia sẻ trong trường hợp `shareType=2`.
+     */
     numberOfUser: number;
 };
 type OpenShareSheetReturns = {
+    /**
+     * Trạng thái chia sẻ:
+     * - `0`: User nhấn hủy/cancel bài viết.
+     * - `1`: Đăng bài viết thành công lên nhật ký.
+     * - `2`: Đăng bài viết thành công qua cửa sổ chat.
+     */
     status: 0 | 2 | 1;
+    /**
+     * Trạng thái bài chia sẻ:
+     * - `0`: Công khai.
+     * - `1`: Chỉ mình tôi.
+     * - `2`: Chia sẻ cho danh sách bạn.
+     */
     shareType: 0 | 2 | 1;
+    /**
+     * Số lượng user nhận được bài chia sẻ trong trường hợp `shareType=2`.
+     */
     numberOfUser: number;
 };
 type RequestCameraPermissionReturns = {
@@ -992,36 +1102,91 @@ type OpenWebviewReturns = {
     success: boolean;
 };
 type GetAppInfoReturns = {
+    /**
+     * Tên Zalo Mini App.
+     */
+    name: string;
+    /**
+     * Mô tả Zalo Mini App.
+     */
     description: string;
+    /**
+     * Phiên bản live hiện tại.
+     */
     version: string;
-    name: string;
+    /**
+     * Link chia sẻ Zalo Mini App.
+     */
     appUrl: string;
+    /**
+     * Link QR của Zalo Mini App.
+     */
     qrCodeUrl: string;
+    /**
+     * Đường dẫn đến hình ảnh logo của Zalo Mini App.
+     */
     logoUrl?: string;
 };
 type GetPhoneNumberReturns = {
+    /**
+     * @deprecated
+     */
     number?: string;
+    /**
+     * Là một chuỗi ký tự dùng để truy xuất thông tin số điện thoại thông qua server. Mỗi token được cung cấp chỉ có thể truy xuất thông tin được 1 lần với thời gian hết hạn sau 2 phút.
+     */
     token?: string;
 };
+type ProfileInfo = {
+    /**
+     * Tên hiển thị của người dùng.
+     */
+    name: string;
+    /**
+     * Ảnh đại diện người dùng.
+     */
+    avatar: string;
+};
+type PickedProfile = {
+    /**
+     * Mã người dùng. Chuỗi này là duy nhất cho mỗi người dùng trên mỗi ứng dụng Zalo App. Các Zalo Mini App cùng chung một Zalo App sẽ dùng được mã người dùng của nhau.
+     */
+    id: string;
+    /**
+     * Thông tin của người dùng.
+     */
+    profile: ProfileInfo;
+    /**
+     * Mã lỗi:
+     * - 0: Lấy thông tin của người dùng thành công.
+     * - 1: Lấy thông tin người dùng thất bại.
+     */
+    code: number;
+    /**
+     * Thông báo lỗi.
+     */
+    message: string;
+};
 type OpenProfilePickerReturns = {
-    users: {
-        id: string;
-        profile: {
-            name: string;
-            avatar: string;
-        };
-        code: number;
-        message: string;
-    }[];
+    /**
+     * Danh sách những bạn bè được chọn.
+     */
+    users: PickedProfile[];
 };
 type OpenMediaPickerReturns = {
+    /**
+     * Toàn bộ nội dung trả về của server upload media.
+     */
     data: string;
 };
-/**
- * Context info
- */
 type ContextInfo = {
-    type?: string;
+    /**
+     * Ngữ cảnh hiện tại là người dùng hoặc nhóm chat.
+     */
+    type?: "USER_CHAT" | "GROUP_CHAT" | "";
+    /**
+     * ID của người dùng hoặc nhóm chat tương ứng.
+     */
     id?: string;
 };
 type GetAuthCodeReturns = {
@@ -1034,12 +1199,25 @@ type GetZPITokenReturns = {
     zpp: string;
     zpt: string;
 };
+type TempFile = {
+    /**
+     * Đường dẫn các temp file đã chọn.
+     */
+    path: string;
+    /**
+     * Kích thước các temp file đã chọn.
+     */
+    size: number;
+};
 type ChooseImageReturns = {
-    filePaths: Array<string>;
-    tempFiles: Array<{
-        path: string;
-        size: number;
-    }>;
+    /**
+     * Đường dẫn các file đã chọn.
+     */
+    filePaths: string[];
+    /**
+     * Thông tin các temp files.
+     */
+    tempFiles: TempFile[];
 };
 type CreateOrderReturns = {
     orderId: string;
@@ -1073,6 +1251,19 @@ type AuthorizeType<T extends ScopeValues> = Partial<{
     [key in T]: boolean;
 }>;
 type GetSettingReturn = {
+    /**
+     * Thông tin cấp quyền, tham khảo bảng Scopes.
+     *
+     * | Scope                 | Corresponding APIs    | Description                     |
+     * | --------------------- | --------------------- | ------------------------------- |
+     * | scope.userInfo        | `getUserInfo`         | Thông tin user (tên, avatar...) |
+     * | scope.userLocation    | `getLocation`         | Thông tin vị trí user           |
+     * | scope.userPhonenumber | `getPhoneNumber`      | Số điện thoại                   |
+     * | scope.camera          | `createCameraContext` | Camera                          |
+     * | scope.micro           | `createCameraContext` | Micro                           |
+     *
+     * Với các scope có giá trị trả về là `true`, tương ứng với việc người dùng đã cấp quyền sử dụng API trước đó, Mini Apps có thể truy xuất thông tin một cách trực tiếp.
+     */
     authSetting: AuthorizeType<(typeof GET_SETTINGS_SCOPE_VALUES)[number]>;
 };
 
@@ -1131,10 +1322,31 @@ type PhotoConstraint = {
 
 declare function login(args?: AsyncCallback<string>): Promise<string>;
 
+/**
+ * API dùng để lấy thông tin xác thực người dùng.
+ *
+ * @important Cập nhật
+ * Từ phiên bản SDK 2.35.0, ứng dụng mặc định có quyền truy xuất access tokens mà không cần người dùng xác nhận đồng ý. Thông qua access tokens này, ứng dụng chỉ có thể xuất ID người sử dụng. Nếu ứng dụng có nhu cầu sử dụng Tên và Ảnh đại diện, vui lòng sử dụng API authorize để yêu cầu người dùng cho phép truy cập scope.userInfo trước khi sử dụng API này. Lưu ý: Với các Zalo App có nhiều hơn 1 Mini App, hệ thống vẫn yêu cầu người dùng xác nhận khi truy xuất access tokens cho từng Mini App.
+ *
+ * @returns {string} `accessToken`.
+ * @example
+ * ```ts
+ * const accessToken = await getAccessToken();
+ * ```
+ */
 declare function getAccessToken(args?: AsyncCallback<string>): Promise<string>;
 
 declare function getVersion(): string;
 
+/**
+ * API truy xuất thông tin hệ thống, thiết bị đang sử dụng.
+ * @minimumVersion 2.4.0
+ * @returns {SystemInfo} các thông tin về phiên bản, ngôn ngữ, theme của hệ thống.
+ * @example Lấy các thông tin phiên bản:
+ * ```ts
+ * const { version, apiVersion, zaloVersion } = getSystemInfo();
+ * ```
+ */
 declare function getSystemInfo(): SystemInfo;
 
 declare type Primitive = string | number | symbol | bigint | boolean | null | undefined;
@@ -2086,6 +2298,20 @@ declare const setNavigationBarTitleArgs: ZodOptional<ZodObject<{
 }, {
     title: string;
 }>>[];
+/**
+ * API đặt lại tiêu đề trên thanh điều hướng của trang hiện tại.
+ *
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} title Tiêu đề mới cần đặt cho trang.
+ * @example Khi người dùng truy cập trang Giỏ hàng:
+ * ```ts
+ * function CartPage() {
+ *   useEffect(() => {
+ *     setNavigationBarTitle({ title: "Giỏ hàng" });
+ *   }, []);
+ * ```
+ */
 declare function setNavigationBarTitle(args: AsyncVoidCallback & TypeOf<(typeof setNavigationBarTitleArgs)[0]>): Promise<void>;
 
 declare const setNavigationBarColorArgs: ZodOptional<ZodObject<{
@@ -2101,6 +2327,21 @@ declare const setNavigationBarColorArgs: ZodOptional<ZodObject<{
     statusBarColor?: string | undefined;
     color: string;
 }>>[];
+/**
+ * API đặt lại màu thanh điều hướng của trang hiện tại.
+ *
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} color Giá trị màu, có giá trị hợp lệ là màu thập lục phân, ví dụ `#000000`. Nếu giá trị này rỗng thì thanh điều hướng sẽ bị ẩn.
+ * @param {"black" | "white"} [textColor] Màu của text và icon trên thanh action bar và status bar. Trên thiết bị iOS, chỉ có thể thay đổi màu icon ở thanh action bar.
+ * @param {string} [statusBarColor] Màu của thanh status bar khi thanh điều hướng bị ẩn, có giá trị hợp lệ là màu thập lục phân, ví dụ `#000000`.
+ * @example Đổi màu thanh điều hướng thành màu đen:
+ * ```ts
+ * setNavigationBarColor({
+ *   color: "#000000",
+ * });
+ * ```
+ */
 declare function setNavigationBarColor(args: AsyncVoidCallback & TypeOf<(typeof setNavigationBarColorArgs)[0]>): Promise<void>;
 
 declare const setNavigationBarLeftButtonArgs: ZodOptional<ZodObject<{
@@ -2110,6 +2351,41 @@ declare const setNavigationBarLeftButtonArgs: ZodOptional<ZodObject<{
 }, {
     type: "none" | "home" | "both" | "back";
 }>>[];
+/**
+ * API đặt lại nút bên trái trên thanh điều hướng của trang hiện tại.
+ *
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {"none" | "back" | "home" | "both"} [type="back"] Loại nút bên trái.
+ *
+ * @example Hiển thị mũi tên quay lại:
+ * ```ts
+ * await setNavigationBarLeftButton({
+ *   type: "back"
+ * });
+ * ```
+ *
+ * @example Hiển thị nút trở về trang chủ:
+ * ```ts
+ * await setNavigationBarLeftButton({
+ *   type: "home"
+ * });
+ * ```
+ *
+ * @example Hiển thị cả nút quay lại và nút trở về trang chủ:
+ * ```ts
+ * await setNavigationBarLeftButton({
+ *   type: "both"
+ * });
+ * ```
+ *
+ * @example Không hiển thị nút bên trái:
+ * ```ts
+ * await setNavigationBarLeftButton({
+ *   type: "none"
+ * });
+ * ```
+ */
 declare function setNavigationBarLeftButton(args: AsyncVoidCallback & TypeOf<(typeof setNavigationBarLeftButtonArgs)[0]>): Promise<void>;
 
 declare const setStorageArgs: ZodOptional<ZodObject<{
@@ -2175,8 +2451,46 @@ declare const getUserInfoArgs: ZodOptional<ZodObject<{
     avatarType?: "small" | "normal" | "large" | undefined;
     autoRequestPermission?: boolean | undefined;
 }>>[];
+/**
+ * API truy xuất thông tin của người dùng bao gồm:
+ * - ID: chuỗi định danh người dùng theo Zalo App, được cấp mặc định.
+ * - Tên và Ảnh đại diện: nhằm tuân thủ Nghị Định số 13/2023/NĐ-CP về chính sách bảo vệ dữ liệu cá nhân, thông tin này sẽ yêu cầu người dùng xác nhận cho phép trước khi truy xuất. Nếu ứng dụng cần sử dụng thông tin này, vui lòng truyền param `autoRequestPermission` với giá trị `true`, hoặc sử dụng API [authorize](https://mini.zalo.me/documents/api/authorize/) để yêu cầu người dùng cho phép truy cập trước khi sử dụng API này.
+
+ * @param {"small" | "normal" | "large"} [avatarType] Kích thước ảnh avatar trả về. Mặc định là ảnh nhỏ nhất.
+ * @param {boolean} [autoRequestPermission=false] Nếu `true`, ứng dụng sẽ tự động hiển thị form yêu cầu người dùng cho phép truy cập thông tin.
+ * @returns {GetUserInfoReturns} Thông tin người dùng bao gồm ID, Tên, và Ảnh đại diện.
+ * @example Tự động yêu cầu quyền truy cập thông tin người dùng:
+ * ```ts
+ * const { userInfo } = await getUserInfo({
+ *   autoRequestPermission: true,
+ * });
+ * ```
+ *
+ * @example Xử lý sự kiện người dùng từ chối truy cập thông tin:
+ * ```ts
+ * try {
+ *   const { userInfo } = await getUserInfo();
+ * } catch (error) {
+ *   if (error instanceof AppError) {
+ *     if (error.code === -1401) {
+ *       // Người dùng từ chối cung cấp tên và ảnh đại diện
+ *     }
+ *   }
+ * }
+ * ```
+ */
 declare function getUserInfo(args?: AsyncCallback<GetUserInfoReturns> & TypeOf<(typeof getUserInfoArgs)[0]>): Promise<GetUserInfoReturns>;
 
+/**
+ * API truy xuất kiểu kết nối mạng hiện tại.
+ *
+ * @returns {GetNetworkTypeReturns} kiểu kết nối mạng hiện tại.
+ *
+ * @example Lấy kiểu kết nối mạng hiện tại:
+ * ```ts
+ * const { networkType } = await getNetworkType();
+ * ```
+ */
 declare function getNetworkType(args?: AsyncCallback<GetNetworkTypeReturns>): Promise<GetNetworkTypeReturns>;
 
 declare const onNetworkStatusChangeArgs: ZodFunction<ZodTuple<[ZodObject<{
@@ -2184,11 +2498,31 @@ declare const onNetworkStatusChangeArgs: ZodFunction<ZodTuple<[ZodObject<{
     networkType: ZodEnum<["none", "wifi", "cellular", "unknown"]>;
 }, "strip", ZodTypeAny, {
     isConnected: boolean;
-    networkType: "none" | "unknown" | "wifi" | "cellular";
+    networkType: "unknown" | "none" | "wifi" | "cellular";
 }, {
     isConnected: boolean;
-    networkType: "none" | "unknown" | "wifi" | "cellular";
+    networkType: "unknown" | "none" | "wifi" | "cellular";
 }>], ZodUnknown>, ZodVoid>[];
+/**
+ * Callback để lắng nghe sự kiện thay đổi mạng.
+ *
+ * @param {function} callback - Callback function được gọi khi mạng thay đổi.
+ * @param {Object} callback.data - Dữ liệu trả về khi mạng thay đổi.
+ * @param {boolean} callback.data.isConnected - Trạng thái kết nối mạng.
+ * @param {string} callback.data.networkType - Kiểu kết nối mạng hiện tại với các giá trị:
+ * - `none`: Không có mạng.
+ * - `wifi`: Mạng Wi-Fi.
+ * - `cellular`: Mạng di động (2g/3g/4g).
+ * - `unknown`: Mạng không xác định (Android).
+ *
+ * @example Lắng nghe sự kiện thay đổi mạng:
+ * ```ts
+ * onNetworkStatusChange(function (data) {
+ *   const { isConnected, networkType } = data;
+ *   console.log(`Kết nối mạng: ${isConnected}, Loại mạng: ${networkType}`);
+ * });
+ * ```
+ */
 declare function onNetworkStatusChange(args: TypeOf<(typeof onNetworkStatusChangeArgs)[0]>): void;
 
 declare const startBeaconDiscoveryArgs: ZodOptional<ZodObject<{
@@ -2293,6 +2627,15 @@ declare function stopBeaconDiscovery(args: AsyncCallback<boolean>): Promise<bool
 
 declare function getBeacons(args?: AsyncCallback<GetBeaconDiscoveryReturns>): Promise<GetBeaconDiscoveryReturns>;
 
+/**
+ * API yêu cầu đóng Zalo Mini App.
+ *
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ * @example Đóng Zalo Mini App:
+ * ```ts
+ * closeApp();
+ * ```
+ */
 declare function closeApp(args?: AsyncVoidCallback): Promise<void>;
 
 declare function scanQRCode(args?: AsyncCallback<ScanQRCodeReturns>): Promise<ScanQRCodeReturns>;
@@ -2313,6 +2656,34 @@ declare const openProfileArgs: ZodOptional<ZodObject<{
     type: "user" | "oa" | "aliasOA";
     id: string;
 }>>[];
+/**
+ * API cho phép ứng dụng mở profile của User hoặc Official Account.
+ *
+ * @minimumVersion 2.5.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {"user" | "oa" | "aliasOA"} type Nhận các giá trị sau:
+ * - `user`: Mở profile User.
+ * - `oa`: Mở profile OA.
+ * - `aliasOA`: Mở profile OA bằng Alias (field id truyền lên là alias của OA).
+ * @param {string} id Id của User hoặc OA.
+ *
+ * @example Mở cửa sổ chat với người dùng:
+ * ```ts
+ * await openProfile({
+ *   type: "user",
+ *   id: "user-id",
+ * });
+ * ```
+ *
+ * @example Mở profile của Official Account:
+ * ```tsx
+ * await openProfile({
+ *   type: "oa",
+ *   id: "oa-id",
+ * });
+ * ```
+ */
 declare function openProfile(args: AsyncVoidCallback & TypeOf<(typeof openProfileArgs)[0]>): Promise<void>;
 
 declare const openChatArgs: ZodOptional<ZodObject<{
@@ -2334,6 +2705,42 @@ declare const openChatArgs: ZodOptional<ZodObject<{
     type: "user" | "oa";
     id: string;
 }>>[];
+/**
+ * API cho phép ứng dụng mở cửa sổ chat với User hoặc Official Account. Có thể tự động điền nội dung tin nhắn, tuy nhiên việc gửi tin nhắn hay không phụ thuộc vào quyết định của người dùng.
+ *
+ * @minimumVersion 2.5.3
+ * @minimumVersion 2.20.0: hỗ trợ tự điền nội dung tin nhắn với `message`.
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {"user" | "oa"} type Đối tượng mở cửa sổ chat.
+ * @param {string} id Id của User hoặc Official Account tương ứng.
+ * @param {string} [message] Nội dung sẽ được tự động điền vào ô tin nhắn. Người dùng có thể thay đổi nội dung này trước khi gửi.
+ *
+ * @example Mở cửa sổ chat với người dùng:
+ * ```ts
+ * await openChat({
+ *   type: "user",
+ *   id: "xxx",
+ * });
+ * ```
+ *
+ * @example Mở cửa sổ chat với Official Account:
+ * ```ts
+ * await openChat({
+ *   type: "oa",
+ *   id: "xxx",
+ * });
+ * ```
+ *
+ * @example Tự động điền nội dung tin nhắn:
+ * ```ts
+ * await openChat({
+ *   type: "oa",
+ *   id: "xxx",
+ *   message: `Xin chào, tôi muốn mua sản phẩm này: ${productName}`,
+ * });
+ * ```
+ */
 declare function openChat(args: AsyncVoidCallback & TypeOf<(typeof openChatArgs)[0]>): Promise<void>;
 
 declare const openPostFeedArgs: ZodUnion<[ZodObject<{
@@ -2414,6 +2821,53 @@ declare const openPostFeedArgs: ZodUnion<[ZodObject<{
     };
     type: "profile";
 }>]>[];
+/**
+ * API cho phép ứng dụng mở giao diện chia sẻ để người dùng chia sẻ thông tin lên nhật ký Zalo.
+ *
+ * @minimumVersion 2.5.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {"image" | "link" | "profile"} type Nhận các giá trị sau:
+ * - `image`: Chia sẻ hình ảnh.
+ * - `link`: Chia sẻ liên kết.
+ * - `profile`: Chia sẻ profile OA.
+ * @param {Object} data Nội dung cần chia sẻ, tùy thuộc vào `type`.
+ *
+ * @returns {OpenPostFeedReturns} thông tin kết quả chia sẻ.
+ *
+ * @example Chia sẻ hình ảnh:
+ * ```ts
+ * const { status, shareType, numberOfUser } = await openPostFeed({
+ *   type: "image",
+ *   data: {
+ *     imageUrls: ["link-to-image"],
+ *   },
+ * });
+ * ```
+ *
+ * @example Chia sẻ liên kết:
+ * ```ts
+ * const { status, shareType, numberOfUser } = await openPostFeed({
+ *   type: "link",
+ *   data: {
+ *     link: "http://news.zing.vn/Trung-uong-quyet-dinh-phuong-an-nhan-su-cap-cao-post632739.html",
+ *     title: "Trung ương quyết định phương án nhân sự cấp cao",
+ *     thumb: "link-to-thumb",
+ *     description: "description",
+ *   },
+ * });
+ * ```
+ *
+ * @example Chia sẻ profile:
+ * ```ts
+ * const { status, shareType, numberOfUser } = await openPostFeed({
+ *   type: "profile",
+ *   data: {
+ *     id: "765465772305886642",
+ *   },
+ * });
+ * ```
+ */
 declare function openPostFeed(args: AsyncCallback<OpenPostFeedReturns> & TypeOf<(typeof openPostFeedArgs)[0]>): Promise<OpenPostFeedReturns>;
 
 declare const followOAArgs: ZodOptional<ZodObject<{
@@ -2426,6 +2880,38 @@ declare const followOAArgs: ZodOptional<ZodObject<{
     showDialogConfirm?: boolean | undefined;
     id: string;
 }>>[];
+/**
+ * API yêu cầu theo dõi Official Account. Khi gọi API, một thông báo sẽ được hiển thị.
+ *
+ * @minimumVersion 2.5.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} id Id của Official Account cần theo dõi.
+ *
+ * @example Theo dõi Official Account:
+ * ```ts
+ * await followOA({
+ *   id: "xxxx",
+ * });
+ * ```
+ *
+ * @example Xử lý lỗi:
+ * ```ts
+ * try {
+ *   await followOA({
+ *     id: "xxxx",
+ *   });
+ *   console.log("Theo dõi thành công");
+ * } catch (error) {
+ *   const code = (error as AppError).code;
+ *   if (code === -201) {
+ *     console.log("Người dùng đã từ chối theo dõi");
+ *   } else {
+ *     console.log("Lỗi khác");
+ *   }
+ * }
+ * ```
+ */
 declare function followOA(args: AsyncVoidCallback & TypeOf<(typeof followOAArgs)[0]>): Promise<void>;
 
 declare const unfollowOAArgs: ZodOptional<ZodObject<{
@@ -2435,6 +2921,21 @@ declare const unfollowOAArgs: ZodOptional<ZodObject<{
 }, {
     id: string;
 }>>[];
+/**
+ * API cho phép ứng dụng hiển thị giao diện yêu cầu bỏ theo dõi Official Account để người dùng xác nhận.
+ *
+ * @minimumVersion 2.5.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} id Id của Official Account.
+ *
+ * @example Hiển thị giao diện yêu cầu bỏ theo dõi Official Account:
+ * ```ts
+ * await unfollowOA({
+ *   id: "xxxx",
+ * });
+ * ```
+ */
 declare function unfollowOA(args: AsyncVoidCallback & TypeOf<(typeof unfollowOAArgs)[0]>): Promise<void>;
 
 declare const openShareSheetArgs: ZodUnion<[ZodObject<{
@@ -2636,24 +3137,168 @@ declare const openShareSheetArgs: ZodUnion<[ZodObject<{
     };
     type: "zmp" | "zmp_deep_link";
 }>]>[];
-declare function openShareSheet(args: AsyncCallback<OpenShareSheetReturns> & TypeOf<(typeof openShareSheetArgs)[0]>): Promise<OpenShareSheetReturns>;
-
-declare function requestCameraPermission(args?: AsyncCallback<RequestCameraPermissionReturns>): Promise<RequestCameraPermissionReturns>;
-
-declare const createShortcutArgs: ZodOptional<ZodObject<{
-    params: ZodOptional<ZodRecord<ZodString, ZodString>>;
-}, "strip", ZodTypeAny, {
-    params?: Record<string, string> | undefined;
-}, {
-    params?: Record<string, string> | undefined;
-}>>[];
-declare function createShortcut(args?: AsyncCallback<any> & TypeOf<(typeof createShortcutArgs)[0]>): Promise<any>;
-
-declare const openBioAuthenticationArgs: ZodOptional<ZodObject<{
-    secretData: ZodString;
-    ui: ZodOptional<ZodObject<{
-        title: ZodOptional<ZodDefault<ZodString>>;
-        subTitle: ZodOptional<ZodDefault<ZodString>>;
+/**
+ * API cho phép ứng dụng mở giao diện chia sẻ để người dùng chia sẻ thông tin với bạn bè Zalo.
+ *
+ * @minimumVersion 2.5.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {"text" | "image" | "link" | "oa" | "gif" | "video" | "zmp" | "zmp_deep_link"} type Nhận các giá trị sau:
+ * - `text`: Chia sẻ văn bản.
+ * - `image`: Chia sẻ hình ảnh.
+ * - `link`: Chia sẻ liên kết.
+ * - `oa`: Chia sẻ Official Account.
+ * - `gif`: Chia sẻ ảnh động.
+ * - `video`: Chia sẻ video.
+ * - `zmp`: Chia sẻ page hiện tại của Zalo Mini App.
+ * - `zmp_deep_link`: Chia sẻ page hiện tại của Zalo Mini App thông qua deep link (hỗ trợ từ API 2.25.7).
+ * @param {object} data Nội dung cần chia sẻ, tùy thuộc vào `type`.
+ *
+ * @returns {OpenShareSheetReturns} thông tin kết quả chia sẻ.
+ *
+ * @example Chia sẻ văn bản:
+ * ```ts
+ * const data = await openShareSheet({
+ *   type: "text",
+ *   data: {
+ *     text: "My Zalo Mini App - HomePage",
+ *   },
+ * });
+ * console.log(data);
+ * ```
+ *
+ * @example Chia sẻ hình ảnh:
+ * ```ts
+ * const data = await openShareSheet({
+ *   type: "image",
+ *   data: {
+ *     imageUrls: ["http://dev.org.zads.zdn.vn/2a16c7fefbbb12e54baa"],
+ *   },
+ * });
+ * console.log(data);
+ * ```
+ *
+ * @example Chia sẻ liên kết:
+ * ```ts
+ * const data = await openShareSheet({
+ *   type: "link",
+ *   data: {
+ *     link: "http://news.zing.vn/Trung-uong-quyet-dinh-phuong-an-nhan-su-cap-cao-post632739.html",
+ *     chatOnly: false,
+ *   },
+ * });
+ * console.log(data);
+ * ```
+ *
+ * @example Chia sẻ Official Account:
+ * ```ts
+ * const data = await openShareSheet({
+ *   type: "oa",
+ *   data: {
+ *     id: "765465772305886642",
+ *   },
+ * });
+ * console.log(data);
+ * ```
+ *
+ * @example Chia sẻ GIF:
+ * ```ts
+ * const data = await openShareSheet({
+ *   type: "gif",
+ *   data: {
+ *     imageUrl: "http://dev.org.zads.zdn.vn/2a16c7fefbbb12e54baa",
+ *     gifUrl: "http://dev.org.zads.zdn.vn/fc88fe60c2252b7b7234",
+ *     width: 480,
+ *     height: 270,
+ *   },
+ * });
+ * console.log(data);
+ * ```
+ *
+ * @example Chia sẻ video:
+ * ```ts
+ * const data = await openShareSheet({
+ *   type: "video",
+ *   data: {
+ *     videoThumb: "http://dev.org.zads.zdn.vn/fc88fe60c2252b7b7234",
+ *     videoUrl: "http://dev.org.zads.zdn.vn/fc88fe60c2252b7b7234",
+ *     width: 480,
+ *     height: 270,
+ *   },
+ * });
+ * console.log(data);
+ * ```
+ *
+ * @example Chia sẻ page hiện tại của Zalo Mini App:
+ * ```ts
+ * const data = await openShareSheet({
+ *   type: "zmp",
+ *   data: {
+ *     title: "My Zalo Mini App - HomePage",
+ *     description: "Home page",
+ *     thumbnail: "https://sample-videos.com/img/Sample-jpg-image-50kb.jpg",
+ *   },
+ * });
+ * console.log(data);
+ * ```
+ *
+ * @example Chia sẻ page hiện tại của Zalo Mini App thông qua deep link:
+ * ```ts
+ * const data = await openShareSheet({
+ *   type: "zmp_deep_link",
+ *   data: {
+ *     title: "My Zalo Mini App - HomePage",
+ *     description: "Home page",
+ *     thumbnail: "https://sample-videos.com/img/Sample-jpg-image-50kb.jpg",
+ *   },
+ * });
+ * console.log(data);
+ * ```
+ */
+declare function openShareSheet(args: AsyncCallback<OpenShareSheetReturns> & TypeOf<(typeof openShareSheetArgs)[0]>): Promise<OpenShareSheetReturns>;
+
+declare function requestCameraPermission(args?: AsyncCallback<RequestCameraPermissionReturns>): Promise<RequestCameraPermissionReturns>;
+
+declare const createShortcutArgs: ZodOptional<ZodObject<{
+    params: ZodOptional<ZodRecord<ZodString, ZodString>>;
+}, "strip", ZodTypeAny, {
+    params?: Record<string, string> | undefined;
+}, {
+    params?: Record<string, string> | undefined;
+}>>[];
+/**
+ * API cho phép ứng dụng tạo shortcut trên màn hình chờ.
+ *
+ * Chi tiết về giao diện tạo shortcut trên cả hai nền tảng vui lòng tham khảo tại [đây](https://mini.zalo.me/documents/api/createShortcut/).
+ *
+ * @minimumVersion 2.5.3: chỉ hỗ trợ tạo shortcut trên Android.
+ * @minimumVersion 2.16.1: hỗ trợ tạo shortcut trên cả iOS và Android.
+ * @minimumVersion 2.16.3: hỗ trợ thêm params vào shortcut.
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {Record<string, string>} [params] Params cần thêm vào Zalo Mini App khi mở..
+ *
+ * @example Tạo shortcut đơn giản:
+ * ```ts
+ * await createShortcut();
+ * ```
+ *
+ * @example Tạo shortcut với params:
+ * ```ts
+ * await createShortcut({
+ *   params: {
+ *     utm_source: "shortcut",
+ *   },
+ * });
+ * ```
+ */
+declare function createShortcut(args?: AsyncCallback<any> & TypeOf<(typeof createShortcutArgs)[0]>): Promise<any>;
+
+declare const openBioAuthenticationArgs: ZodOptional<ZodObject<{
+    secretData: ZodString;
+    ui: ZodOptional<ZodObject<{
+        title: ZodOptional<ZodDefault<ZodString>>;
+        subTitle: ZodOptional<ZodDefault<ZodString>>;
         negativeButtonText: ZodOptional<ZodDefault<ZodString>>;
     }, "strip", ZodTypeAny, {
         title?: string | undefined;
@@ -2693,8 +3338,33 @@ declare const showToastArgs: ZodOptional<ZodObject<{
 }, {
     message: string;
 }>>[];
+/**
+ * API hiển thị một thông báo ngắn trên màn hình.
+ *
+ * @minimumVersion 2.5.3
+ *
+ * @param {string} message Nội dung thông báo cần hiển thị.
+ *
+ * @example Hiện thông báo đặt hàng thành công:
+ * ```ts
+ * showToast({
+ *   message: "Đặt hàng thành công!"
+ * });
+ * ```
+ */
 declare function showToast(args: AsyncVoidCallback & TypeOf<(typeof showToastArgs)[0]>): Promise<void>;
 
+/**
+ * API để ẩn bàn phím ảo.
+ *
+ * @minimumVersion 2.5.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @example Chủ động ẩn bàn phím ảo:
+ * ```ts
+ * hideKeyboard();
+ * ```
+ */
 declare function hideKeyboard(args?: AsyncVoidCallback): Promise<void>;
 
 declare const openPhoneArgs: ZodObject<{
@@ -2704,6 +3374,28 @@ declare const openPhoneArgs: ZodObject<{
 }, {
     phoneNumber: string;
 }>[];
+/**
+ * API cho phép mở màn hình cuộc gọi với một số điện thoại cụ thể.
+ *
+ * @minimumVersion 2.5.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} phoneNumber Số điện thoại cần gọi.
+ *
+ * @example Mở màn hình cuộc gọi với số điện thoại cụ thể:
+ * ```ts
+ * await openPhone({
+ *   phoneNumber: "0123456789",
+ * });
+ * ```
+ *
+ * @example Số điện thoại có thể bắt đầu bằng mã quốc tế:
+ * ```ts
+ * await openPhone({
+ *   phoneNumber: "+84123456789",
+ * });
+ * ```
+ */
 declare function openPhone(args: AsyncVoidCallback & TypeOf<(typeof openPhoneArgs)[0]>): Promise<void>;
 
 declare const openSMSArgs: ZodObject<{
@@ -2716,6 +3408,23 @@ declare const openSMSArgs: ZodObject<{
     content: string;
     phoneNumber: string;
 }>[];
+/**
+ * API mở ứng dụng tin nhắn với nội dung và số điện thoại cụ thể.
+ *
+ * @minimumVersion 2.5.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} content Nội dung tin nhắn.
+ * @param {string} phoneNumber Số điện thoại nhận tin nhắn.
+ *
+ * @example Mở ứng dụng tin nhắn với nội dung và số điện thoại cụ thể:
+ * ```ts
+ * await openSMS({
+ *   content: "text",
+ *   phoneNumber: "+84123456789",
+ * });
+ * ```
+ */
 declare function openSMS(args: AsyncVoidCallback & TypeOf<(typeof openSMSArgs)[0]>): Promise<void>;
 
 declare const viewOAQrArgs: ZodObject<{
@@ -2728,6 +3437,23 @@ declare const viewOAQrArgs: ZodObject<{
     displayName?: string | undefined;
     id: string;
 }>[];
+/**
+ * API cho phép ứng dụng hiển thị QR code của OA.
+ *
+ * @minimumVersion 2.5.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} id Id của OA.
+ * @param {string} [displayName] Tên hiển thị của QR code.
+ *
+ * @example Hiển thị QR code của OA:
+ * ```ts
+ * await viewOAQr({
+ *   id: "765465772305886642",
+ *   displayName: "Galaxy Cinema",
+ * });
+ * ```
+ */
 declare function viewOAQr(args: AsyncVoidCallback & TypeOf<(typeof viewOAQrArgs)[0]>): Promise<void>;
 
 declare const keepScreenArgs: ZodObject<{
@@ -2737,6 +3463,29 @@ declare const keepScreenArgs: ZodObject<{
 }, {
     keepScreenOn: boolean;
 }>[];
+/**
+ * API cho phép ứng dụng giữ cho màn hình luôn bật. Ví dụ: trường hợp play video. Khi thoát khỏi ứng dụng, cài đặt này sẽ quay về mặc định để tránh màn hình luôn bật.
+ *
+ * @minimumVersion 2.5.3
+ * @requirePermission Cần xin Cấp quyền sử dụng các API này cho Mini App ID tại trang Quản lý ứng dụng. Nếu không, sẽ bị [lỗi với người dùng bình thường, mặc dù Developer/Admin thì không bị](https://mini.zalo.me/community/8746968970844796879/loi-chi-xay-ra-voi-nguoi-dung-binh-thuong-con-developer-admin-thi-khong-bi).
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {boolean} keepScreenOn Truyền `true` để giữ màn hình luôn bật. Truyền `false` để tắt chế độ này.
+ *
+ * @example Giữ màn hình luôn bật:
+ * ```ts
+ * await keepScreen({
+ *   keepScreenOn: true,
+ * });
+ * ```
+ *
+ * @example Tắt chế độ giữ màn hình:
+ * ```ts
+ * await keepScreen({
+ *   keepScreenOn: false,
+ * });
+ * ```
+ */
 declare function keepScreen(args: AsyncCallback<KeepScreenReturns> & TypeOf<(typeof keepScreenArgs)[0]>): Promise<void>;
 
 declare function onKeepScreen(args?: AsyncVoidCallback): Promise<void>;
@@ -2753,6 +3502,46 @@ declare const saveImageToGalleryArgs: ZodOptional<ZodObject<{
     imageUrl?: string | undefined;
     imageBase64Data?: string | undefined;
 }>>[];
+/**
+ * Lưu ảnh vào thư viện media của thiết bị.
+ *
+ * @minimumVersion 2.16.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} [imageBase64Data] Giá trị base64 của ảnh cần lưu.
+ * @param {string} [imageUrl] Đường dẫn của ảnh cần lưu.
+ * @param {(progress: number) => void} [onProgress] Callback function tiến độ tải file. Với `progress` là số từ 0 đến 100%.
+ *
+ * @example Thông báo một lần sau khi lưu ảnh xong:
+ * ```ts
+ * await saveImageToGallery({
+ *   imageUrl: "https://sample-videos.com/img/Sample-jpg-image-50kb.jpg",
+ * });
+ * console.log("Lưu ảnh thành công!");
+ * ```
+ *
+ * @example Xử lý lỗi khi lưu ảnh:
+ * ```ts
+ * try {
+ *   await saveImageToGallery({
+ *     imageUrl: "https://sample-videos.com/img/Sample-jpg-image-50kb.jpg",
+ *   });
+ * } catch (error) {
+ *   console.error(error);
+ * }
+ * ```
+ *
+ * @example Báo cáo tiến độ lưu ảnh:
+ * ```ts
+ * await saveImageToGallery({
+ *   imageUrl: "https://sample-videos.com/img/Sample-jpg-image-50kb.jpg",
+ *   onProgress: (progress) => {
+ *     console.log(`Đã lưu được ${progress}%...`);
+ *   },
+ * });
+ * console.log("Lưu ảnh thành công!");
+ * ```
+ */
 declare function saveImageToGallery(args: AsyncProgressCallback & TypeOf<(typeof saveImageToGalleryArgs)[0]>): Promise<void>;
 
 declare const saveVideoToGalleryArgs: ZodOptional<ZodObject<{
@@ -2762,6 +3551,46 @@ declare const saveVideoToGalleryArgs: ZodOptional<ZodObject<{
 }, {
     videoUrl: string;
 }>>[];
+/**
+ * Lưu video vào thư viện media của thiết bị.
+ *
+ * @minimumVersion 2.44.0
+ * @requirePermission Cần xin Cấp quyền sử dụng các API này cho Mini App ID tại trang Quản lý ứng dụng. Nếu không, sẽ bị [lỗi với người dùng bình thường, mặc dù Developer/Admin thì không bị](https://mini.zalo.me/community/8746968970844796879/loi-chi-xay-ra-voi-nguoi-dung-binh-thuong-con-developer-admin-thi-khong-bi).
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} videoUrl Đường dẫn của video cần lưu.
+ * @param {(progress: number) => void} [onProgress] Callback function tiến độ tải file. Với `progress` là số từ 0 đến 100%.
+ *
+ * @example Thông báo một lần sau khi lưu video xong:
+ * ```ts
+ * await saveVideoToGallery({
+ *   videoUrl: "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4",
+ * });
+ * console.log("Lưu video thành công!");
+ * ```
+ *
+ * @example Xử lý lỗi khi lưu video:
+ * ```ts
+ * try {
+ *   await saveVideoToGallery({
+ *     videoUrl: "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4",
+ *   });
+ * } catch (error) {
+ *   console.error(error);
+ * }
+ * ```
+ *
+ * @example Báo cáo tiến độ lưu video:
+ * ```ts
+ * await saveVideoToGallery({
+ *   videoUrl: "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4",
+ *   onProgress: (progress) => {
+ *     console.log(`Đã lưu được ${progress}%...`);
+ *   },
+ * });
+ * console.log("Lưu video thành công!");
+ * ```
+ */
 declare function saveVideoToGallery(args: AsyncProgressCallback & TypeOf<(typeof saveVideoToGalleryArgs)[0]>): Promise<void>;
 
 declare const openMiniAppArgs: ZodObject<{
@@ -2777,18 +3606,77 @@ declare const openMiniAppArgs: ZodObject<{
     params?: Record<string, string> | undefined;
     appId: string;
 }>[];
+/**
+ * API dùng để mở một Zalo Mini App khác. Có thể mở với một đường dẫn cụ thể bên trong Mini App đó, hoặc đính kèm các tham số bổ sung.
+ *
+ * @minimumVersion 2.7.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} appId ID của Zalo Mini App cần mở.
+ * @param {string} [path] Đường dẫn đến một trang cụ thể bên trong Zalo Mini App cần mở.
+ * @param {Record<string, string>} [params] Object chứa các tham số bổ sung cần đính kèm với đường dẫn.
+ *
+ *
+ * @example Mở Mini App "ZaUI Coffee":
+ * ```ts
+ * openMiniApp({
+ *   appId: "194839900003483517",
+ * });
+ * ```
+ *
+ * @example Mở tab "Cá nhân" bên trong "ZaUI Coffee":
+ * ```ts
+ * openMiniApp({
+ *   appId: "194839900003483517",
+ *   path: "/profile",
+ * });
+ * ```
+ *
+ * @example Mở "ZaUI Coffee" với `utm_campaign` tracking:
+ * ```ts
+ * openMiniApp({
+ *   appId: "194839900003483517",
+ *   params: {
+ *     utm_campaign: "spring_promo",
+ *   },
+ * });
+ * ```
+ */
 declare function openMiniApp(args: AsyncVoidCallback & TypeOf<(typeof openMiniAppArgs)[0]>): Promise<void>;
 
 declare const vibrateArgs: ZodObject<{
-    type: ZodDefault<ZodEnum<["oneShot"]>>;
+    type: ZodOptional<ZodDefault<ZodEnum<["oneShot"]>>>;
     milliseconds: ZodOptional<ZodNumber>;
 }, "strip", ZodTypeAny, {
+    type?: "oneShot" | undefined;
     milliseconds?: number | undefined;
-    type: "oneShot";
 }, {
     type?: "oneShot" | undefined;
     milliseconds?: number | undefined;
 }>[];
+/**
+ * API rung thiết bị.
+ *
+ * @minimumVersion 2.9.8
+ * @requirePermission Cần xin Cấp quyền sử dụng các API này cho Mini App ID tại trang Quản lý ứng dụng. Nếu không, sẽ bị [lỗi với người dùng bình thường, mặc dù Developer/Admin thì không bị](https://mini.zalo.me/community/8746968970844796879/loi-chi-xay-ra-voi-nguoi-dung-binh-thuong-con-developer-admin-thi-khong-bi).
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} [type="oneShot"] Loại rung, hiện tại chỉ hỗ trợ `oneShot`.
+ * @param {number} [milliseconds=500] Thời gian rung (tính bằng mili giây). Chỉ có thể thiết lập trên thiết bị Android.
+ *
+ * @example Rung thiết bị trong 500 mili giây:
+ * ```ts
+ * await vibrate();
+ * ```
+ *
+ * @example Rung thiết bị trong 1 giây:
+ * ```ts
+ * await vibrate({
+ *   type: "oneShot",
+ *   milliseconds: 1000
+ * })
+ * ```
+ */
 declare function vibrate(args?: AsyncVoidCallback & TypeOf<(typeof vibrateArgs)[0]>): Promise<void>;
 
 declare const openWebviewArgs: ZodObject<{
@@ -2816,10 +3704,60 @@ declare const openWebviewArgs: ZodObject<{
     } | undefined;
     url: string;
 }>[];
+/**
+ * Tải một trang web bằng Webview.
+ * Để biết khi nào Webview được đóng, vui lòng lắng nghe sự kiện [WebviewClosed](https://mini.zalo.me/documents/api/events/#webviewclosed).
+ *
+ * @minimumVersion 2.11.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} url Đường dẫn của trang web cần tải.
+ * @param {"bottomSheet" | "normal"} [config.style="bottomSheet"] Kiểu hiển thị của Webview:
+ * - `bottomSheet`: Cửa sổ hiển thị từ dưới đáy của màn hình.
+ * - `normal`: Cửa sổ hiển thị toàn màn hình.
+ * @param {"back" | "none"} [config.leftButton="back"] Nút bên trái thanh header: (chỉ hỗ trợ cho style 'bottomSheet')
+ * - `back`: Nút quay về trang trước.
+ * - `none`: không hiển thị nút.
+ *
+ * @example Mở trang chủ của Zalo Mini App:
+ * ```ts
+ * openWebview({
+ *   url: "https://mini.zalo.me",
+ * });
+ * ```
+ * @example Mở trang chủ của Zalo Mini App toàn màn hình:
+ * ```ts
+ * openWebview({
+ *   url: "https://mini.zalo.me",
+ *   config: {
+ *     style: "normal",
+ *   }
+ * });
+ * ```
+ */
 declare function openWebview(args: AsyncCallback<OpenWebviewReturns> & TypeOf<(typeof openWebviewArgs)[0]>): Promise<void>;
 
+/**
+ * API truy xuất các tham số được gửi đến trang hiện tại.
+ *
+ * @minimumVersion 2.11.0
+ * @returns {Record<string, string>} tất cả tham số dưới dạng key-value.
+ *
+ * @example Lấy ID của sản phẩm được truyền vào trong URL:
+ * ```ts
+ * const { id } = getRouteParams();
+ * ```
+ */
 declare function getRouteParams(): Record<string, string>;
 
+/**
+ * API truy xuất thông tin Zalo Mini App hiện tại.
+ * @returns {GetAppInfoReturns} các thông tin Zalo Mini App hiện tại.
+ * @example Lấy tên và phiên bản live hiện tại:
+ * ```ts
+ * const { name, version } = await getAppInfo({});
+ * ```
+ */
 declare function getAppInfo(args?: AsyncCallback<GetAppInfoReturns>): Promise<GetAppInfoReturns>;
 
 declare const sendDataToPreviousMiniAppArgs: ZodObject<{
@@ -2829,8 +3767,97 @@ declare const sendDataToPreviousMiniAppArgs: ZodObject<{
 }, {
     data?: any;
 }>[];
+/**
+ * Gửi dữ liệu cho Zalo Mini App trước đó.
+ * Zalo Mini App trước đó cần lắng nghe sự kiện [OnDataCallback](https://mini.zalo.me/documents/api/events/#ondatacallback) để nhận dữ liệu.
+ * Nếu API được gọi nhiều lần thì dữ liệu cuối cùng sẽ được gửi đi.
+ *
+ * @minimumVersion 2.13.0
+ *
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {any} data Dữ liệu cần gửi.
+ *
+ * @example Ví dụ có 2 Zalo Mini App A với id là `2953132499190403100` và B với id là `2953132499190403200`. Để B có thể gửi dữ liệu cho A, chúng ta cần thực hiện những bước sau:
+ *
+ * 1. Lắng nghe sự kiện [OnDataCallback](https://mini.zalo.me/documents/api/events/#ondatacallback) ở app A:
+ * ```ts
+ * import { events, EventName } from "zmp-sdk/apis";
+ *
+ * const callback = (data) => {
+ *   console.log(data);
+ * };
+ *
+ * events.on(EventName.OnDataCallback, callback);
+ * ```
+ *
+ * 2. Gọi API [openMiniApp](https://mini.zalo.me/documents/api/openMiniApp/) để chuyển đến app B:
+ * ```ts
+ * import { openMiniApp } from "zmp-sdk/apis";
+ *
+ * openMiniApp({
+ *   appId: "2953132499190403200",
+ *   success: (res) => {
+ *     // xử lý khi gọi API thành công
+ *   },
+ *   fail: (error) => {
+ *     // xử lý khi gọi API thất bại
+ *     console.log(error);
+ *   },
+ * });
+ * ```
+ *
+ * 3. Ở app B, gửi dữ liệu cho app A:
+ * ```ts
+ * import { sendDataToPreviousMiniApp } from "zmp-sdk/apis";
+ *
+ * sendDataToPreviousMiniApp({
+ *   data: "Success",
+ *   success: (res) => {
+ *     // xử lý khi gọi API thành công
+ *   },
+ *   fail: (err) => {
+ *     // xử lý khi gọi API thất bại
+ *     console.log(err);
+ *   },
+ * });
+ * ```
+ *
+ * 4. Tắt app B bằng API [closeApp](https://mini.zalo.me/documents/api/closeApp/) hoặc nhấn nút tắt Mini App trên header:
+ * ```ts
+ * import { closeApp } from "zmp-sdk/apis";
+ *
+ * closeApp();
+ * ```
+ *
+ * 5. Sau khi app B đóng hoàn toàn, app A sẽ nhận được dữ liệu đã gửi.
+ */
 declare function sendDataToPreviousMiniApp(args: AsyncVoidCallback & TypeOf<(typeof sendDataToPreviousMiniAppArgs)[0]>): Promise<void>;
 
+/**
+ * Lấy thông tin số điện thoại của người dùng. Khi gọi API, một thông báo xin cấp quyền sẽ được hiển thị. Mini App chỉ lấy được thông tin số điện thoại nếu người dùng đồng ý cấp quyền chia sẻ số điện thoại.
+ *
+ * Lưu ý, để giúp các nhà phát triển Mini App sử dụng flow xin quyền một cách hiệu quả, cũng như phù hợp với [chính sách của Zalo Mini App điều 3.3.4](https://mini.zalo.me/documents/zalo-mini-app-developer-program-agreement/#33-api-quy%E1%BB%81n-truy-c%E1%BA%ADp), Mini App Team đã đưa ra một số gợi ý thiết kế trải nghiệm như thông tin bên dưới. Nhà phát triển cần giải thích rõ ràng và trực quan mục đích xin quyền để người dùng dễ dàng hiểu và đồng ý cung cấp thông tin.
+ *
+ * - **Trường hợp chỉ cần số điện thoại cho một số tính năng nhất định**: Chỉ nên yêu cầu người dùng chia sẻ số điện thoại khi người dùng bắt đầu sử dụng các tính năng đó như khi tiến hành đặt hàng, đăng ký tham dự sự kiện...
+ * - **Trường hợp bắt buộc phải cung cấp số điện thoại để sử dụng ứng dụng**: Cần hiển thị UI Onboarding giải thích cụ thể lý do người dùng cần phải cung cấp số điện thoại.
+ *
+ * Nhằm đảm bảo trải nghiệm thoải mái của người dùng Mini App, chúng tôi sẽ từ chối xét duyệt cho những Mini App có luồng xin cấp quyền chưa rõ ràng, không nêu được mục đích xin quyền đến người dùng.
+ *
+ * @minimumVersion 2.13.0
+ * @requirePermission Cần xin Cấp quyền sử dụng các API này cho Mini App ID tại trang Quản lý ứng dụng. Nếu không, sẽ bị [lỗi với người dùng bình thường, mặc dù Developer/Admin thì không bị](https://mini.zalo.me/community/8746968970844796879/loi-chi-xay-ra-voi-nguoi-dung-binh-thuong-con-developer-admin-thi-khong-bi).
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @returns {GetPhoneNumberReturns} token để truy xuất thông tin số điện thoại.
+ *
+ * @example
+ * 1. Ở Zalo Mini App, gọi API này để lấy token số điện thoại:
+ * ```ts
+ * const { token } = await getPhoneNumber();
+ * ```
+ * 2. Dùng fetch hoặc axios để gửi token này lên server. Nếu không, bạn sẽ bị [lỗi khi gọi các API Server-Server từ Mini App](https://mini.zalo.me/community/9107262438710014159/loi-khi-goi-cac-api-server-server-tu-mini-app).
+ * 3. Server chuyển đổi token thành thông tin số điện thoại và trả về cho Mini App theo [hướng dẫn sau](https://mini.zalo.me/documents/api/getPhoneNumber/#hướng-dẫn-chuyển-đổi-token-thành-số-điện-thoại-người-dùng).
+ */
 declare function getPhoneNumber(args?: AsyncCallback<GetPhoneNumberReturns>): Promise<GetPhoneNumberReturns>;
 
 declare const openProfilePickerArgs: ZodObject<{
@@ -2840,6 +3867,24 @@ declare const openProfilePickerArgs: ZodObject<{
 }, {
     maxProfile?: number | undefined;
 }>[];
+/**
+ * API mở cửa sổ chọn bạn bè trong Zalo, API sẽ trả về danh sách những người được chọn.
+ *
+ * @minimumVersion 2.16.1
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {number} [maxProfile=1] Số lượng bạn bè tối đa được chọn. Giới hạn trong khoảng 1 đến 10.
+ *
+ * @returns {OpenProfilePickerReturns} danh sách những bạn bè được chọn.
+ *
+ * @example Chọn tối đa 2 bạn bè trong danh sách bạn bè của người dùng:
+ * ```ts
+ * const { users } = await openProfilePicker({
+ *   maxProfile: 2,
+ * });
+ * console.log(users);
+ * ```
+ */
 declare function openProfilePicker(args?: AsyncCallback<OpenProfilePickerReturns> & TypeOf<(typeof openProfilePickerArgs)[0]>): Promise<OpenProfilePickerReturns>;
 
 declare const connectWifiArgs: ZodObject<{
@@ -2894,6 +3939,72 @@ declare const openMediaPickerArgs: ZodObject<{
     type: "video" | "zcamera" | "zcamera_photo" | "zcamera_video" | "zcamera_scan" | "photo" | "file";
     serverUploadUrl: string;
 }>[];
+/**
+ * Mở cửa sổ chọn media (camera, ảnh, file, video) từ thiết bị.
+ *
+ * Media sau khi chọn sẽ được tải lên server của bạn dưới dạng dữ liệu `multipart/form-data`, `fieldname=file`.
+ *
+ * @minimumVersion 2.18.11
+ * @minimumVersion 2.23.2: hỗ trợ các type `zcamera`, `zcamera_photo`, `zcamera_video`, `zcamera_scan`.
+ * @requirePermission Cần xin Cấp quyền sử dụng các API này cho Mini App ID tại trang Quản lý ứng dụng. Nếu không, sẽ bị [lỗi với người dùng bình thường, mặc dù Developer/Admin thì không bị](https://mini.zalo.me/community/8746968970844796879/loi-chi-xay-ra-voi-nguoi-dung-binh-thuong-con-developer-admin-thi-khong-bi).
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} serverUploadUrl Đường dẫn upload media. Server phải hỗ trợ upload media qua POST và trả về kết quả dạng JSON. Xem ví dụ về server tại [đây](https://mini.zalo.me/documents/api/openMediaPicker/#server).
+ * @param {"photo" | "file" | "video" | "zcamera" | "zcamera_photo" | "zcamera_video" | "zcamera_scan"} type Loại media cần chọn. Các giá trị:
+ * - 'photo': Mở cửa sổ chọn ảnh.
+ * - 'file': Mở cửa sổ chọn file.
+ * - 'video': Mở cửa sổ chọn video.
+ * - 'zcamera': Mở camera Zalo.
+ * - 'zcamera_photo': Mở camera Zalo để chụp ảnh.
+ * - 'zcamera_video': Mở camera Zalo để quay phim.
+ * - 'zcamera_scan': Mở camera Zalo để chụp tài liệu.
+ * Các type `zcamera`, `zcamera_photo`, `zcamera_video`, `zcamera_scan` hỗ trợ từ phiên bản API 2.23.2.
+ * @param {number} [maxItemSize] Giới hạn kích thước (byte) tối đa của media được phép chọn.
+ * @param {number} [maxSelectItem=1] Giới hạn số lượng tối đa media được chọn.
+ * @param {boolean} [silentRequest=false] Hiển thị hoặc ẩn dialog xử lý các tác vụ ngầm:
+ * - `false`: Hiện dialog xử lý các tác vụ ngầm như render video, upload media, và có nút hủy tác vụ.
+ * - `true`: Không hiện dialog xử lý các tác vụ ngầm.
+ * @param {Object} [editView] Hiển thị view chỉnh sửa ảnh.
+ * @param {boolean} [editView.enable=true] Hiển thị view chỉnh sửa ảnh.
+ * @param {string} [editView.aspectRatio="1:1"] Cắt ảnh theo tỉ lệ đã chỉ định. Tỉ lệ truyền vào theo format `width:height` (phân số tối giản quy định tỉ lệ width/height).
+ *
+ * @returns {OpenMediaPickerReturns} kết quả trả về.
+ *
+ * @example Mở cửa sổ chọn ảnh nhận kết quả trả về dạng JSON:
+ * ```ts
+ * const { data } = await openMediaPicker({
+ *   serverUploadUrl: "https://<your-domain-api>/upload/media",
+ *   type: "photo",
+ * });
+ * const result = JSON.parse(data);
+ * console.log(result);
+ * ```
+ *
+ * @example Chọn nhiều ảnh:
+ * ```ts
+ * const { data } = await openMediaPicker({
+ *   serverUploadUrl: "https://<your-domain-api>/upload/media",
+ *   type: "photo",
+ *   maxSelectItem: 5,
+ * });
+ * ```
+ *
+ * @example Chọn video:
+ * ```ts
+ * const { data } = await openMediaPicker({
+ *   serverUploadUrl: "https://<your-domain-api>/upload/media",
+ *   type: "video",
+ * });
+ * ```
+ *
+ * @example Chọn ảnh từ camera Zalo:
+ * ```ts
+ * const { data } = await openMediaPicker({
+ *   serverUploadUrl: "https://<your-domain-api>/upload/media",
+ *   type: "zcamera_photo",
+ * });
+ * ```
+ */
 declare function openMediaPicker(args: AsyncCallback<OpenMediaPickerReturns> & TypeOf<(typeof openMediaPickerArgs)[0]>): Promise<OpenMediaPickerReturns>;
 
 declare const getShareableLinkArgs: ZodObject<{
@@ -2914,8 +4025,39 @@ declare const getShareableLinkArgs: ZodObject<{
 }>[];
 declare function getShareableLink(args: AsyncCallback<string> & TypeOf<(typeof getShareableLinkArgs)[0]>): Promise<string>;
 
+/**
+ * Khi người dùng mở Zalo Mini App, một màn hình loading sẽ được hiển thị trong lúc chờ Mini App được tải. Màn hình này gọi là Splash Loading.
+ * Mặc định Splash Loading sẽ tự động đóng khi Mini App được tải xong. Tuy nhiên, phía tích hợp có thể chọn thời điểm phù hợp để đóng loading bằng cách:
+ * - Thêm thiết lập `selfControlLoading: true` trong `app-config.json`. Xem [Cấu Hình Zalo Mini App](https://mini.zalo.me/documents/intro/getting-started/app-config/#app).
+ * - Gọi `closeLoading` ở thời điểm thích hợp để đóng Splash Loading.
+ *
+ * Lưu ý:
+ * - Nếu thiết lập `selfControlLoading: true` mà API này không được gọi, **Mini App sẽ stuck ở màn hình Splash Loading**.
+ * - Do code gọi API này chỉ được thực thi sau khi Mini App đã được tải xong, nên Splash Loading sẽ được đóng trễ hơn so với bình thường. Chỉ sử dụng cơ chế này khi cần thiết (để giảm layout shift hoặc không muốn người dùng thấy nội dung chưa hoàn chỉnh).
+
+ * @minimumVersion 2.17.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ * @example Đóng loading sau khi HomePage đã render xong:
+ * ```ts
+ * function HomePage() {
+ *   useEffect(() => {
+ *     closeLoading();
+ *   }, []);
+ * ```
+ */
 declare function closeLoading(args?: AsyncVoidCallback): Promise<void>;
 
+/**
+ * API chủ động điều hướng người dùng tới AppStore/CH Play để cập nhật phiên bản Zalo mới nhất.
+ *
+ * @minimumVersion 2.19.3
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @example
+ * ```ts
+ * await requestUpdateZalo();
+ * ```
+ */
 declare function requestUpdateZalo(args?: AsyncVoidCallback): Promise<void>;
 
 declare const onConfirmToExitArgs: ZodFunction<ZodTuple<[], ZodUnknown>, ZodUnknown>[];
@@ -2925,10 +4067,34 @@ declare function offConfirmToExit(): void;
 
 declare function getDeviceId(): string;
 
+/**
+ * API trả về chuỗi Device ID của thiết bị đã được hash. Các tài khoản người dùng khác nhau đăng nhập trên cùng 1 thiết bị và sử dụng cùng 1 Mini App (hoặc các Mini App có chung Zalo App ID) sẽ có giá trị Device ID giống nhau. Nếu không lấy được Device ID thì giá trị trả về là `unknown`.
+ * @minimumVersion 2.20.0
+ * @returns {string} chuỗi Device ID của thiết bị đã được hash.
+ * @example Sử dụng kết hợp với `await`:
+ * ```ts
+ * const deviceId = await getDeviceIdAsync();
+ * ```
+ */
 declare function getDeviceIdAsync(args?: AsyncCallback<string>): Promise<string>;
 
 declare function getContext(): ContextInfo | null;
 
+/**
+ * API trả về thông tin ngữ cảnh của người dùng hoặc nhóm khi Mini App được mở từ Menu mở rộng trong cửa sổ chat Zalo.
+ * Nếu ngữ cảnh không hợp lệ hoặc phiên bản Zalo không hỗ trợ, giá trị trả về sẽ rỗng.
+ *
+ * @minimumVersion Zalo Android: 22.06.02
+ * @minimumVersion ZMP SDK: 2.22.0
+ * @returns {ContextInfo} ngữ cảnh hiện tại.
+ * @example Kiểm tra ngữ cảnh hợp lệ và trả về thông tin ngữ cảnh:
+ * ```ts
+ * const contextInfo = await getContextAsync();
+ * if (contextInfo) { // Ngữ cảnh hợp lệ
+ *   const { id, type } = contextInfo;
+ * }
+ * ```
+ */
 declare function getContextAsync(args?: AsyncCallback<ContextInfo>): Promise<ContextInfo | null>;
 
 declare function getAuthCode(args?: AsyncCallback<GetAuthCodeReturns>): Promise<GetAuthCodeReturns>;
@@ -2960,8 +4126,59 @@ declare const chooseImageArgs: ZodObject<{
     sourceType?: ("album" | "camera")[] | undefined;
     cameraType?: "back" | "front" | undefined;
 }>[];
+/**
+ * API chọn hình ảnh từ album hoặc camera.
+ *
+ * @minimumVersion 2.23.4
+ *
+ * @param {("album" | "camera")[]} [sourceType] Nguồn chọn hình ảnh. Có thể chọn từ album/tệp (`album`), chụp ảnh mới từ camera (`camera`), hoặc cả hai.
+ * @param {"back" | "front"} [cameraType] Xác định camera cần mở là camera trước hay sau.
+ * @param {number} [count] Số lượng hình ảnh tối đa có thể chọn.
+ * @returns {ChooseImageReturns} đường dẫn tới hình ảnh đã chọn.
+ * @example Chụp hình ảnh từ camera trước:
+ * ```ts
+ * const { filePaths } = await chooseImage({
+ *   sourceType: ["camera"],
+ *   cameraType: "front",
+ * });
+ * ```
+ * @example Chụp hình ảnh từ camera sau:
+ * ```ts
+ * const { filePaths } = await chooseImage({
+ *   sourceType: ["camera"],
+ *   cameraType: "back",
+ * });
+ * ```
+ * @example Chọn nhiều hình ảnh để viết đánh giá sản phẩm:
+ * ```ts
+ * const { filePaths } = await chooseImage({
+ *   sourceType: ["album", "camera"],
+ *   count: 5,
+ * });
+ * ```
+ */
 declare function chooseImage(args: AsyncCallback<ChooseImageReturns> & TypeOf<(typeof chooseImageArgs)[0]>): Promise<ChooseImageReturns>;
 
+/**
+ * API truy xuất vị trí hiện tại của người dùng. Khi gọi API, một thông báo xin cấp quyền sẽ được hiển thị. Mini App chỉ lấy được thông tin vị trí nếu người dùng đồng ý cấp quyền chia sẻ vị trí.
+ *
+ * Lưu ý, để giúp các nhà phát triển Mini App sử dụng flow xin quyền một cách hiệu quả, cũng như phù hợp với [chính sách của Zalo Mini App điều 3.3.4](https://mini.zalo.me/documents/zalo-mini-app-developer-program-agreement/#33-api-quy%E1%BB%81n-truy-c%E1%BA%ADp), Mini App Team đã đưa ra một số gợi ý thiết kế trải nghiệm như thông tin bên dưới. Nhà phát triển cần giải thích rõ ràng và trực quan mục đích xin quyền để người dùng dễ dàng hiểu và đồng ý cung cấp thông tin.
+ *
+ * Nhằm đảm bảo trải nghiệm thoải mái của người dùng Mini App, chúng tôi sẽ từ chối xét duyệt cho những Mini App có luồng xin cấp quyền chưa rõ ràng, không nêu được mục đích xin quyền đến người dùng.
+ *
+ * @requirePermission Cần xin Cấp quyền sử dụng các API này cho Mini App ID tại trang Quản lý ứng dụng. Nếu không, sẽ bị [lỗi với người dùng bình thường, mặc dù Developer/Admin thì không bị](https://mini.zalo.me/community/8746968970844796879/loi-chi-xay-ra-voi-nguoi-dung-binh-thuong-con-developer-admin-thi-khong-bi).
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ * @behavior Ở môi trường phát triển, API này sẽ luôn thành công và trả về token rỗng (`""`). Khi chạy bên trong ứng dụng Zalo mobile, API này sẽ hiển thị thông báo xin cấp quyền, và trả về token hợp lệ nếu người dùng đồng ý hoặc lỗi nếu người dùng từ chối.
+ *
+ * @returns {GetLocationReturns} token vị trí.
+ * @example
+ * 1. Ở Zalo Mini App, gọi API này để lấy token vị trí:
+ * ```ts
+ * const { token } = await getLocation();
+ * ```
+ * 2. Dùng fetch hoặc axios để gửi token này lên server. Nếu không, bạn sẽ bị [lỗi khi gọi các API Server-Server từ Mini App](https://mini.zalo.me/community/9107262438710014159/loi-khi-goi-cac-api-server-server-tu-mini-app).
+ * 3. Server chuyển đổi token thành thông tin vị trí và trả về cho Mini App theo [hướng dẫn sau](https://mini.zalo.me/documents/api/getLocation/#hướng-dẫn-chuyển-đổi-token-thành-thông-tin-vị-trí-người-dùng).
+ */
 declare function getLocation(args?: AsyncCallback<GetLocationReturns>): Promise<GetLocationReturns>;
 
 declare const onCallbackDataArgs: ZodFunction<ZodTuple<[ZodObject<{
@@ -3356,18 +4573,121 @@ declare const configAppViewArgs: ZodObject<{
     hideAndroidBottomNavigationBar?: boolean | undefined;
     hideIOSSafeAreaBottom?: boolean | undefined;
 }>[];
+/**
+ * API tuỳ chỉnh các thành phần giao diện chính trên Mini App, bao gồm:
+ * - Status bar
+ * - Action bar
+ * - Bottom Navigation (Android) / Safe Area Inset Bottom (iOS)
+ *
+ * Với api `configAppView`, bạn có thể ẩn/ hiện, tuỳ chỉnh màu sắc, kiểu hiển thị của các thành phần mặc định trên Mini App. Xem hình ảnh mô tả bên dưới để hiểu rõ các thành phần có thể tuỳ chỉnh trên Mini App của bạn.
+ *
+ * @minimumVersion Zalo iOS: 23.02.01.r2
+ * @minimumVersion Zalo Android: 23.02.01.r2
+ * @minimumVersion ZMP SDK: 2.25.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} headerColor Mã màu, có giá trị hợp lệ là màu thập lục phân, ví dụ `#000000`.
+ * @param {"white" | "black"} [headerTextColor] Màu của text và icon trên thanh action bar và status bar.
+ * @param {"normal" | "hidden" | "transparent"} [statusBarType="normal"] Kiểu hiển thị của status bar.
+ * @param {boolean} [hideAndroidBottomNavigationBar=false] Ẩn thanh navigation bar trên Android.
+ * @param {boolean} [hideIOSSafeAreaBottom=false] Ẩn thanh safe area inset bottom trên iOS.
+ * @param {boolean} [actionBar.hide] Ẩn action bar.
+ * @param {string} [actionBar.title] Tiêu đề hiển thị trên action bar.
+ * @param {"back" | "none"} [actionBar.leftButton="back"] Tuỳ chỉnh nút điều hướng bên trái action bar. Mặc định hiển thị nút back. Truyền `none` để ẩn nút.
+ * @param {"left" | "center"} [actionBar.textAlign="left"] Tuỳ chỉnh vị trí tiêu đề hiển thị trên action bar.
+ *
+ * @example Thay đổi tiêu đề action bar:
+ * ```ts
+ * configAppView({
+ *   actionBar: {
+ *     title: "Giỏ hàng",
+ *   },
+ * });
+ * ```
+ *
+ * @example Để có được giao diện toàn màn hình:
+ * ```ts
+ * configAppView({
+ *   hideAndroidBottomNavigationBar: true,
+ *   hideIOSSafeAreaBottom: true,
+ *   statusBarType: "transparent", // hoặc "hidden"
+ *   actionBar: {
+ *     hide: true,
+ *   },
+ * });
+ * ```
+ */
 declare function configAppView(args: AsyncVoidCallback & TypeOf<(typeof configAppViewArgs)[0]>): Promise<void>;
 
+/**
+ * API chủ động thu nhỏ ứng dụng. Khi gọi API, Mini App sẽ được thu nhỏ vào một floating icon ở góc màn hình, giúp người sử dụng có thể tạm thời sử dụng các chức năng khác của Zalo, và quay trở lại Mini App của bạn mà không cần phải tải lại từ đầu.
+ *
+ * ![Thu nhỏ ứng dụng](https://mini.zalo.me/documents/img/ZMA-Floating.png)
+ *
+ * @minimumVersion 2.26.1
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @example Thu nhỏ ứng dụng:
+ * ```ts
+ * await minimizeApp();
+ * ```
+ */
 declare function minimizeApp(args?: AsyncVoidCallback): Promise<void>;
 
+/**
+ * API mở cửa sổ Quản lý quyền mà người dùng đã cấp cho Mini App. Người dùng có thể thay đổi các thiết lập quyền (cấp thêm hoặc thu hồi) tại đây.
+ *
+ * @minimumVersion 2.27.1
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @example Mở cửa sổ cài đặt quyền:
+ * ```ts
+ * await openPermissionSetting();
+ * ```
+ */
 declare function openPermissionSetting(args?: AsyncVoidCallback): Promise<void>;
 
+/**
+ * API thêm ứng dụng vào danh sách ưa thích của người dùng ở Zalo Mini Apps Store.
+ * ![Danh sách ưa thích ở Zalo Mini Apps Store](https://mini.zalo.me/documents/img/api/favoriteApp/favorite_screen.jpeg)
+ *
+ * @minimumVersion 2.27.1
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @example Thêm ứng dụng vào danh sách ưa thích:
+ * ```ts
+ * await favoriteApp();
+ * ```
+ */
 declare function favoriteApp(args?: AsyncVoidCallback): Promise<void>;
 
 declare function openGroupList(args?: AsyncVoidCallback): Promise<void>;
 
+/**
+ * API yêu cầu người dùng cho phép nhận thông báo qua OA Mini App. Khi gọi API, một thông báo sẽ được hiển thị.
+ *
+ * @minimumVersion 2.27.1
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @example Yêu cầu người dùng cho phép nhận thông báo:
+ * ```ts
+ * await requestSendNotification();
+ * ```
+ */
 declare function requestSendNotification(args?: AsyncVoidCallback): Promise<void>;
 
+/**
+ * API mở cửa sổ đánh giá ứng dụng, hỗ trợ ghi nhận đánh giá phản hồi của người dùng về chất lượng của Mini App.
+ *
+ * @minimumVersion 2.28.0
+ * @important Chỉ có thể hiển thị cửa sổ đánh giá 1 lần/tuần đối với mỗi người dùng. Quá giới hạn trên sẽ trả về [lỗi](https://mini.zalo.me/documents/api/errorCode/).
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @example Mở cửa sổ đánh giá ứng dụng:
+ * ```ts
+ * await addRating();
+ * ```
+ */
 declare function addRating(args?: AsyncVoidCallback): Promise<void>;
 
 declare const interactOAArgs$1: ZodObject<{
@@ -3377,6 +4697,38 @@ declare const interactOAArgs$1: ZodObject<{
 }, {
     oaId: string;
 }>[];
+/**
+ * API yêu cầu người dùng cho phép gửi thông báo thông qua Official Account. Khi gọi API, một thông báo sẽ được hiển thị.
+ *
+ * @minimumVersion 2.28.8
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} oaId Id của Official Account.
+ *
+ * @example Yêu cầu người dùng cho phép gửi thông báo thông qua Official Account:
+ * ```ts
+ * await interactOA({
+ *   oaId: "xxxx",
+ * });
+ * ```
+ *
+ * @example Xử lý lỗi:
+ * ```ts
+ * try {
+ *   await interactOA({
+ *     oaId: "xxxx",
+ *   });
+ *   console.log("Người dùng đã cho phép");
+ * } catch (error) {
+ *   const code = (error as AppError).code;
+ *   if (code === -201) {
+ *     console.log("Người dùng đã từ chối");
+ *   } else {
+ *     console.log("Lỗi khác");
+ *   }
+ * }
+ * ```
+ */
 declare function interactOA(args: AsyncVoidCallback & TypeOf<(typeof interactOAArgs$1)[0]>): Promise<void>;
 
 declare const interactOAArgs: ZodObject<{
@@ -3388,6 +4740,19 @@ declare const interactOAArgs: ZodObject<{
 }>[];
 declare function checkIsAllowedInteractWithOA(args: AsyncVoidCallback & TypeOf<(typeof interactOAArgs)[0]>): Promise<void>;
 
+/**
+ * API lấy thông tin cài đặt hiện tại của người dùng.
+ *
+ * @minimumVersion 2.31.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @returns {GetSettingReturn} thông tin cài đặt hiện tại của người dùng.
+ *
+ * @example Lấy thông tin cài đặt hiện tại của người dùng:
+ * ```ts
+ * const { authSetting } = await getSetting();
+ * ```
+ */
 declare function getSetting(args?: AsyncCallback<GetSettingReturn>): Promise<GetSettingReturn>;
 
 declare const authorizeArgs: ZodOptional<ZodObject<{
@@ -3397,10 +4762,86 @@ declare const authorizeArgs: ZodOptional<ZodObject<{
 }, {
     scopes?: ("scope.userInfo" | "scope.userLocation" | "scope.userPhonenumber")[] | undefined;
 }>>[];
+/**
+ * ### Cấp quyền sử dụng API
+ *
+ * Một số API cần sự cho phép của người dùng trước khi có thể được gọi. Các API này được chia thành nhiều phạm vi (Scope) tương ứng với từng mục đích sử dụng, mô tả chi tiết tham khảo bảng Scopes:
+ *
+ * | Scope                   | Corresponding APIs | Description                     |
+ * |-------------------------|--------------------|---------------------------------|
+ * | `scope.userInfo`        | `getUserInfo`      | Thông tin user (tên, avatar...) |
+ * | `scope.userLocation`    | `getLocation`      | Thông tin vị trí user           |
+ * | `scope.userPhonenumber` | `getPhoneNumber`   | Số điện thoại                   |
+ *
+ * Khi một API như vậy được gọi:
+ * - Nếu người dùng chưa chấp nhận hoặc từ chối, một cửa sổ pop-up sẽ xuất hiện để hỏi người dùng có muốn chấp nhận không. API chỉ có thể được gọi sau khi người dùng bấm chấp nhận.
+ * - Nếu người dùng đã chấp nhận cho phép, API có thể được gọi trực tiếp.
+ * - Nếu người dùng từ chối cho phép, callback lỗi sẽ được trả về.
+ * - Developer có thể sử dụng api `authorize` để chủ động khởi tạo yêu cầu cấp quyền đối với người dùng khi cần, hỗ trợ xin tối đa 3 quyền (đã bao gồm quyền User Authen).
+ *
+ * ### Lấy trạng thái của scope
+ *
+ * Developer có thể sử dụng API `getSetting` để lấy trạng thái cho phép hiện tại của người dùng.
+ *
+ * ### Quản lý cấp/thu hồi quyền cho người dùng
+ *
+ * Developer có thể gọi API `openPermissionSetting` để mở cài đặt và hướng dẫn người dùng bật/tắt cho phép API.
+ *
+ * ### Thời gian hiệu lực
+ *
+ * Sau khi user đồng ý hoặc từ chối cấp quyền, trạng thái cấp quyền sẽ được ghi nhận và đồng bộ cho những lần sử dụng sau này.
+ *
+ * ### Best Practices
+ *
+ * - Chỉ khởi tạo yêu cầu cấp quyền khi cần thiết, giải thích rõ ràng lý do tại sao bạn muốn sử dụng nó trong yêu cầu cấp quyền.
+ * - Sử dụng API `getSetting` trước để lấy trạng thái cho phép hiện tại của người dùng, sau đó yêu cầu xin cấp thêm các quyền còn thiếu.
+ *
+ * @minimumVersion Zalo iOS: 23.12.02 (573)
+ * @minimumVersion Zalo Android: 23.12.02 (724)
+ * @minimumVersion ZMP SDK: 2.34.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string[]} scopes Danh sách các quyền cần được cấp, tham khảo bảng Scopes.
+ * @returns {Scopes} các trạng thái của các quyền được cấp.
+ * @property {boolean} scope.userInfo Trạng thái quyền thông tin user.
+ * @property {boolean} scope.userLocation Trạng thái quyền vị trí user.
+ * @property {boolean} scope.userPhonenumber Trạng thái quyền số điện thoại.
+ *
+ * @example Khởi tạo cấp quyền
+ * ```ts
+ * try {
+ *   const data = await authorize({
+ *     scopes: ["scope.userLocation", "scope.userPhonenumber"],
+ *   });
+ *   console.log(data["scope.userLocation"]); // `true` nếu người dùng đồng ý cấp vị trí
+ *   console.log(data["scope.userPhonenumber"]); // `true` nếu người dùng đồng ý cấp số điện thoại
+ * } catch (error) {
+ *   const code = (error as AppError).code;
+ *   if (code === -201) {
+ *     console.log("Người dùng đã từ chối cấp quyền");
+ *   } else {
+ *     console.log("Lỗi khác");
+ *   }
+ * }
+ * ```
+ */
 declare function authorize(args?: AsyncVoidCallback & TypeOf<(typeof authorizeArgs)[0]>): Promise<AuthorizeType<(typeof AUTHEN_SCOPE_VALUES)[number]>>;
 
 declare function checkZaloCameraPermission(args?: AsyncCallback<CheckZaloCameraPermissionReturns>): Promise<CheckZaloCameraPermissionReturns>;
 
+/**
+ * API cho phép truy xuất ID người dùng. Với ID là chuỗi định danh người dùng theo Zalo App. Chuỗi này là duy nhất cho mỗi người dùng trên mỗi ID Zalo App. Các Mini App cùng chung một ID Zalo App sẽ có thể dùng chuỗi này để định danh người dùng. (API này sẽ không cần yêu cầu người dùng xác nhận).
+ *
+ * @minimumVersion 2.32.2
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @returns {string} ID người dùng.
+ *
+ * @example Truy xuất ID người dùng:
+ * ```ts
+ * const userID = await getUserID({});
+ * ```
+ */
 declare function getUserID(args?: AsyncCallback<string>): Promise<string>;
 
 declare function getIDToken(args?: AsyncCallback<string>): Promise<string>;
@@ -3543,6 +4984,30 @@ declare const cameraArgs: ZodOptional<ZodObject<{
 }>>[];
 declare function createCameraContext(args: CameraParams & TypeOf<(typeof cameraArgs)[0]>): ZMACamera;
 
+/**
+ * API cấu hình các thông tin dùng để chạy quảng cáo. API cần được gọi khi khởi tạo ứng dụng.
+ *
+ * @minimumVersion 2.37.0
+ * @info Tính năng đang trong giai đoạn thử nghiệm và chỉ được mở cho một số đối tác nhất định.
+ *
+ * @example Bên trong `app.ts`:
+ * ```ts
+ * import React from "react";
+ * import { createRoot } from "react-dom/client";
+ * import { setupAd } from "zmp-sdk/apis";
+ *
+ * import "zmp-ui/zaui.css";
+ * import "./css/app.scss";
+ *
+ * import App from "./components/app";
+ *
+ * // Setup advertising
+ * setupAd();
+ *
+ * const root = createRoot(document.getElementById("app"));
+ * root.render(React.createElement(App));
+ * ```
+ */
 declare function setupAd(args?: AsyncCallback): Promise<void>;
 
 declare const loadAdArgs: ZodObject<{
@@ -3570,6 +5035,47 @@ declare const loadAdArgs: ZodObject<{
     } | undefined;
     ids: string | string[];
 }>[];
+/**
+ * API dùng để tải quảng cáo. Có các loại quảng cáo sau đây:
+ *
+ * | ID             | Size          |
+ * | -------------- | ------------- |
+ * | ZMA_Masthead   | 480x270       |
+ * | ZMA_Middle     | 300x250       |
+ * | ZMA_Fullscreen | Toàn màn hình |
+ * | ZMA_Reward     | Toàn màn hình |
+ * | ZMA_Bottom     | Tùy chỉnh     |
+ *
+ * Mặc định quảng cáo sẽ được hiển thị sau khi tải xong. Vị trí hiển thị quảng cáo sẽ được xác định theo ID của từng loại.
+ *
+ * @minimumVersion 2.37.0
+ *
+ * @param {string | string[]} ids ID của loại quảng cáo cần tải trong trang.
+ * @param {Object} [config] Cấu hình thêm.
+ * @param {boolean} [config.display=true] Hiển thị quảng cáo sau khi tải (true) hoặc không hiển thị (false).
+ * @param {function} [config.onClose] Callback được gọi sau khi quảng cáo ZMA_Reward đóng, trả về reward token.
+ *
+ * @example Tải quảng cáo ZMA_Middle:
+ * ```ts
+ * import React, { useEffect } from "react";
+ * import { loadAd } from "zmp-sdk/apis";
+ *
+ * function HomePage() {
+ *   useEffect(() => {
+ *     loadAd({ ids: ["ZMA_Middle"] });
+ *   }, []);
+ *
+ *   return (
+ *     <>
+ *       ...
+ *       <div id="ZMA_Middle"></div>
+ *     </>
+ *   );
+ * }
+ *
+ * export default HomePage;
+ * ```
+ */
 declare function loadAd(args: AsyncCallback & TypeOf<(typeof loadAdArgs)[0]>): Promise<void>;
 
 declare const displayAdArgs: ZodObject<{
@@ -3579,6 +5085,45 @@ declare const displayAdArgs: ZodObject<{
 }, {
     id: string;
 }>[];
+/**
+ * API dùng để hiển thị quảng cáo sau khi tải xong. Vị trí hiển thị quảng cáo sẽ được xác định theo ID của từng loại.
+ *
+ * @minimumVersion 2.37.0
+ *
+ * @param {string} id ID của loại quảng cáo cần hiển thị trong trang.
+ *
+ * @example Hiển thị quảng cáo ZMA_Middle:
+ * ```ts
+ * import React from "react";
+ * import { createRoot } from "react-dom/client";
+ * import { setupAd, loadAd, displayAd } from "zmp-sdk/apis";
+ *
+ * function App() {
+ *   useEffect(() => {
+ *     displayAd({ id: "ZMA_Middle" });
+ *   }, []);
+ *
+ *   return (
+ *     <>
+ *       ...
+ *       <div id='ZMA_Middle' />
+ *       ...
+ *     </>
+ *   );
+ * }
+ *
+ * setupAd();
+ * loadAd({
+ *   ids: ["ZMA_Middle"],
+ *   config: {
+ *     display: false
+ *   }
+ * });
+ *
+ * const root = createRoot(document.getElementById("app"));
+ * root.render(React.createElement(App));
+ * ```
+ */
 declare function displayAd(args: AsyncCallback & TypeOf<(typeof displayAdArgs)[0]>): Promise<void>;
 
 declare const refreshAdArgs: ZodOptional<ZodObject<{
@@ -3588,6 +5133,18 @@ declare const refreshAdArgs: ZodOptional<ZodObject<{
 }, {
     id?: string | undefined;
 }>>[];
+/**
+ * API dùng để xóa quảng cáo ở phiên hiện tại.
+ *
+ * @minimumVersion 2.37.0
+ *
+ * @param {string} [id] ID của loại quảng cáo cần xóa.
+ *
+ * @example Xóa quảng cáo ZMA_Middle:
+ * ```ts
+ * refreshAd({ id: "ZMA_Middle" });
+ * ```
+ */
 declare function refreshAd(args: AsyncCallback & TypeOf<(typeof refreshAdArgs)[0]>): Promise<void>;
 
 declare const showOAWidgetArgs: ZodObject<{
@@ -3611,6 +5168,46 @@ declare const showOAWidgetArgs: ZodObject<{
     onError?: ((...args: unknown[]) => unknown) | undefined;
     id: string;
 }>[];
+/**
+ * Widget Quan tâm OA: Người dùng bấm nút "Quan tâm" trên widget sẽ thực hiện quan tâm ngay mà không cần hiển thị bottom sheet xin quyền. Thông tin OA được lấy từ OA đã xác thực Mini App.
+ *
+ * @minimumVersion 2.38.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} id ID của element, nơi cần hiển thị widget.
+ * @param {string} [guidingText="Nhận thông báo khuyến mãi mới nhất từ cửa hàng"] Chuỗi dùng để thông báo cho người dùng.
+ * @param {string} [color="#0068FF"] Màu chủ đạo của widget. Giá trị phải là chuỗi hex.
+ * @param {(status: boolean) => void} [onStatusChange] Callback được gọi khi người dùng nhấn theo dõi OA. Trạng thái theo dõi mới được truyền vào tham số của callback.
+ *
+ * @example Hiển thị Widget Quan tâm OA:
+ * ```ts
+ * import React, { useEffect } from "react";
+ * import { showOAWidget } from "zmp-sdk/apis";
+ *
+ * function HomePage() {
+ *   useEffect(() => {
+ *     showOAWidget({
+ *       id: "oaWidget",
+ *       guidingText: "Nhận thông báo khuyến mãi mới nhất từ cửa hàng",
+ *       color: "#0068FF",
+ *       onStatusChange: (status) => {
+ *         console.log(status);
+ *       },
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <>
+ *       ...
+ *       <div id="oaWidget" />
+ *       ...
+ *     </>
+ *   );
+ * }
+ *
+ * export default HomePage;
+ * ```
+ */
 declare function showOAWidget(args: AsyncVoidCallback & TypeOf<(typeof showOAWidgetArgs)[0]>): Promise<void>;
 
 declare const showFunctionButtonWidgetArgs: ZodObject<{
@@ -3640,6 +5237,70 @@ declare const showFunctionButtonWidgetArgs: ZodObject<{
     type: string;
     id: string;
 }>[];
+/**
+ * Widget Function Button: Khi người dùng nhấn vào button này, Mini App sẽ nhận được 1 message token (có giá trị trong 7 ngày) để gửi tin nhắn tới người dùng. Chi tiết hướng dẫn gửi tin nhắn thông qua message token tham khảo [tại đây](https://developers.zalo.me/docs/official-account/tin-nhan/cac-loai-tin-khac/gui-tin-nhan-miniapp-den-nguoi-dung).
+ *
+ * @minimumVersion 2.39.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} id ID của element, nơi cần hiển thị widget.
+ * @param {"ORDER"} type Loại nút, hiện tại chỉ hỗ trợ giá trị: `ORDER`.
+ * @param {"Thanh toán" |"Đặt món" |"Đặt xe" |"Đặt hàng" |"Mua vé" |"Booking" |"Đặt chỗ" |"Tạo đơn hàng" |"Đặt trước" |"Mua hàng" |"Đặt lịch" |"Tra cứu" |"Kiểm tra"} text Chuỗi hiển thị trong button. Phải là một trong các giá trị được cho phép:
+ * - Thanh toán
+ * - Đặt món
+ * - Đặt xe
+ * - Đặt hàng
+ * - Mua vé
+ * - Booking
+ * - Đặt chỗ
+ * - Tạo đơn hàng
+ * - Đặt trước
+ * - Mua hàng
+ * - Đặt lịch
+ * - Tra cứu
+ * - Kiểm tra
+ * @param {string} [fontSize="16px"] Kích thước font chữ. Giá trị nhỏ nhất là 14px.
+ * @param {string} [color="#0068FF"] Màu chủ đạo của widget. Giá trị phải là chuỗi hex.
+ * @param {string} [textColor="#FFFFFF"] Màu chữ trong button. Giá trị phải là chuỗi hex.
+ * @param {string} [borderRadius="48px"] Bo góc (bo tròn các góc của button).
+ * @param {(messageToken: string) => void} [onDataReceived] Callback được gọi khi người dùng nhấn vào widget. Callback này chứa `messageToken` là một token được dùng để gửi tin nhắn tới người dùng. Có giá trị trong 7 ngày.
+ * @param {(error: string) => void} [onError] Callback được gọi khi có lỗi xảy ra khi người dùng nhấn vào widget. Callback này chứa `error` là thông tin về lỗi.
+ *
+ * @example Hiển thị Widget Function Button:
+ * ```ts
+ * import React, { useEffect } from "react";
+ * import { showFunctionButtonWidget } from "zmp-sdk/apis";
+ *
+ * function HomePage() {
+ *   useEffect(() => {
+ *     showFunctionButtonWidget({
+ *       id: "orderButton",
+ *       type: "ORDER",
+ *       text: "Đặt hàng",
+ *       color: "#0068FF",
+ *       textColor: "#FFFFFF",
+ *       borderRadius: "48px",
+ *       onDataReceived: (messageToken) => {
+ *         console.log(messageToken);
+ *       },
+ *       onError: (error) => {
+ *         console.error("onError:", error);
+ *       },
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <>
+ *       ...
+ *       <div id="orderButton" />
+ *       ...
+ *     </>
+ *   );
+ * }
+ *
+ * export default HomePage;
+ * ```
+ */
 declare function showFunctionButtonWidget(args: AsyncVoidCallback & TypeOf<(typeof showFunctionButtonWidgetArgs)[0]>): Promise<void>;
 
 declare const scanNFCArgs: ZodObject<{
@@ -3667,16 +5328,88 @@ declare function scanNFC(args: AsyncCallback & TypeOf<(typeof scanNFCArgs)[0]>):
 declare function checkNFC(args: AsyncVoidCallback): Promise<any>;
 
 declare const getItemArgs: ZodString[];
+/**
+ * Lấy dữ liệu đã lưu ở cache theo cơ chế đồng bộ.
+ *
+ * @minimumVersion 2.43.0
+ * @behavior Ở môi trường phát triển, nhóm API Native Storage sẽ fallback về Local Storage để lưu trữ dữ liệu. Khi chạy bên trong ứng dụng Zalo mobile, Native Storage lưu trữ dữ liệu trong bộ nhớ của ứng dụng Zalo.
+ *
+ * @param {string} key Tên khóa của dữ liệu cần lấy
+ * @returns {string} Giá trị của khóa cần lấy, hoặc `null` nếu khóa không tồn tại.
+ * @example Lấy giá trị tìm kiếm gần đây
+ * ```ts
+ * const keyword = getItem("recentSearch");
+ * ```
+ *
+ * @example Lấy danh sách sản phẩm từ cache. Đảm bảo luôn sử dụng `try/catch` khi parse JSON để tránh lỗi có thể dẫn đến crash app.
+ * ```ts
+ * try {
+ *   const data: Product[] = JSON.parse(getItem("cache.productList"));
+ * } catch (error) {
+ *   // Không tìm thấy dữ liệu trong cache, hoặc dữ liệu không phải chuỗi JSON hợp lệ
+ * }
+ * ```
+ */
 declare function getItem(key: TypeOf<(typeof getItemArgs)[0]>): string;
 
 declare const setItemArgs: ZodString[];
+/**
+ * Lưu trữ dữ liệu xuống bộ đệm theo cơ chế đồng bộ. Dữ liệu sẽ được lưu ở thiết bị của người dùng. Dữ liệu cũ nhất sẽ bị xoá nếu bộ nhớ đạt giới hạn (5MB).
+ *
+ * @minimumVersion 2.43.0
+ * @behavior Ở môi trường phát triển, nhóm API Native Storage sẽ fallback về Local Storage để lưu trữ dữ liệu. Khi chạy bên trong ứng dụng Zalo mobile, Native Storage lưu trữ dữ liệu trong bộ nhớ của ứng dụng Zalo.
+ *
+ * @param {string} key Tên khóa mà bạn muốn tạo/cập nhật.
+ * @param {string} value Giá trị mà bạn muốn cung cấp cho khóa mà bạn đang tạo/cập nhật.
+ * @example Lưu từ khoá tìm kiếm vào bộ nhớ:
+ * ```ts
+ * nativeStorage.setItem("recentSearch", keyword);
+ * ```
+ */
 declare function setItem(key: TypeOf<(typeof setItemArgs)[0]>, value: TypeOf<(typeof setItemArgs)[1]>): void;
 
+/**
+ * Xoá toàn bộ dữ liệu trong cache theo cơ chế đồng bộ.
+ *
+ * @minimumVersion 2.43.0
+ * @behavior Ở môi trường phát triển, nhóm API Native Storage sẽ fallback về Local Storage để lưu trữ dữ liệu. Khi chạy bên trong ứng dụng Zalo mobile, Native Storage lưu trữ dữ liệu trong bộ nhớ của ứng dụng Zalo.
+ *
+ * @example Xoá toàn bộ dữ liệu trong cache:
+ * ```ts
+ * nativeStorage.clear();
+ * ```
+ */
 declare function clear(): void;
 
 declare const removeItemArgs: ZodString[];
+/**
+ * Xoá dữ liệu trong cache theo cơ chế đồng bộ.
+ *
+ * @minimumVersion 2.43.0
+ * @behavior Ở môi trường phát triển, nhóm API Native Storage sẽ fallback về Local Storage để lưu trữ dữ liệu. Khi chạy bên trong ứng dụng Zalo mobile, Native Storage lưu trữ dữ liệu trong bộ nhớ của ứng dụng Zalo.
+ *
+ * @param {string} key Tên khóa của dữ liệu cần xoá
+ *
+ * @example Xoá từ khoá tìm kiếm cũ khỏi bộ nhớ:
+ * ```ts
+ * nativeStorage.removeItem("recentSearch");
+ * ```
+ */
 declare function removeItem(key: TypeOf<(typeof removeItemArgs)[0]>): void;
 
+/**
+ * Lấy thông tin của cache theo cơ chế đồng bộ.
+ *
+ * @minimumVersion 2.43.0
+ * @behavior Ở môi trường phát triển, nhóm API Native Storage sẽ fallback về Local Storage để lưu trữ dữ liệu. Khi chạy bên trong ứng dụng Zalo mobile, Native Storage lưu trữ dữ liệu trong bộ nhớ của ứng dụng Zalo.
+
+ * @returns {StorageInfo} thông tin của cache.
+ *
+ * @example
+ * ```ts
+ * const { currentSize, limitSize } = nativeStorage.getStorageInfo();
+ * ```
+ */
 declare function getStorageInfoSync(): StorageInfo;
 
 declare const nativeStorage: {
@@ -3709,6 +5442,53 @@ declare const downloadFileArgs: ZodOptional<ZodObject<{
 }, {
     url: string;
 }>>[];
+/**
+ * API hỗ trợ tải file về thiết bị. Hỗ trợ giao thức tải file `https://` với các định dạng được liệt kê bên dưới.
+ *
+ * | Định dạng | Đuôi file                                                |
+ * | --------  | -------------------------------------------------------- |
+ * | Văn bản   | pdf, doc, docx, odt, xls, xlsx, ppt, pptx, txt, rtf, csv |
+ * | Hình ảnh  | jpg, jpeg, png, gif, bmp                                 |
+ * | Video     | mp4, avi, mkv, mov, wmv                                  |
+ *
+ * @minimumVersion 2.44.0
+ * @requirePermission Cần xin Cấp quyền sử dụng các API này cho Mini App ID tại trang Quản lý ứng dụng. Nếu không, sẽ bị [lỗi với người dùng bình thường, mặc dù Developer/Admin thì không bị](https://mini.zalo.me/community/8746968970844796879/loi-chi-xay-ra-voi-nguoi-dung-binh-thuong-con-developer-admin-thi-khong-bi).
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} url Đường dẫn của file muốn download.
+ * @param {(progress: number) => void} [onProgress] Callback function tiến độ tải file. Với `progress` là số từ 0 đến 100%.
+ *
+ * @example Thông báo một lần sau khi tải file xong:
+ * ```ts
+ * await downloadFile({
+ *   url: "https://stc-zmp.zadn.vn/mini-app/landingpage-banner-new.png",
+ * });
+ * console.log("Tải file thành công!");
+ * ```
+ *
+ * @example Xử lý lỗi khi tải file (tham khảo bảng mã lỗi tại [đây](https://mini.zalo.me/documents/api/downloadFile/#errors)):
+ * ```ts
+ * try {
+ *   await downloadFile({
+ *     url: "https://stc-zmp.zadn.vn/mini-app/landingpage-banner-new.png",
+ *   });
+ * } catch (error) {
+ *   // Đã có lỗi xảy ra
+ *   console.error(error);
+ * }
+ * ```
+ *
+ * @example Báo cáo tiến độ tải file:
+ * ```ts
+ * await downloadFile({
+ *   url: "https://stc-zmp.zadn.vn/mini-app/landingpage-banner-new.png",
+ *   onProgress: (progress) => {
+ *     console.log(`Đã tải được ${progress}%...`);
+ *   },
+ * });
+ * console.log("Tải file thành công!");
+ * ```
+ */
 declare function downloadFile(args: AsyncProgressCallback & TypeOf<(typeof downloadFileArgs)[0]>): Promise<void>;
 
 declare const eventTypeType: ZodEnum<["APP_INITIALIZING", "APP_READY"]>;
@@ -3719,4 +5499,108 @@ declare const trackingManager: {
     logEvent: typeof logEvent;
 };
 
-export { CameraEvents, CheckoutSDK, Events as EventName, Events, FacingMode, MediaConstraints, MediaDevice, Payment, PhotoConstraint, PhotoFormat, PhotoFrame, PhotoQuality, StreamType, ZMACamera, ZMACameraImp, addRating, authorize, checkNFC, checkStateBioAuthentication, checkTransaction, checkZaloCameraPermission, chooseImage, clearStorage, closeApp, closeLoading, configAppView, connectWifi, createCameraContext, createOrder, createOrderIAP, createShortcut, displayAd, downloadFile, events, favoriteApp, followOA, getAccessToken, getAppInfo, getAuthCode, getBeacons, getContext, getContextAsync, getDeviceId, getDeviceIdAsync, getIDToken, getLocation, getNetworkType, getPhoneNumber, getRouteParams, getSetting, getShareableLink, getStorage, getStorageInfo, getSystemInfo, getUserID, getUserInfo, getVersion, getZPIToken, hideKeyboard, interactOA, interactOA as interactOa, checkIsAllowedInteractWithOA as isAllowedInteractWithOA, keepScreen, loadAd, login, minimizeApp, nativeStorage, offConfirmToExit, offKeepScreen, onCallbackData, onConfirmToExit, onKeepScreen, onNetworkStatusChange, openBioAuthentication, openChat, openGroupList, openMediaPicker, openMiniApp, openOutApp, openPermissionSetting, openPhone, openPostFeed, openProfile, openProfilePicker, openSMS, openShareSheet, openWebview, purchase, refreshAd, removeStorage, requestCameraPermission, requestSendNotification, requestUpdateZalo, saveImageToGallery, saveVideoToGallery, scanNFC, scanQRCode, selectPaymentMethod, sendDataToPreviousMiniApp, setAccessToken, setAndroidBottomNavigationBar, setIOSBottomSafeArea, setNavigationBarColor, setNavigationBarLeftButton, setNavigationBarTitle, setStatusBar, setStorage, setupAd, showFunctionButtonWidget, showOAWidget, showToast, startBeaconDiscovery, stopBeaconDiscovery, trackingManager, unfollowOA, vibrate, viewOAQr };
+declare const showCustomOAWidgetArgs: ZodObject<{
+    id: ZodString;
+    textColor: ZodOptional<ZodString>;
+    fontSize: ZodOptional<ZodString>;
+    buttonHeight: ZodOptional<ZodString>;
+    buttonColor: ZodOptional<ZodString>;
+    buttonTextColor: ZodOptional<ZodString>;
+    buttonRadius: ZodOptional<ZodString>;
+    buttonText: ZodOptional<ZodString>;
+    checkboxBGColor: ZodOptional<ZodString>;
+    checkboxCheckmarkColor: ZodOptional<ZodString>;
+    onClick: ZodOptional<ZodFunction<ZodTuple<[], ZodUnknown>, ZodUnknown>>;
+    onStatusChange: ZodOptional<ZodFunction<ZodTuple<[], ZodUnknown>, ZodUnknown>>;
+    onError: ZodOptional<ZodFunction<ZodTuple<[], ZodUnknown>, ZodUnknown>>;
+}, "strip", ZodAny, {
+    [x: string]: any;
+    textColor?: string | undefined;
+    onStatusChange?: ((...args: unknown[]) => unknown) | undefined;
+    onError?: ((...args: unknown[]) => unknown) | undefined;
+    fontSize?: string | undefined;
+    buttonHeight?: string | undefined;
+    buttonColor?: string | undefined;
+    buttonTextColor?: string | undefined;
+    buttonRadius?: string | undefined;
+    buttonText?: string | undefined;
+    checkboxBGColor?: string | undefined;
+    checkboxCheckmarkColor?: string | undefined;
+    onClick?: ((...args: unknown[]) => unknown) | undefined;
+    id: string;
+}, {
+    [x: string]: any;
+    textColor?: string | undefined;
+    onStatusChange?: ((...args: unknown[]) => unknown) | undefined;
+    onError?: ((...args: unknown[]) => unknown) | undefined;
+    fontSize?: string | undefined;
+    buttonHeight?: string | undefined;
+    buttonColor?: string | undefined;
+    buttonTextColor?: string | undefined;
+    buttonRadius?: string | undefined;
+    buttonText?: string | undefined;
+    checkboxBGColor?: string | undefined;
+    checkboxCheckmarkColor?: string | undefined;
+    onClick?: ((...args: unknown[]) => unknown) | undefined;
+    id: string;
+}>[];
+/**
+ * Nhằm tối ưu hiệu quả tăng follower của OA cho nhóm đối tác nội bộ, đồng thời đảm bảo trải nghiệm của User, không cảm thấy confuse, spam, Platform đã hỗ trợ cho nhóm đối tác nội bộ tool Widget "Quan tâm OA custom".
+ * Đối tác có thể chỉnh sửa và gắn widget vào Mini App.
+ *
+ * @minimumVersion 2.46.0
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} id - ID của element, nơi cần hiển thị widget.
+ * @param {string} [textColor='#6F7071'] - Màu chữ của checkbox ("Đồng ý theo dõi OA").
+ * @param {string} [fontSize='12px'] - Kích thước chữ cho checkbox
+ * @param {string} [buttonHeight='48px'] - Chiều cao của nút CTA.
+ * @param {string} [buttonColor='#0068FF'] - Màu nền của nút CTA.
+ * @param {string} [buttonTextColor='#FFFFFF'] - Màu chữ của nút CTA.
+ * @param {string} [buttonRadius='9999px'] - Border radius của nút CTA.
+ * @param {string} [buttonText='Đồng ý'] - Nội dung hiển thị trên nút CTA.
+ * @param {string} [checkboxBGColor='#0068FF'] - Màu nền của ô checkbox.
+ * @param {string} [checkboxCheckmarkColor='#FFFFFF'] - Màu của dấu check (checkmark) trong checkbox.
+ * @param {(status: boolean) => void} [onClick] - Callback được gọi khi người dùng nhấn nút CTA. Trả về `true` nếu checkbox được tick, ngược lại `false`.
+ * @param {(error: string) => void} [onError] - Callback được gọi khi có lỗi xảy ra trong quá trình tương tác với widget.
+ *
+ * @example Hiển thị Widget Quan tâm OA Custom:
+ * ```ts
+ * import React, { useEffect } from "react";
+ * import { showCustomOAWidget } from "zmp-sdk/apis";
+ *
+ * function HomePage() {
+ *   useEffect(() => {
+ *     showCustomOAWidget({
+ *       id: "oaCustomWidget",
+ *       onClick: (status) => {
+ *         console.log(status);
+ *       },
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <>
+ *       ...
+ *       <div id="oaCustomWidget" />
+ *       ...
+ *     </>
+ *   );
+ * }
+ *
+ * export default HomePage;
+ * ```
+ */
+declare function showCustomOAWidget(args: AsyncVoidCallback & TypeOf<(typeof showCustomOAWidgetArgs)[0]>): Promise<void>;
+
+declare class AppError {
+    code: number;
+    message: string | string[];
+    api?: string | symbol;
+    detail?: any;
+    constructor(code: number, message: string | string[], api?: string | symbol, detail?: any);
+    toString(): string;
+    toJSON(): object;
+}
+
+export { AppError, CameraEvents, CheckoutSDK, Events as EventName, Events, FacingMode, MediaConstraints, MediaDevice, Payment, PhotoConstraint, PhotoFormat, PhotoFrame, PhotoQuality, StreamType, ZMACamera, ZMACameraImp, addRating, authorize, checkNFC, checkStateBioAuthentication, checkTransaction, checkZaloCameraPermission, chooseImage, clearStorage, closeApp, closeLoading, configAppView, connectWifi, createCameraContext, createOrder, createOrderIAP, createShortcut, displayAd, downloadFile, events, favoriteApp, followOA, getAccessToken, getAppInfo, getAuthCode, getBeacons, getContext, getContextAsync, getDeviceId, getDeviceIdAsync, getIDToken, getLocation, getNetworkType, getPhoneNumber, getRouteParams, getSetting, getShareableLink, getStorage, getStorageInfo, getSystemInfo, getUserID, getUserInfo, getVersion, getZPIToken, hideKeyboard, interactOA, interactOA as interactOa, checkIsAllowedInteractWithOA as isAllowedInteractWithOA, keepScreen, loadAd, login, minimizeApp, nativeStorage, offConfirmToExit, offKeepScreen, onCallbackData, onConfirmToExit, onKeepScreen, onNetworkStatusChange, openBioAuthentication, openChat, openGroupList, openMediaPicker, openMiniApp, openOutApp, openPermissionSetting, openPhone, openPostFeed, openProfile, openProfilePicker, openSMS, openShareSheet, openWebview, purchase, refreshAd, removeStorage, requestCameraPermission, requestSendNotification, requestUpdateZalo, saveImageToGallery, saveVideoToGallery, scanNFC, scanQRCode, selectPaymentMethod, sendDataToPreviousMiniApp, setAccessToken, setAndroidBottomNavigationBar, setIOSBottomSafeArea, setNavigationBarColor, setNavigationBarLeftButton, setNavigationBarTitle, setStatusBar, setStorage, setupAd, showCustomOAWidget, showFunctionButtonWidget, showOAWidget, showToast, startBeaconDiscovery, stopBeaconDiscovery, trackingManager, unfollowOA, vibrate, viewOAQr };