n8n-nodes-zalo-user-v3

Professional Zalo integration for n8n workflows. Automate Zalo messaging, group management, and business operations directly within n8n—completely self-hosted with no external dependencies.

Version: 0.0.69 | License: MIT | Node.js: ≥18.10 | pnpm: ≥9.1

Overview

n8n-nodes-zalo-user-v3 provides three integration pathways for Zalo automation:

| Integration | Type | Use Case | |------------|------|----------| | ZaloUser | Unofficial Web API | Personal account automation, chatbots, message automation | | ZaloBot | Official API | Bot account operations, follower management | | ZaloOA | Official API | Official Account operations, business broadcasting |

All data remains private within your n8n instance—no cloud processing, no third-party servers.

Installation

Via n8n Community Nodes (Recommended)

1. Open n8n editor (v0.187+)
2. Go to Settings > Community Nodes
3. Search for "n8n-nodes-zalo-user-v3"
4. Click Install → Reload

Manual Installation

cd YOUR_N8N_INSTALLATION_DIRECTORY
npm install n8n-nodes-zalo-user-v3

Features

ZaloUser Nodes (Personal Account)

Trigger: Real-time event listening (messages, group events, reactions, undo) Action: 80+ operations including send, friend management, groups, polling, TTS

| Feature | Basic | Premium | |---------|-------|---------| | QR/Cookie Login | ✅ | ✅ | | Real-time Messages | ✅ | ✅ | | Send Messages/Stickers | ✅ | ✅ | | View Friends | ✅ | ✅ | | Proxy Support | ❌ | ✅ | | Group Events | ❌ | ✅ | | Group Management | ❌ | ✅ | | Message Reactions | ❌ | ✅ | | Text-to-Speech | ❌ | ✅ | | User Search | ❌ | ✅ | | Polls & Reminders | ❌ | ✅ |

ZaloBot Node (Official Bot API)

• Send messages to followers
• Manage follower relationships
• Retrieve conversation history

ZaloOA Node (Official OA API)

• Send broadcasts to followers
• Message templating
• Follower management
• OAuth2 credential handling

ZaloManager Node (Multi-Account Webhook)

• Web UI for account management
• REST API for multi-account operations
• PostgreSQL backend for message history
• Multipart message upload support

Quick Start

1. Add ZaloUserLogin Trigger

1. Create new workflow
2. Add ZaloUserLogin trigger node
3. Click "Execute" to generate QR code
4. Scan with Zalo phone app
5. Credentials auto-created on approval

2. Add ZaloUser Trigger (Real-time)

1. Add ZaloUser trigger node
2. Select credential from dropdown
3. Configure event filtering (optional)
4. Toggle workflow active

3. Add ZaloUserInteract Action

1. Add ZaloUserInteract node
2. Select Resource (Message, Friend, Group, Get, Tool)
3. Select Operation (Send Message, Add User, etc.)
4. Fill operation-specific parameters
5. Test and execute

Example: Send Reply Message

Resource:    Message
Operation:   Send Message
Thread ID:   {{ $json.threadId }}  (from trigger)
Thread Type: User
Message:     Hello from n8n!

Credentials

ZaloUserCredentialsApi (Personal Account)

Required fields after QR login:

• Cookie (session token)
• IMEI (device identifier)
• UserAgent (browser signature)
• License Key (for premium features)

ZaloBotApi (Official Bot)

• Bot API Token

ZaloOACredentialsApi (Official Account)

• App ID
• App Secret
• OAuth2 Access Token

Documentation

• Project Overview & PDR — Business model, constraints, requirements
• Codebase Summary — Directory structure, file organization, metrics
• Code Standards — TypeScript, ESLint, naming conventions, patterns
• System Architecture — Component design, data flow, security
• Project Roadmap — Current status, phases, future improvements

Important: Single Session Limitation

Zalo enforces one active browser session per account. If you log in elsewhere, the n8n connection breaks.

To reconnect:

1. Update credentials (re-authorize)
2. Turn workflow off, then on
3. Connection restored

Security & Privacy

• All credentials encrypted by n8n before storage
• No data transmitted to external servers (ZaloUser)
• HMAC-SHA256 license verification
• Webhook endpoint protected by basic auth
• No credential logging to console

Premium License

Premium features (proxy, groups, reactions, TTS) require valid license key.

Get license: Linktr.ee/n8nzalo

Troubleshooting

Trigger Node Stops Working

Possible causes:

• Logged in elsewhere → Session disconnected
• Zalo detected unusual activity
• Network connectivity issue

Fix:

1. Update credentials (re-scan QR)
2. Turn workflow off → back on
3. Check n8n error logs

Premium Feature Error

"Premium feature requires valid license"

1. Verify license key in credentials
2. Check license server availability
3. Contact support if license is valid

Connection Timeout

• Check firewall/proxy settings
• Enable proxy in credentials if needed (premium)
• Increase timeout in node configuration

Known Limitations

1. Single active session per account (Zalo policy)
2. Unofficial ZaloUser API may break if Zalo updates protocol
3. No automatic reconnect on permanent session loss
4. Limited error recovery for network failures

Roadmap

• Phase 1: Enhanced error recovery, automated testing, complete docs
• Phase 2: Message delivery tracking, advanced groups, performance optimization
• Phase 3: Zalo Business API, workflow templates, analytics dashboard
• v1.0.0: Production-stable, enterprise support

See Project Roadmap for details.

Contributing

Contributions welcome! Please:

1. Fork repository
2. Create feature branch (git checkout -b feature/my-feature)
3. Follow Code Standards
4. Run linting: pnpm lint
5. Submit pull request

Legal Disclaimer

This project is not affiliated with Zalo. Using the unofficial ZaloUser API may violate Zalo's terms of service and could result in:

• Account lockout
• Account ban
• Data loss

Use at your own risk. We assume no responsibility for any consequences.

For business use, strongly recommend official Zalo Bot or OA APIs instead.

Support

• GitHub Issues — Bug reports & feature requests
• Demo Workflow — Setup guide & examples
• n8n Community — Ask questions in n8n forums

License

MIT License

Questions? See Troubleshooting or open a GitHub issue.