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
• Documentation
• Basic Usages
  • Login
  • Listen for new messages
  • Send a message
  • Get/Send a sticker
• Example
• Projects
• Contributing
• License
• Support Our Mission

Installation

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

---

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

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.

---

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 Our Mission

• ⭐ Star our repositories if you find them useful!
• 🔄 Share with your network to help us grow
• 💡 Contribute your ideas and code