mochi-zalo

Zalo personal API library for Node.js & TypeScript

Automate Zalo messaging, manage groups and friends, listen to real-time events — with full TypeScript support.

Features

• Multi-account — manage multiple Zalo accounts simultaneously
• Real-time events — WebSocket listener for messages, reactions, group events
• QR Login — scan-to-login flow with retry protection
• Session persistence — save and restore login sessions
• Type-safe — full TypeScript support with strict types
• Secure — URL whitelist on redirects, bounded retry loops, no phone-home telemetry

Installation

npm install mochi-zalo

Quick Start

import { Zalo, LoginQRCallbackEventType } from "mochi-zalo";

const zalo = new Zalo({
    logging: true,
});

// QR Login
const api = await zalo.loginQR({}, (event) => {
    if (event.type === LoginQRCallbackEventType.GotQR) {
        // event.data.image — base64 QR image
        // event.data.filePath — saved file path
        console.log("Scan QR code to login");
    }
});

// Send a message
const result = await api.sendMessage(
    { text: "Hello from mochi-zalo!" },
    "recipient-uid",
    ThreadType.User,
);

// Listen to events
const listener = api.listener();
listener.on("message", (msg) => {
    console.log("New message:", msg.data.content);
});
await listener.start();

Session Persistence

import { Zalo, saveSession, loadSession, isSessionValid } from "mochi-zalo";

// Save session after login
const api = await zalo.login(credentials);
const ctx = api.getContext();
await saveSession(ctx, "./session.json");

// Restore session
const session = await loadSession("./session.json");
if (session && await isSessionValid(session)) {
    const api = await zalo.login({
        cookie: session.cookie,
        imei: session.imei,
        userAgent: session.userAgent,
    });
}

Architecture

src/
├── Errors/        — Typed error hierarchy (ZaloAuthError, ZaloNetworkError, etc.)
├── crypto/        — AES encryption, request signing
├── http/          — HTTP client with security (redirect whitelist, retry logic)
├── helpers/       — Pure utility functions (format, uuid, color)
├── media/         — Image, GIF, and file utilities
├── models/        — TypeScript type definitions
├── apis/          — 120+ Zalo API implementations
├── context.ts     — Session context types
├── session.ts     — Session save/load helpers
├── zalo.ts        — Main Zalo class
└── index.ts       — Public API surface

Error Handling

import { ZaloApiError, ZaloAuthError, ZaloNetworkError } from "mochi-zalo";

try {
    await api.sendMessage(...);
} catch (err) {
    if (err instanceof ZaloAuthError) {
        // Re-login required
    } else if (err instanceof ZaloNetworkError) {
        // Network issue, can retry
    } else if (err instanceof ZaloApiError) {
        // Other Zalo API error
    }
}

Security

This package implements several security measures:

• Redirect URL whitelist: only follows redirects to trusted Zalo domains
• Bounded retry loops: QR scan loops are capped at 60 iterations (no infinite recursion)
• No telemetry: no phone-home, no version checks, no external calls on startup
• Session isolation: cookie jars are per-instance, not shared

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (if using TypeScript)

License

MIT © Cong Dinh