{"id":12701,"library":"zca-js","title":"Unofficial Zalo API for JavaScript","description":"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.","status":"active","version":"2.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/RFS-ADRENO/zca-js","tags":["javascript","chatbot","zalo","api","typescript"],"install":[{"cmd":"npm install zca-js","lang":"bash","label":"npm"},{"cmd":"yarn add zca-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add zca-js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for `imageMetadataGetter` if sending images/gifs by file path; not a direct dependency of the library itself since v2.0.0.","package":"sharp","optional":true}],"imports":[{"note":"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.","wrong":"const Zalo = require('zca-js')","symbol":"Zalo","correct":"import { Zalo } from 'zca-js'"},{"note":"ThreadType is an enum used to distinguish between different conversation types (e.g., User, Group) when handling messages.","wrong":"import ThreadType from 'zca-js'","symbol":"ThreadType","correct":"import { ThreadType } from 'zca-js'"},{"note":"Specific error classes like ZaloApiLoginQRAborted were introduced in v2.0.3 to provide clearer error handling for login operations.","wrong":"const { ZaloApiLoginQRAborted } = require('zca-js')","symbol":"ZaloApiLoginQRAborted","correct":"import { ZaloApiLoginQRAborted } from 'zca-js'"}],"quickstart":{"code":"import { Zalo, ThreadType } from 'zca-js';\n\nconst zalo = new Zalo();\n// For advanced image sending by file path, you might need to provide an imageMetadataGetter:\n// import sharp from 'sharp';\n// import fs from 'node:fs';\n// async function imageMetadataGetter(filePath) {\n//     const data = await fs.promises.readFile(filePath);\n//     const metadata = await sharp(data).metadata();\n//     return {\n//         height: metadata.height,\n//         width: metadata.width,\n//         size: metadata.size || data.length,\n//     };\n// }\n// const zalo = new Zalo({ imageMetadataGetter });\n\nasync function runBot() {\n  const api = await zalo.loginQR(); // Authenticates via QR code displayed in the console.\n  console.log('Logged in successfully!');\n\n  api.listener.on('message', (message) => {\n    const isPlainText = typeof message.data.content === 'string';\n    if (message.isSelf || !isPlainText) return; // Ignore messages from self or non-plain text.\n\n    console.log(`Received message from ${message.threadId} (${message.type}): ${message.data.content}`);\n\n    const replyMessage = `echo: ${message.data.content}`;\n    const quoteData = message.data; // Optional: quote the original message.\n\n    switch (message.type) {\n      case ThreadType.User: {\n        api.sendMessage(\n          { msg: replyMessage, quote: quoteData },\n          message.threadId,\n          message.type\n        );\n        console.log(`Sent echo to user ${message.threadId}`);\n        break;\n      }\n      case ThreadType.Group: {\n        api.sendMessage(\n          { msg: replyMessage, quote: quoteData },\n          message.threadId,\n          message.type\n        );\n        console.log(`Sent echo to group ${message.threadId}`);\n        break;\n      }\n    }\n  });\n\n  api.listener.on('disconnected', (reason) => {\n    console.warn(`Listener disconnected: ${reason}. Attempting to restart...`);\n    // In a production environment, you might want to implement a robust retry mechanism.\n    // For this example, we just log.\n  });\n\n  api.listener.start();\n  console.log('Listener started. Waiting for messages...');\n}\n\nrunBot().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Install `sharp` (e.g., `npm install sharp`) and pass an `imageMetadataGetter` function (as shown in the README) to the `Zalo` constructor.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update any calls from `getRequestStatus` to `getFriendRequestStatus` in your codebase.","message":"The API method `getRequestStatus` was renamed to `getFriendRequestStatus` in `v2.0.0-beta.27` for clarity and consistency.","severity":"breaking","affected_versions":">=2.0.0-beta.27"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"Only 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.","severity":"gotcha","affected_versions":"*"},{"fix":"Regularly update `zca-js` to the latest version and monitor the GitHub repository for announcements regarding compatibility issues and new releases.","message":"As `zca-js` simulates Zalo Web, changes to Zalo's frontend or backend APIs can introduce breaking changes or unexpected behavior, potentially requiring library updates.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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()`.","cause":"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.","error":"Unhandled promise rejection (or similar error indicating crash on loginQR abort)"},{"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.","cause":"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.","error":"Authentication or session issues, incorrect cookie handling, or failed logins."},{"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.","cause":"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.","error":"BigInt: Failed to convert a Number to a BigInt value (or incorrect large number values in message quotes/IDs)"}],"ecosystem":"npm"}