Registry / http-networking / zca-js

zca-js

JSON →
library2.1.2jsnpmunverified

zca-js is an unofficial JavaScript/TypeScript library designed to interact with the Zalo platform for personal accounts by simulating a web browser's interaction with Zalo Web. The current stable version is 2.1.2, and the project maintains an active release cadence, frequently publishing patches and minor updates to address bugs and introduce new API functionalities. It ships with TypeScript types, facilitating robust development. A key differentiator is its approach of simulating browser behavior, which allows access to features typically unavailable through official APIs. However, this method comes with a significant warning: using the library carries a risk of account suspension or banning, and the maintainers explicitly disclaim responsibility for such outcomes. Developers are advised to proceed with caution and consider using dedicated test accounts.

npm install zca-js
INSTALL
IMPORT
SIG · ZCA-JS
Z
zca-js
http-networkingjavascriptv2.1.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Zalo
import { Zalo } from 'zca-js'
const Zalo = require('zca-js')
The Zalo class is the primary entry point for the API. ESM import is recommended given the package's `node` engine requirement and TypeScript types.
ThreadType
import { ThreadType } from 'zca-js'
import ThreadType from 'zca-js'
ThreadType is an enum used to distinguish between different conversation types (e.g., User, Group) when handling messages.
ZaloApiLoginQRAborted
import { ZaloApiLoginQRAborted } from 'zca-js'
const { ZaloApiLoginQRAborted } = require('zca-js')
Specific error classes like ZaloApiLoginQRAborted were introduced in v2.0.3 to provide clearer error handling for login operations.

Demonstrates how to log in with a QR code, set up a listener for incoming messages, and implement a basic echo bot that replies to direct and group messages received.

import { Zalo, ThreadType } from 'zca-js'; const zalo = new Zalo(); // For advanced image sending by file path, you might need to provide an imageMetadataGetter: // 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 }); async function runBot() { const api = await zalo.loginQR(); // Authenticates via QR code displayed in the console. console.log('Logged in successfully!'); api.listener.on('message', (message) => { const isPlainText = typeof message.data.content === 'string'; if (message.isSelf || !isPlainText) return; // Ignore messages from self or non-plain text. console.log(`Received message from ${message.threadId} (${message.type}): ${message.data.content}`); const replyMessage = `echo: ${message.data.content}`; const quoteData = message.data; // Optional: quote the original message. switch (message.type) { case ThreadType.User: { api.sendMessage( { msg: replyMessage, quote: quoteData }, message.threadId, message.type ); console.log(`Sent echo to user ${message.threadId}`); break; } case ThreadType.Group: { api.sendMessage( { msg: replyMessage, quote: quoteData }, message.threadId, message.type ); console.log(`Sent echo to group ${message.threadId}`); break; } } }); api.listener.on('disconnected', (reason) => { console.warn(`Listener disconnected: ${reason}. Attempting to restart...`); // In a production environment, you might want to implement a robust retry mechanism. // For this example, we just log. }); api.listener.start(); console.log('Listener started. Waiting for messages...'); } runBot().catch(console.error);
Debug
Known issues
breakingVersion 2.0.0 removed `sharp` as a direct dependency. If you intend to send images or GIFs using file paths, you must manually install `sharp` and provide a custom `imageMetadataGetter` function during `Zalo` class instantiation.
fix
Install `sharp` (e.g., `npm install sharp`) and pass an `imageMetadataGetter` function (as shown in the README) to the `Zalo` constructor.
affects: >=2.0.0
breakingThe API method `getRequestStatus` was renamed to `getFriendRequestStatus` in `v2.0.0-beta.27` for clarity and consistency.
fix
Update any calls from `getRequestStatus` to `getFriendRequestStatus` in your codebase.
affects: >=2.0.0-beta.27
gotchaThis is an unofficial API that simulates browser interaction. Using it carries a significant risk of your Zalo account being locked or banned. The library authors explicitly disclaim responsibility for any issues that may arise.
fix
Proceed with extreme caution. It is strongly recommended to use this library only with a dedicated test account and to be aware of the potential consequences.
affects: *
gotchaOnly one Zalo web listener can run per account at a time. If the Zalo web client is opened in a browser while `zca-js`'s listener is active, the listener will be automatically stopped.
fix
Ensure no other Zalo web sessions are open or active when running the listener to maintain continuous operation. Implement robust reconnection logic for production use cases.
affects: *
gotchaAs `zca-js` simulates Zalo Web, changes to Zalo's frontend or backend APIs can introduce breaking changes or unexpected behavior, potentially requiring library updates.
fix
Regularly update `zca-js` to the latest version and monitor the GitHub repository for announcements regarding compatibility issues and new releases.
affects: *
Errors
Common errors & fixes
Unhandled promise rejection (or similar error indicating crash on loginQR abort)
In versions prior to `v2.0.4`, the `loginQR` function might have thrown an error instead of rejecting a promise when the login process was aborted, leading to unhandled rejections.
fix
Upgrade to `zca-js` `v2.0.4` or newer to ensure `loginQR` correctly rejects its promise upon abortion, allowing for proper error handling with `.catch()`.
Authentication or session issues, incorrect cookie handling, or failed logins.
Older versions (prior to `v2.1.2`) had fixes related to setting correct cookie domains and properly parsing `Set-Cookie` headers, which are critical for maintaining a stable session.
fix
Upgrade to `zca-js` `v2.1.2` or newer to benefit from fixes addressing cookie parsing and domain handling, which are essential for stable authentication and session management.
BigInt: Failed to convert a Number to a BigInt value (or incorrect large number values in message quotes/IDs)
In versions prior to `v2.0.0-beta.26`, large numerical IDs from the Zalo API (e.g., `quote.ownerId`) could exceed JavaScript's safe integer limit, leading to rounding errors or conversion failures.
fix
Upgrade to `zca-js` `v2.0.0-beta.26` or newer, which integrated `json-bigint` to correctly handle large integer values from the Zalo API, preventing data corruption.
Upgrade
Version history
2.1.2latest on npm
Audit
Dependencies
sharpoptionalRequired for `imageMetadataGetter` if sending images/gifs by file path; not a direct dependency of the library itself since v2.0.0.
Agent activity
77 hits · last 30 days
node
68
OpenAI (training)
1
Resources