slidge-zalo

A Zalo gateway for XMPP, built on the Slidge framework.

Chat with your Zalo friends and groups from any XMPP client — no official Zalo app required on your desktop.

---

✨ Features

Feature	Status
🔐 QR-code login	✅
💬 Direct messages (1-on-1)	✅
👥 Group chats (MUC)	✅
📎 Media, photos, voice, GIFs, files	✅
💬 Reply / quote messages	✅
✏️ Typing indicators	✅
🟢 Presence / online status	✅
🔍 Search contacts by phone or username	✅
👤 Send / accept / cancel friend requests	✅
🖼️ Avatars (user & group)	✅
🔗 Link previews	✅
🏷️ Stickers	✅
📜 Message history backfill (groups)	✅

---

🏗️ Architecture

┌─────────────┐       XMPP       ┌──────────────┐      stdin/stdout      ┌─────────┐
│ Your XMPP   │ ◄──────────────► │   slidge     │ ◄────────────────────► │ zca-js  │
│   client    │                  │  (Python)    │   newline-delimited    │ (Node)  │
└─────────────┘                  └──────────────┘        JSON            └────┬────┘
                                                                              │
                                                                              ▼
                                                                        ┌─────────┐
                                                                        │  Zalo   │
                                                                        │ servers │
                                                                        └─────────┘

• Python side (slidge) — handles the XMPP component protocol, roster, MUC rooms, and media upload.
• Node.js bridge (zca-js) — the unofficial Zalo client library. Communicates with the Python side over JSON lines on stdin/stdout.

---

🚀 Quick Start (Docker Compose)

The easiest way to run slidge-zalo is with the provided docker-compose.yml.

1. Create directories

mkdir -p data attachments

2. Create a .env file

# .env
SLIDGE_JID=zalo.example.com
SLIDGE_SECRET=your-component-secret
SLIDGE_SERVER=ejabberd
SLIDGE_ADMINS=admin@example.com

3. Configure docker-compose.yml

Edit the command: section in docker-compose.yml to match your server:

services:
  slidge-zalo:
    image: roiarthurb/slidge-zalo:latest
    user: "9000:9000"
    restart: unless-stopped
    volumes:
      - ./data:/data:rw
      - ./attachments:/attachments:rw
    environment:
      SLIDGE_LEGACY_MODULE: slidge_zalo
      SLIDGE_HOME_DIR: /data
    command:
      - "--admins=admin@example.com"
      - "--jid=zalo.example.com"
      - "--secret=your-component-secret"
      - "--user-jid-validator=.*@example.com"
      - "--no-upload-path=/attachments"
      - "--no-upload-url-prefix=https://files.example.com/attachments"
      - "--home-dir=/data"

💡 Tip: --no-upload-path + --no-upload-url-prefix let slidge serve attachments from a local folder exposed by your reverse proxy, instead of uploading them to an HTTP file server.

4. Start it

docker compose up -d

5. Register your account

In your XMPP client, start a chat with the component (zalo.example.com) and follow the registration flow. You will receive a QR code — scan it with the Zalo mobile app to link your account.

---

🐳 Docker

Build locally

docker build . -t roiarthurb/slidge-zalo:latest

Run

docker run -d \
  --name slidge-zalo \
  -v ./data:/data \
  -v ./attachments:/attachments \
  -e SLIDGE_LEGACY_MODULE=slidge_zalo \
  roiarthurb/slidge-zalo:latest \
  --jid=zalo.example.com \
  --secret=your-secret \
  --admins=admin@example.com \
  --user-jid-validator=.*@example.com \
  --home-dir=/data

---

🧑‍💻 Development

Requirements

• Python ≥ 3.11
• Node.js ≥ 18
• A running XMPP server with component support (ejabberd, Prosody, Openfire …)

Install

# 1. Python dependencies
python -m venv .venv
source .venv/bin/activate
pip install -e .

# 2. Node.js bridge dependencies
cd slidge_zalo/bridge && npm install && cd ../..

Run

slidge --legacy-module=slidge_zalo \
       --jid=zalo.localhost \
       --secret=secret \
       --admins=admin@localhost \
       --user-jid-validator=.*@localhost \
       --debug

---

⚙️ Configuration Reference

All standard Slidge CLI options work. The most common ones for slidge-zalo:

Option	Description	Example
--jid	XMPP component JID	zalo.example.com
--secret	Shared secret with the XMPP server	hunter2
--server	XMPP server host	ejabberd
--admins	Comma-separated admin JIDs	admin@example.com
--user-jid-validator	Regex restricting who can register	.*@example.com
--home-dir	Persistent data directory	/data
--no-upload-path	Local path for attachments	/attachments
--no-upload-url-prefix	Public URL prefix for attachments	https://files.example.com/attachments
--debug	Verbose logging	—

---

🔒 Security Notes

• Your Zalo credentials (IMEI, cookies, user-agent) are stored locally in the --home-dir directory. Never share this folder.
• The bridge communicates with Zalo's unofficial API. Use at your own risk.
• slidge-zalo is not affiliated with or endorsed by Zalo Group / VNG Corporation.

---

🏭 Forgejo CI

This repository includes a Forgejo Actions workflow (.forgejo/workflows/docker.yml) that automatically builds and pushes the Docker image to a Forgejo Container Registry on every push to main and every v* tag.

Set these secrets in your repo settings:

Secret	Description
REGISTRY_USERNAME	Your Forgejo username
REGISTRY_PASSWORD	Forgejo access token with package:write scope

---

📜 License

AGPL-3.0-or-later

Copyright (C) 2024  RoiArthurB

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

---

🙏 Acknowledgements

• Slidge — the XMPP bridging framework
• zca-js — the unofficial Zalo Node.js client