ZCA-JS

Note

This is an unofficial Zalo API for personal account. It work by simulating the browser to interact with Zalo Web.

Warning

Using this API could get your account locked or banned. We are not responsible for any issues that may happen. Use it at your own risk.

---

Table of Contents

• Installation
  • Migrate to V2
• Documentation
• Basic Usages
  • Login
  • Listen for new messages
  • Send a message
  • Get/Send a sticker
• Example
• Projects & Useful Resources
• Contributing
• License
• Support Us

Installation

bun add zca-js # or npm install zca-js

Migrate to V2

Since official version 2.0.0, zca-js has removed sharp dependency for image metadata extraction. It now requires users to provide their own imageMetadataGetter function when initializing the Zalo class if they want to send images/gifs by file path.

Example of custom imageMetadataGetter using sharp:

bun add sharp # or npm install sharp

import { Zalo } from "zca-js";
import sharp from "sharp";
import fs from "fs";

async function imageMetadataGetter(filePath) {
    const data = await fs.promises.readFile(filePath);
    const metadata = await sharp(data).metadata();
    return {
        height: metadata.height,
        width: metadata.width,
        size: metadata.size || data.length,
    };
}

const zalo = new Zalo({
    imageMetadataGetter,
});

---

Documentation

See API Documentation for more details.

---

Basic Usages

Login

import { Zalo } from "zca-js";

const zalo = new Zalo();
const api = await zalo.loginQR();

Listen for new messages

import { Zalo, ThreadType } from "zca-js";

const zalo = new Zalo();
const api = await zalo.loginQR();

api.listener.on("message", (message) => {
    const isPlainText = typeof message.data.content === "string";

    switch (message.type) {
        case ThreadType.User: {
            if (isPlainText) {
                // received plain text direct message
            }
            break;
        }
        case ThreadType.Group: {
            if (isPlainText) {
                // received plain text group message
            }
            break;
        }
    }
});

api.listener.start();

Important

Only one web listener can run per account at a time. If you open Zalo in the browser while the listener is active, the listener will be automatically stopped.

Send a message

import { Zalo, ThreadType } from "zca-js";

const zalo = new Zalo();
const api = await zalo.loginQR();

// Echo bot
api.listener.on("message", (message) => {
    const isPlainText = typeof message.data.content === "string";
    if (message.isSelf || !isPlainText) return;

    switch (message.type) {
        case ThreadType.User: {
            api.sendMessage(
                {
                    msg: "echo: " + message.data.content,
                    quote: message.data, // the message to reply to (optional)
                },
                message.threadId,
                message.type, // ThreadType.User
            );
            break;
        }
        case ThreadType.Group: {
            api.sendMessage(
                {
                    msg: "echo: " + message.data.content,
                    quote: message.data, // the message to reply to (optional)
                },
                message.threadId,
                message.type, // ThreadType.Group
            );
            break;
        }
    }
});

api.listener.start();

Get/Send a sticker

api.getStickers("hello").then(async (stickerIds) => {
    // Get the first sticker
    const stickerObject = await api.getStickersDetail(stickerIds[0]);
    api.sendMessageSticker(
        stickerObject,
        message.threadId,
        message.type, // ThreadType.User or ThreadType.Group
    );
});

---

Example

See examples folder for more details.

---

Projects & Useful Resources

Repository	Description
ZaloDataExtractor	A browser Extension to extract IMEI, cookies, and user agent from Zalo Web.
MultiZlogin	A multi-account Zalo management system that lets you log in to and manage multiple accounts simultaneously, with proxy and webhook integration.
n8n-nodes-zalo-tools	N8N node for personal Zalo account.
Zalo-F12	A collection of JavaScript code snippets to paste into DevTools to change how Zalo Web/PC works.
Zalo-F12-Tools	Toggle hidden modes for Zalo Web.

---

Contributing

We welcome contributions from the community! Please see our Contributing Guidelines for details on how to:

• 🐛 Report bugs and issues
• ✨ Suggest new features
• 🔧 Submit code contributions
• 📚 Improve documentation
• 🧪 Add or improve tests
• 🔒 Report security vulnerabilities

For more information, please read our Code of Conduct and Security Policy before participating.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Support Us

• ⭐ Star our repositories if you find them useful!
• 🔄 Share with your network to help us grow
• 💡 Contribute your ideas and code
• ☕ A coffee:
  • Buy Me a Coffee
  • Paypal
  • VietQR
  • Momo