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 "node: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

---

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