Zalo Personal (unofficial)

Unofficial Zalo personal account automation via native zca-js with QR login, DMs, groups, reactions, and typing indicators.

Zalo Personal is the unofficial counterpart to the Zalo Bot API integration, using the zca-js library to automate a personal Zalo account via QR code login. This gives your AI agent access to features that the official Bot API doesn't expose: reactions, typing indicators, file sharing, and the ability to operate as a regular Zalo user rather than a bot account. Authentication works through Zalo's QR code login flow — scan the QR displayed in your terminal with the Zalo mobile app, and the plugin establishes a session. This mirrors how Zalo's desktop client authenticates, making it feel natural. Once connected, the bot can handle DMs and group chats, send and receive images and files, react to messages, and show typing indicators for a more human-like interaction. Group chat support includes mention gating — the bot only responds when @mentioned in groups, preventing noise. A built-in directory CLI helps discover peers and groups, making it easy to configure allowlists. Per-peer session routing ensures each conversation has independent context. Multi-account support lets you run multiple personal Zalo accounts through a single OpenClaw instance. The critical caveat: this is unofficial. The zca-js library reverse-engineers Zalo's protocol, which means Zalo could change their API at any time and break the integration. There's also a risk of account restrictions if Zalo detects automated usage. For users who need more features than the official Bot API provides and are willing to accept the risks of unofficial automation, this integration delivers a rich, human-like AI assistant experience on Vietnam's most popular messaging platform.

Tags: messaging, vietnam, asia, unofficial, qr-login

Category: Messaging

Use Cases

Feature-rich AI assistant on Zalo with reactions and typing indicators
Personal AI bot on your own Zalo account for Vietnamese users
Group chat AI moderator with mention-gated responses
File exchange AI assistant for document processing via Zalo
Human-like AI chatbot experience on Vietnam's top messaging platform
Multi-account AI deployment across different Zalo identities

Tips

Use a secondary Zalo account for the bot rather than your primary personal account
Monitor for QR code re-authentication prompts — the session can expire
Enable mention gating in groups to prevent the bot from responding to every message
Use the directory CLI (openclaw channels zalouser directory) to discover peer IDs for allowlists
Keep the zca-js dependency updated — protocol changes can break connectivity
Set dmPolicy: 'allowlist' with specific user IDs for production use
Use typing indicators to make the bot feel more natural in conversations
Back up your session credentials if running in Docker — losing the session means re-scanning QR

Known Issues & Gotchas

This is UNOFFICIAL — Zalo could change their protocol at any time and break the integration
Using automation on a personal account risks account restrictions or bans from Zalo
QR code login sessions expire periodically — you'll need to re-scan when they do
The zca-js library must stay updated to track Zalo protocol changes
Running this 24/7 on a personal account may trigger Zalo's anti-automation systems
Group mention gating means the bot only responds when @mentioned — this is by design
Multi-account setup requires separate QR scans for each account
File exchange depends on Zalo's CDN — large files may have upload limits

Alternatives

Zalo (Bot API)
WhatsApp
Telegram
WeChat

Community Feedback

The Zalo Personal plugin gives you way more features than the Bot API — reactions, typing indicators, file sharing. The risk is that it's unofficial and could break. I've been running it for months without issues though.
— Reddit r/selfhosted

zca-js based Zalo integration is impressive. QR login works just like the desktop app. The directory CLI for discovering groups and peers is a nice touch that the Bot API doesn't have.
— GitHub Discussions

Zalo Personal: Zalo personal account via QR code login. This unofficial integration offers more features than the Bot API including reactions and typing indicators, but comes with the risks of using reverse-engineered protocols.
— Hivelocity Blog

Frequently Asked Questions

Is this safe to use on my personal Zalo account?

There's inherent risk. This uses unofficial, reverse-engineered APIs. Zalo could detect automation and restrict your account. Using a secondary account dedicated to the bot is strongly recommended.

How often do I need to re-scan the QR code?

Sessions persist for days to weeks typically, but they can expire unpredictably. Keep terminal access available for re-authentication. Running in a persistent terminal (tmux/screen) helps monitor for QR prompts.

What's the difference between this and the Zalo Bot API plugin?

This plugin automates a personal Zalo account (unofficial, more features like reactions and files). The Zalo Bot API plugin uses the official bot platform (stable, fewer features). Choose based on your risk tolerance and feature needs.

Can the bot send files?

Yes. The zalouser plugin supports sending and receiving files (images and documents) through Zalo's CDN. This is a major advantage over the official Bot API which only supports images.

Does it support reactions?

Yes. The zalouser plugin supports emoji reactions on messages, which the official Bot API does not. This makes interactions feel more natural and human-like.

Is the plugin bundled with OpenClaw?

No. Install it separately: openclaw plugins install @openclaw/zalouser. It's a plugin, not part of core OpenClaw.

What happens if zca-js breaks due to Zalo protocol changes?

The plugin will stop receiving or sending messages. You'll need to wait for a zca-js update that adapts to the new protocol. This is the primary risk of using unofficial integrations — no guaranteed uptime or support.

Configuration Examples

Basic QR login setup

channels:
  zalouser:
    enabled: true
    dmPolicy: pairing

Group chat with mention gating

channels:
  zalouser:
    enabled: true
    dmPolicy: allowlist
    allowFrom:
      - "user-id-1"
      - "user-id-2"
    groupPolicy: allowlist
    groupAllowFrom:
      - "group-id-1"
    requireMention: true

Multi-account setup

channels:
  zalouser:
    enabled: true
    accounts:
      personal:
        dmPolicy: pairing
      business:
        dmPolicy: allowlist
        allowFrom:
          - "customer-id-1"
          - "customer-id-2"
        groupPolicy: open

Installation

openclaw plugins install @openclaw/zalouser