mirror of
https://github.com/hanzoai/bot.git
synced 2026-11-02 20:15:14 +00:00
zooqueen
adb8e1f802
Squash merge of 1,462 upstream commits with openclaw→hanzo-bot naming transforms applied. Conflicts resolved favoring our main branch to preserve existing customizations. Key upstream additions: - iOS Security Stack (concurrency locks, runtime guards, TTS fallback) - Discord CDN hostname allowlisting for SSRF protection - Discord mention handling improvements - Various bug fixes and stability improvements
4.1 KiB
4.1 KiB
@bot/zalouser
Hanzo Bot extension for Zalo Personal Account messaging via zca-cli.
Warning: Using Zalo automation may result in account suspension or ban. Use at your own risk. This is an unofficial integration.
Features
- Channel plugin integration with onboarding + QR login
- In-process listener/sender via
zca-js(no external CLI) - Multi-account support
- Agent tool integration (
zalouser) - DM/group policy support
Prerequisites
- Bot Gateway
- Zalo mobile app (for QR login)
No external zca, openzca, or zca-cli binary is required.
Install
Option A: npm
bot plugins install @bot/zalouser
Option B: local source checkout
bot plugins install ./extensions/zalouser
cd ./extensions/zalouser && pnpm install
Restart the Gateway after install.
Quick start
Login (QR)
hanzo-bot onboard
# Select "Zalo Personal" from channel list
# Follow QR code login flow
Scan the QR code with the Zalo app on your phone.
hanzo-bot channels login --channel zalouser
# Scan QR code with Zalo app
Send a Message
hanzo-bot message send --channel zalouser --target <threadId> --message "Hello from Hanzo Bot!"
Configuration
After onboarding, your config will include:
channels:
zalouser:
enabled: true
dmPolicy: pairing # pairing | allowlist | open | disabled
Send a message
bot message send --channel zalouser --target <threadId> --message "Hello from Bot"
Configuration
Basic:
channels:
zalouser:
enabled: true
dmPolicy: pairing
Multi-account:
channels:
zalouser:
enabled: true
defaultAccount: default
accounts:
default:
enabled: true
profile: default
work:
enabled: true
profile: work
Useful commands
hanzo-bot channels login --channel zalouser # Login via QR
hanzo-bot channels login --channel zalouser --account work
hanzo-bot channels status --probe
hanzo-bot channels logout --channel zalouser
Agent tool
hanzo-bot directory self --channel zalouser
hanzo-bot directory peers list --channel zalouser --query "name"
hanzo-bot directory groups list --channel zalouser --query "work"
hanzo-bot directory groups members --channel zalouser --group-id <id>
Account Management
zca account list # List all profiles
zca account current # Show active profile
zca account switch <profile>
zca account remove <profile>
zca account label <profile> "Work Account"
Messaging
# Text
hanzo-bot message send --channel zalouser --target <threadId> --message "message"
# Media (URL)
hanzo-bot message send --channel zalouser --target <threadId> --message "caption" --media-url "https://example.com/img.jpg"
Listener
The listener runs inside the Gateway when the channel is enabled. For debugging,
use hanzo-bot channels logs --channel zalouser or run zca listen directly.
Data Access
# Friends
zca friend list
zca friend list -j # JSON output
zca friend find "name"
zca friend online
# Groups
zca group list
zca group info <groupId>
zca group members <groupId>
# Profile
zca me info
zca me id
Multi-Account Support
Use --profile or -p to work with multiple accounts:
hanzo-bot channels login --channel zalouser --account work
hanzo-bot message send --channel zalouser --account work --target <id> --message "Hello"
ZCA_PROFILE=work zca listen
Profile resolution order: --profile flag > ZCA_PROFILE env > default
Agent Tool
The extension registers a zalouser tool for AI agents:
{
"action": "send",
"threadId": "123456",
"message": "Hello from AI!",
"isGroup": false,
"profile": "default"
}
Available actions: send, image, link, friends, groups, me, status
Troubleshooting
- Login not persisted:
bot channels logout --channel zalouser && bot channels login --channel zalouser - Probe status:
bot channels status --probe - Name resolution issues (allowlist/groups): use numeric IDs or exact Zalo names
Credits
Built on zca-js.