npm package: @jackle.dev/zalox-plugin
Description: OpenClaw channel plugin for Zalo via zca-js (in-process, single login)
Latest version: 2.0.0

# ZaloX 🚀

> **Modern Zalo CLI & API Platform** — Automation Unleashed.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Built with Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=flat&logo=bun&logoColor=white)](https://bun.sh)
[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)](https://github.com/lktiep/zalox)

**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)

```bash
npm install -g @jackle.dev/zalox
```
Download the latest binary from [Releases](https://github.com/lktiep/zalox/releases).

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

# Windows
# Add zalox.exe to your PATH
```

### From Source
Requires [Bun](https://bun.sh) or Node.js 18+.

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

---

## 🚀 Quick Start

1. **Login**
   ```bash
   zalox auth login
   # Scan the QR code with your Zalo app
   ```

2. **Send Message**
   ```bash
   zalox msg send <user_id> "Hello from ZaloX!"
   ```

3. **List Friends**
   ```bash
   zalox friend list
   ```

4. **Start Listener**
   ```bash
   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:**
```bash
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`:
   ```json
   {
     "plugins": [{ "source": "/path/to/zalox/plugin" }],
     "channels": {
       "zalox": {
         "accounts": { "default": {} },
         "bindings": [{ "match": { "channel": "zalox" }, "agentId": "main" }]
       }
     }
   }
   ```
2. Login via QR:
   ```bash
   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