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 install 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, // the message object to reply to (optional)
                },
                message.threadId,
                message.type, // ThreadType.User
            );
            break;
        }
        case ThreadType.Group: {
            api.sendMessage(
                {
                    msg: "echo: " + message.data.content,
                    quote: message, // the message object 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	ZaloDataExtractor - Công cụ trích xuất thông tin cần thiết như IMEI, Cookie và User-Agent từ Zalo Web.
MultiZlogin	Hệ thống quản lý đa tài khoản Zalo, hỗ trợ đăng nhập và quản lý nhiều tài khoản Zalo cùng lúc, tích hợp proxy và webhook.
n8n-nodes-zalo-tools	N8N node cho Zalo cá nhân.

---

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