ZaloX 🚀

Modern Zalo CLI & API Platform — Automation Unleashed.

ZaloX is a powerful, developer-friendly CLI tool and API server for Zalo automation. It replaces paid tools like zca-cli with a free, open-source alternative built on top of zca-js.

✨ Features

| Feature | ZaloX Free | zca-cli | |---------|------------|---------| | Auth | QR Code & Cookie Login | ✅ | | Messaging | Text, Link, Reply, Undo, React | ✅ | | Contacts | List Friends & Groups | 💰 Paid | | Real-time | Message Listener | 💰 Paid | | Multi-account | Unlimited Profiles | 💰 Paid | | API Server | REST API (zalox serve) | ❌ | | Webhooks | HTTP Forwarding | ❌ | | Platform | Linux, macOS, Windows | Linux only |

📦 Installation

NPM (Node.js)

npm install -g @jackle.dev/zalox

Download the latest binary from Releases.

# Linux / macOS
chmod +x zalox
mv zalox /usr/local/bin/

# Windows
# Add zalox.exe to your PATH

From Source

Requires Bun or Node.js 18+.

git clone https://github.com/lktiep/zalox.git
cd zalox
bun install
bun run build

🚀 Quick Start

1. Login

   zalox auth login
   # Scan the QR code with your Zalo app

2. Send Message

   zalox msg send <user_id> "Hello from ZaloX!"

3. List Friends

   zalox friend list

4. Start Listener

   zalox listen

📚 Commands Reference

Authentication

• zalox auth login - Login via QR code
• zalox auth status - Check current session
• zalox auth logout - Remove credentials
• zalox auth profiles - List all saved profiles
• zalox auth use <profile> - Switch active profile

Messaging

• zalox msg send <id> <text> - Send text message
• zalox msg send-link <id> <url> - Send link with preview
• zalox msg undo <id> <msgId> - Recall a message
• zalox msg react <id> <msgId> <icon> - React (❤️, 👍, 😂, etc.)

Contacts

• zalox friend list - List friends
• zalox friend find <phone> - Find user by phone
• zalox friend add <id> <msg> - Send friend request
• zalox group list - List groups
• zalox group members <id> - List group members
• zalox group create <name> <id1> <id2> - Create new group

Advanced

• zalox listen - Start real-time event listener
• zalox serve - Start REST API Server (Port 3456)
• zalox config set webhook.url <url> - Forward messages to URL
• zalox me info - View detailed account info

🔌 REST API Server

Run zalox serve to expose your Zalo account as a local REST API.

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/me | Account info | | GET | /api/friends | List friends | | GET | /api/groups | List groups | | POST | /api/messages/send | Send message |

Example usage:

curl -X POST http://localhost:3456/api/messages/send \
  -H "Content-Type: application/json" \
  -d '{"threadId": "123456789", "message": "Hello via API"}'

🤖 OpenClaw Plugin

ZaloX includes a native OpenClaw channel plugin (plugin/) that integrates Zalo as a first-class messaging channel — just like Telegram, Discord, or WhatsApp.

Features

• 📥 Inbound: Receive DMs and group messages from Zalo
• 📤 Outbound: Send text, images, and files
• ❤️ Reactions: Auto heart-react on inbound messages
• 👥 Group mentions: Only replies when @tagged in groups
• 🔐 Persistent credentials: Survives container restarts
• 📸 Image upload: Full support via sharp + zca-js uploadAttachment

Setup

1. Configure in openclaw.json:

   {
     "plugins": [{ "source": "/path/to/zalox/plugin" }],
     "channels": {
       "zalox": {
         "accounts": { "default": {} },
         "bindings": [{ "match": { "channel": "zalox" }, "agentId": "main" }]
       }
     }
   }

2. Login via QR:

   tsx plugin/scripts/qr-login.ts

3. Restart OpenClaw — Zalo messages now route to your agent!

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'feat: Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

⚖️ Disclaimer

This tool is not affiliated with, endorsed by, or associated with Zalo Group or VNG Corporation.
It is an unofficial open-source tool built for educational and development purposes.
Use responsibly and at your own risk.

License: MIT