zalo-agent-cli 1.0.30 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.md +122 -676
  2. package/package.json +6 -3
  3. package/src/commands/auto-reply.js +83 -0
  4. package/src/commands/catalog.js +143 -0
  5. package/src/commands/conv.js +86 -0
  6. package/src/commands/label.js +39 -0
  7. package/src/commands/msg.js +47 -3
  8. package/src/commands/oa-init.js +503 -0
  9. package/src/commands/oa-listen.js +215 -0
  10. package/src/commands/oa.js +657 -0
  11. package/src/commands/profile.js +64 -0
  12. package/src/commands/quick-msg.js +55 -0
  13. package/src/core/oa-client.js +391 -0
  14. package/src/index.js +15 -4
package/README.md CHANGED
@@ -1,744 +1,190 @@
1
1
  <p align="center">
2
- <img src="assets/mascot.png" width="200" alt="zalo-agent-cli mascot" />
2
+ <img src="assets/mascot.png" width="120" alt="zalo-agent-cli mascot" />
3
3
  </p>
4
4
 
5
5
  # zalo-agent-cli
6
6
 
7
- CLI tool for Zalo automation — multi-account, proxy support, bank transfers, QR payments.
8
-
9
- Built on top of [zca-js](https://github.com/AKAspanion/zca-js), the unofficial Zalo API library for Node.js.
10
-
11
- **[Tiếng Việt](#tiếng-việt)** | **[English](#english)**
7
+ <p align="center">
8
+ <img src="assets/demo.gif" alt="zalo-agent-cli demo" />
9
+ </p>
12
10
 
13
- ---
11
+ [![npm version](https://img.shields.io/npm/v/zalo-agent-cli.svg)](https://www.npmjs.com/package/zalo-agent-cli)
12
+ [![npm downloads](https://img.shields.io/npm/dm/zalo-agent-cli.svg)](https://www.npmjs.com/package/zalo-agent-cli)
13
+ [![npm total downloads](https://img.shields.io/npm/dt/zalo-agent-cli.svg)](https://www.npmjs.com/package/zalo-agent-cli)
14
+ [![license](https://img.shields.io/npm/l/zalo-agent-cli.svg)](https://github.com/PhucMPham/zalo-agent-cli/blob/main/LICENSE)
14
15
 
15
- ## English
16
+ Công cụ CLI tự động hóa Zalo — đa tài khoản, proxy, chuyển khoản ngân hàng, thanh toán QR.
17
+ Xây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).
16
18
 
17
- ### Table of Contents
18
-
19
- - [Features](#features)
20
- - [Requirements](#requirements)
21
- - [Installation](#installation)
22
- - [Quick Start](#quick-start)
23
- - [Command Reference](#command-reference)
24
- - [Multi-Account & Proxy](#multi-account--proxy)
25
- - [Headless / VPS / CI Usage](#headless--vps--ci-usage)
26
- - [Bank Card & QR Payments](#bank-card--qr-payments)
27
- - [Security](#security)
28
- - [Disclaimer](#disclaimer)
29
- - [License](#license)
30
-
31
- ### Features
32
-
33
- - Login via QR code with auto HTTP server (PNG in browser + inline terminal image + base64 data URL)
34
- - Multi-account management with per-account dedicated proxy (1:1 mapping)
35
- - Send text, images, files, contact cards, stickers, reactions
36
- - Send bank cards (55+ Vietnamese banks)
37
- - Generate and send VietQR transfer images via qr.sepay.vn
38
- - Friend management (list, find, add, remove, block, alias, recommendations)
39
- - Group management (create, rename, members, settings, links, notes, invites)
40
- - Conversation management (mute, pin, archive, read/unread)
41
- - Export/import credentials for headless server deployment
42
- - Local HTTP server for QR display on VPS (via SSH tunnel)
43
- - `--json` output on all commands for scripting and coding agents
44
-
45
- ### Requirements
46
-
47
- - **Node.js** >= 20
48
- - **npm** (comes with Node.js)
49
-
50
- ### Installation
19
+ **[Tiếng Việt](#bắt-đầu-nhanh)** | **[English](#english)**
51
20
 
52
- ```bash
53
- npm install -g zalo-agent-cli
54
- ```
21
+ > [!WARNING]
22
+ > Tool này sử dụng API Zalo **không chính thức** ([zca-js](https://github.com/RFS-ADRENO/zca-js)). Zalo không hỗ trợ và **tài khoản của bạn có thể bị khóa hoặc ban**. Tự chịu trách nhiệm. Không liên kết với Zalo hay VNG. Xem [DISCLAIMER.md](DISCLAIMER.md).
55
23
 
56
- Or run without installing:
24
+ > [!TIP]
25
+ > **AI Agent Skill** — Dùng với OpenClaw, Claude Code, hoặc bất kỳ agent nào hỗ trợ SKILL.md:
26
+ > ```bash
27
+ > clawhub install zalo-agent # OpenClaw (từ ClawHub registry)
28
+ > cp -r skill/ ~/.claude/skills/zalo-agent/ # Claude Code
29
+ > ```
30
+ > 15+ nhóm lệnh · listen mode + webhook · 55+ ngân hàng VN · đa tài khoản + proxy
31
+ > Xem [skill/SKILL.md](skill/SKILL.md) · [Eval scenarios](skill/evals/)
57
32
 
58
- ```bash
59
- npx zalo-agent-cli login
60
- ```
33
+ ---
61
34
 
62
- Or clone and link for development:
35
+ ## Cài đặt
63
36
 
64
37
  ```bash
65
- git clone https://github.com/PhucMPham/zalo-agent-cli.git
66
- cd zalo-agent-cli
67
- npm install
68
- npm link
38
+ npm install -g zalo-agent-cli
69
39
  ```
70
40
 
71
- ### Quick Start
41
+ ## Bắt đầu nhanh
72
42
 
73
- #### 1. Login
43
+ ### 1. Đăng nhập
74
44
 
75
45
  ```bash
76
46
  zalo-agent login
77
47
  ```
78
48
 
79
- A QR code PNG will be saved and a local HTTP server starts automatically. Open the URL shown in output (e.g. `http://your-ip:18927/qr`) in your browser, then scan with **Zalo app > QR Scanner**. Credentials are auto-saved to `~/.zalo-agent-cli/`.
80
-
81
- > **Important:** Use Zalo's built-in QR scanner (not regular phone camera). The QR expires in ~60 seconds.
49
+ Quét QR bằng **Zalo app > Quét mã QR**. Thông tin tự động lưu.
82
50
 
83
- #### 2. Find a thread ID
84
-
85
- A `thread_id` is a user ID (for DMs) or group ID (for group chats). You need it for most messaging commands.
51
+ ### 2. Tìm bạn bè
86
52
 
87
53
  ```bash
88
- # Search friends by name → get their thread_id
89
54
  zalo-agent friend search "Phúc"
90
-
91
- # List recent conversations (friends + groups) with thread_id
92
- zalo-agent conv recent
93
-
94
- # List only groups
95
- zalo-agent conv recent --groups-only
96
- ```
97
-
98
- #### 3. Send a message
99
-
100
- ```bash
101
- # Send to a user (type 0, default)
102
- zalo-agent msg send <THREAD_ID> "Hello from zalo-agent!"
103
-
104
- # Send to a group (type 1)
105
- zalo-agent msg send <THREAD_ID> "Hello group!" -t 1
106
- ```
107
-
108
- #### 4. List friends
109
-
110
- ```bash
111
- zalo-agent friend list
112
- ```
113
-
114
- #### 5. Manage your profile
115
-
116
- ```bash
117
- # View your profile
118
- zalo-agent profile me
119
-
120
- # Change avatar
121
- zalo-agent profile avatar /path/to/photo.jpg
122
-
123
- # Update bio
124
- zalo-agent profile bio "Phụ tùng ô tô chính hãng"
125
-
126
- # View privacy settings
127
- zalo-agent profile settings
128
-
129
- # Update a setting (e.g. hide online status)
130
- zalo-agent profile set online-status 0
131
- ```
132
-
133
- #### 6. Check status
134
-
135
- ```bash
136
- zalo-agent status
137
- zalo-agent whoami
138
- ```
139
-
140
- ### Command Reference
141
-
142
- #### Global Flags
143
-
144
- | Flag | Description |
145
- | --------------- | -------------------------- |
146
- | `--json` | Output all results as JSON |
147
- | `-V, --version` | Show version number |
148
- | `-h, --help` | Show help |
149
-
150
- #### Auth
151
-
152
- | Command | Description |
153
- | ----------------------------------------------------- | ----------------------------------------- |
154
- | `login [--proxy URL] [--credentials PATH] [--qr-url]` | Login via QR or from exported credentials |
155
- | `logout` | Clear current session |
156
- | `status` | Show login state |
157
- | `whoami` | Show current user profile |
158
-
159
- #### Messages (`msg`)
160
-
161
- | Command | Description |
162
- | ------------------------------------------------------------------------------------------------ | ----------------------------------- |
163
- | `msg send <threadId> <text> [-t 0\|1] [--md] [--style specs...]` | Send text message (with formatting) |
164
- | `msg send-image <threadId> <paths...> [-t 0\|1] [-m caption]` | Send images |
165
- | `msg send-file <threadId> <paths...> [-t 0\|1] [-m caption]` | Send files |
166
- | `msg send-card <threadId> <userId> [-t 0\|1] [--phone NUM]` | Send contact card |
167
- | `msg send-bank <threadId> <accountNum> -b BANK [-n name] [-t 0\|1]` | Send bank card |
168
- | `msg send-qr-transfer <threadId> <accountNum> -b BANK [-a amount] [-m content] [--template tpl]` | Send VietQR transfer image |
169
- | `msg send-voice <threadId> <voiceUrl> [-t 0\|1] [--ttl ms]` | Send a voice message from URL |
170
- | `msg send-link <threadId> <url> [-m caption] [-t 0\|1]` | Send link with auto-preview |
171
- | `msg send-video <threadId> <videoUrl> --thumb <thumbUrl> [-m caption] [-d ms] [-W px] [-H px]` | Send video from URL |
172
- | `msg sticker <threadId> <keyword> [-t 0\|1]` | Search and send sticker |
173
- | `msg react <msgId> <threadId> <emoji> [-t 0\|1]` | React to a message |
174
- | `msg delete <msgId> <threadId> [-t 0\|1]` | Delete a message |
175
- | `msg forward <msgId> <threadId> [-t 0\|1]` | Forward a message |
176
-
177
- > `-t 0` = User (default), `-t 1` = Group
178
-
179
- **Text formatting with `--md` (markdown mode):**
180
-
181
- ```bash
182
- zalo-agent msg send <threadId> "**Bold** *Italic* __Underline__ ~~Strike~~ {red:Red} {big:BIG}" --md
183
- ```
184
-
185
- | Syntax | Style |
186
- | --------------- | ------------- |
187
- | `**text**` | Bold |
188
- | `*text*` | Italic |
189
- | `__text__` | Underline |
190
- | `~~text~~` | Strikethrough |
191
- | `{red:text}` | Red text |
192
- | `{orange:text}` | Orange text |
193
- | `{yellow:text}` | Yellow text |
194
- | `{green:text}` | Green text |
195
- | `{big:text}` | Large font |
196
- | `{small:text}` | Small font |
197
-
198
- **Manual style with `--style` (for agents/automation):**
199
-
200
- ```bash
201
- # Format: start:len:style — style names: bold, italic, underline, strikethrough, red, orange, yellow, green, big, small
202
- zalo-agent msg send <threadId> "Hello World" --style 0:5:bold 6:5:italic
203
55
  ```
204
56
 
205
- #### Friends (`friend`)
206
-
207
- | Command | Description |
208
- | ---------------------------------------- | ---------------------------------------------- |
209
- | `friend list` | List all friends |
210
- | `friend search <name>` | Search friends by name (get thread_id) |
211
- | `friend online` | List online friends |
212
- | `friend find <query>` | Find by phone or ID |
213
- | `friend info <userId>` | Get user profile |
214
- | `friend add <userId> [-m msg]` | Send friend request |
215
- | `friend accept <userId>` | Accept request |
216
- | `friend remove <userId>` | Remove friend |
217
- | `friend block <userId>` | Block user |
218
- | `friend unblock <userId>` | Unblock user |
219
- | `friend last-online <userId>` | Check last seen |
220
- | `friend find-username <username>` | Find user by Zalo username |
221
- | `friend alias <friendId> <alias>` | Set nickname for a friend |
222
- | `friend alias-list [-c count] [-p page]` | List all friend aliases |
223
- | `friend alias-remove <friendId>` | Remove a friend's alias |
224
- | `friend reject <userId>` | Reject a friend request |
225
- | `friend undo-request <userId>` | Cancel a sent friend request |
226
- | `friend sent-requests` | List sent friend requests |
227
- | `friend request-status <userId>` | Check friend request status |
228
- | `friend close` | List close friends |
229
- | `friend recommendations` | Get friend recommendations & received requests |
230
- | `friend find-phones <phones...>` | Find users by phone numbers |
231
-
232
- #### Groups (`group`)
233
-
234
- | Command | Description |
235
- | ---------------------------------------------------- | --------------------------------------- |
236
- | `group list` | List all groups |
237
- | `group create <name> <memberIds...>` | Create group |
238
- | `group history <groupId> [-n count]` | Get chat history (normalized JSON) |
239
- | `group info <groupId>` | Group details |
240
- | `group members <groupId>` | List members |
241
- | `group add-member <groupId> <userIds...>` | Add members |
242
- | `group remove-member <groupId> <userIds...>` | Remove members |
243
- | `group rename <groupId> <name>` | Rename |
244
- | `group upgrade-community <groupId>` | Upgrade group to Zalo Community |
245
- | `group leave <groupId>` | Leave group |
246
- | `group join <link>` | Join via invite link |
247
- | `group members-info <userIds...>` | Get detailed info for members by IDs |
248
- | `group settings <groupId> [flags]` | Update group settings (see flags below) |
249
- | `group pending <groupId>` | List pending member requests (admin) |
250
- | `group approve <groupId> <userIds...>` | Approve pending members (admin) |
251
- | `group reject-member <groupId> <userIds...>` | Reject pending members (admin) |
252
- | `group enable-link <groupId>` | Enable group invite link |
253
- | `group disable-link <groupId>` | Disable group invite link |
254
- | `group link-info <groupId>` | Get group invite link details |
255
- | `group blocked <groupId> [-c count] [-p page]` | List blocked members |
256
- | `group note-create <groupId> <title> [--pin]` | Create a note |
257
- | `group note-edit <groupId> <noteId> <title> [--pin]` | Edit a note |
258
- | `group invite-boxes` | List received group invitations |
259
- | `group join-invite <groupId>` | Accept a group invitation |
260
- | `group delete-invite <groupIds...> [--block]` | Delete invitations |
261
- | `group invite-to <userId> <groupIds...>` | Invite user to groups |
262
- | `group disperse <groupId>` | Disperse group (irreversible!) |
263
-
264
- **Group settings flags:** `--block-name`, `--sign-admin`, `--msg-history`, `--join-appr`, `--lock-post`, `--lock-poll`, `--lock-msg`, `--lock-view-member` (prefix with `--no-` to disable)
265
-
266
- #### Conversations (`conv`)
267
-
268
- | Command | Description |
269
- | --------------------------------------------------------- | ---------------------------------------- |
270
- | `conv recent [-n limit] [--friends-only] [--groups-only]` | List recent conversations with thread_id |
271
- | `conv pinned` | List pinned |
272
- | `conv archived` | List archived |
273
- | `conv mute <threadId> [-t 0\|1] [-d secs]` | Mute (-1 = forever) |
274
- | `conv unmute <threadId> [-t 0\|1]` | Unmute |
275
- | `conv read <threadId> [-t 0\|1]` | Mark as read |
276
- | `conv unread <threadId> [-t 0\|1]` | Mark as unread |
277
- | `conv delete <threadId> [-t 0\|1]` | Delete conversation |
278
-
279
- #### Profile (`profile`)
280
-
281
- | Command | Description |
282
- | ---------------------------------------------------- | --------------------------------------------- |
283
- | `profile me` | Show your profile (name, phone, avatar, etc.) |
284
- | `profile avatar <imagePath>` | Change profile avatar |
285
- | `profile bio [text]` | View or update bio/status |
286
- | `profile update [-n name] [-d YYYY-MM-DD] [-g 0\|1]` | Update name, birthday, gender |
287
- | `profile settings` | View privacy settings |
288
- | `profile set <setting> <value>` | Update a privacy setting |
289
-
290
- **Privacy settings:** `online-status`, `seen-status`, `birthday`, `receive-msg`, `accept-call`, `add-by-phone`, `add-by-qr`, `add-by-group`, `recommend`
291
-
292
- #### Polls (`poll`)
293
-
294
- | Command | Description |
295
- | ------------------------------------------------ | -------------------------------------------- |
296
- | `poll create <groupId> <question> <options...>` | Create a poll (see flags below) |
297
- | `poll info <pollId>` | View poll details and vote results |
298
- | `poll vote <pollId> <optionIds...>` | Vote on a poll (option IDs from `poll info`) |
299
- | `poll unvote <pollId>` | Remove your vote |
300
- | `poll add-option <pollId> <options...> [--vote]` | Add new options to a poll |
301
- | `poll lock <pollId>` | Close a poll (no more votes) |
302
- | `poll share <pollId>` | Share a poll |
303
-
304
- **Poll create flags:** `--multi` (multiple choices), `--add-options` (members can add options), `--anonymous` (hide voters), `--hide-preview` (hide results until voted), `--expire <minutes>` (auto-close)
305
-
306
- **Example:**
57
+ ### 3. Lắng nghe tin nhắn (lấy thread ID)
307
58
 
308
59
  ```bash
309
- # Create a multi-choice poll with 3 options, auto-close after 60 minutes
310
- zalo-agent poll create <groupId> "Chọn ngày họp" "Thứ 2" "Thứ 4" "Thứ 6" --multi --expire 60
311
-
312
- # View results
313
- zalo-agent poll info <pollId>
314
-
315
- # Vote for option IDs 123 and 456
316
- zalo-agent poll vote <pollId> 123 456
317
-
318
- # Close the poll
319
- zalo-agent poll lock <pollId>
320
- ```
321
-
322
- #### Reminders (`reminder`)
323
-
324
- | Command | Description |
325
- | ---------------------------------------------------------------------------------------------------- | --------------------------------------- |
326
- | `reminder create <threadId> <title> [-t 0\|1] [--time "YYYY-MM-DD HH:mm"] [--repeat mode] [--emoji]` | Create a reminder |
327
- | `reminder list <threadId> [-t 0\|1] [-n count]` | List reminders |
328
- | `reminder info <reminderId>` | View reminder details (group only) |
329
- | `reminder responses <reminderId>` | View who accepted/rejected (group only) |
330
- | `reminder edit <reminderId> <threadId> <title> [-t 0\|1] [--time] [--repeat] [--emoji]` | Edit a reminder |
331
- | `reminder remove <reminderId> <threadId> [-t 0\|1]` | Remove a reminder |
332
-
333
- **Repeat modes:** `none`, `daily`, `weekly`, `monthly`
334
-
335
- **Example:**
336
-
337
- ```bash
338
- # Create a daily reminder in a group at 9:00 AM tomorrow
339
- zalo-agent reminder create <groupId> "Standup meeting" -t 1 --time "2026-03-16 09:00" --repeat daily
340
-
341
- # List reminders in a group
342
- zalo-agent reminder list <groupId> -t 1
343
-
344
- # View who responded
345
- zalo-agent reminder responses <reminderId>
346
-
347
- # Edit reminder title and time
348
- zalo-agent reminder edit <reminderId> <groupId> "New title" -t 1 --time "2026-03-17 10:00"
349
-
350
- # Remove a reminder
351
- zalo-agent reminder remove <reminderId> <groupId> -t 1
352
- ```
353
-
354
- #### Accounts (`account`)
355
-
356
- | Command | Description |
357
- | ----------------------------------------------- | ------------------------------------- |
358
- | `account list` | List all registered accounts |
359
- | `account login [-p proxy] [-n name] [--qr-url]` | Login new account with optional proxy |
360
- | `account switch <ownerId>` | Switch active account |
361
- | `account remove <ownerId>` | Remove account + credentials |
362
- | `account info` | Show active account |
363
- | `account export [ownerId] [-o path]` | Export credentials for transfer |
364
-
365
- #### Listener (`listen`)
366
-
367
- ```bash
368
- # Listen for messages (default: message + friend events)
369
60
  zalo-agent listen
370
-
371
- # Filter: DM only, with webhook
372
- zalo-agent listen -f user -w https://your-n8n.com/webhook/zalo
373
-
374
- # Save messages locally as JSONL (one file per thread)
375
- zalo-agent listen --save ./zalo-logs
376
-
377
- # JSON mode for piping + save locally + webhook
378
- zalo-agent --json listen --save ./zalo-logs -w https://webhook.url
379
-
380
- # Auto-accept friend requests
381
- zalo-agent listen --auto-accept
382
- ```
383
-
384
- **Flags:** `-e` events (message,friend,group,reaction), `-f` filter (user,group,all), `-w` webhook URL, `--save <dir>` local JSONL storage, `--no-self` exclude own messages, `--auto-accept` auto-accept friend requests
385
-
386
- **JSONL storage format:** One file per thread (`<threadId>.jsonl`), each line is a JSON object with event data + `savedAt` timestamp. Useful as workaround for chat history — Zalo API only returns ~20 recent messages.
387
-
388
- ### Multi-Account & Proxy
389
-
390
- Each Zalo account can be bound to its own dedicated proxy (1:1 mapping).
391
-
392
- ```bash
393
- # Login account via residential proxy
394
- zalo-agent account login --proxy "http://user:pass@proxy:8080" --name "Shop A"
395
-
396
- # Login another account via different proxy
397
- zalo-agent account login --proxy "socks5://user:pass@proxy2:1080" --name "Shop B"
398
-
399
- # List accounts (proxy passwords are always masked)
400
- zalo-agent account list
401
- # ★ 356721... Shop A http://user:***@proxy:8080
402
- # 789012... Shop B socks5://user:***@proxy2:1080
403
-
404
- # Switch between accounts
405
- zalo-agent account switch 789012...
406
- ```
407
-
408
- **Important notes:**
409
-
410
- - Zalo enforces 1 account = 1 device (IMEI). Each QR login auto-generates a unique IMEI.
411
- - Use 1 dedicated proxy per account — sharing proxies risks both accounts being flagged.
412
- - Supported proxy protocols: `http://`, `https://`, `socks5://`
413
- - Proxy passwords are **never** displayed in output — always masked as `***`.
414
-
415
- ### Headless / VPS / CI Usage
416
-
417
- #### Option A: QR via browser (recommended)
418
-
419
- ```bash
420
- # On VPS — QR HTTP server starts automatically
421
- zalo-agent login
422
- # Output: QR available at http://your-vps-ip:18927/qr
423
-
424
- # Open the URL in your browser, scan with Zalo app > QR Scanner
425
- ```
426
-
427
- > The server auto-detects your public IP and tries ports 18927, 8080, 3000, 9000.
428
- > Make sure at least one port is open in your firewall.
429
-
430
- #### Option B: Export/import credentials
431
-
432
- ```bash
433
- # On local machine — login and export
434
- zalo-agent login
435
- zalo-agent account export --output ./creds.json
436
-
437
- # Transfer to server
438
- scp ./creds.json user@server:~/
439
-
440
- # On server — import (no QR needed)
441
- zalo-agent login --credentials ~/creds.json
442
- ```
443
-
444
- ### Bank Card & QR Payments
445
-
446
- #### Send bank card (55+ Vietnamese banks)
447
-
448
- ```bash
449
- # By bank name
450
- zalo-agent msg send-bank THREAD_ID 0123456789 --bank ocb
451
-
452
- # With holder name
453
- zalo-agent msg send-bank THREAD_ID 0123456789 --bank vietcombank --name "NGUYEN VAN A"
454
- ```
455
-
456
- #### Send VietQR transfer image
457
-
458
- ```bash
459
- # Basic QR
460
- zalo-agent msg send-qr-transfer THREAD_ID 0123456789 --bank ocb
461
-
462
- # With amount + content + template
463
- zalo-agent msg send-qr-transfer THREAD_ID 0123456789 --bank vcb \
464
- --amount 500000 --content "thanh toan don hang" --template qronly
465
- ```
466
-
467
- Templates: `compact` (VietQR frame, default), `print` (logo V), `qronly` (bare QR)
468
-
469
- Transfer content: max 50 characters (VietQR/NAPAS spec).
470
-
471
- ### Security
472
-
473
- - Credentials stored at `~/.zalo-agent-cli/credentials/` with **0600** file permissions (owner-only)
474
- - Proxy configuration stored separately from credential files
475
- - Proxy passwords **never** shown in CLI output — always masked
476
- - QR HTTP server binds to `127.0.0.1` only (not externally accessible)
477
- - Exported credential files created with **0600** permissions + security warning
478
-
479
- #### Storage layout
480
-
481
- ```
482
- ~/.zalo-agent-cli/
483
- ├── accounts.json # Account registry (ownId, name, proxy, active)
484
- ├── credentials/
485
- │ ├── cred_<ownId1>.json # Per-account credentials (0600)
486
- │ └── cred_<ownId2>.json
487
- └── qr.png # Last generated QR code
488
- ```
489
-
490
- ### Disclaimer
491
-
492
- > ⚠️ **Warning:** This tool uses [zca-js](https://github.com/AKAspanion/zca-js), an **unofficial** Zalo API library. Zalo does not support this and **your account may be banned**. Use at your own risk.
493
-
494
- This is an **unofficial** project and is **not affiliated with, endorsed by, or connected to Zalo or VNG Corporation**. See [DISCLAIMER.md](DISCLAIMER.md) for full details.
495
-
496
- ### License
497
-
498
- [MIT](LICENSE)
499
-
500
- ---
501
-
502
- ## Tiếng Việt
503
-
504
- ### Mục lục
505
-
506
- - [Tính năng](#tính-năng)
507
- - [Yêu cầu](#yêu-cầu)
508
- - [Cài đặt](#cài-đặt)
509
- - [Bắt đầu nhanh](#bắt-đầu-nhanh)
510
- - [Danh sách lệnh](#danh-sách-lệnh)
511
- - [Đa tài khoản & Proxy](#đa-tài-khoản--proxy)
512
- - [Sử dụng trên VPS / Headless / CI](#sử-dụng-trên-vps--headless--ci)
513
- - [Thẻ ngân hàng & Thanh toán QR](#thẻ-ngân-hàng--thanh-toán-qr)
514
- - [Bảo mật](#bảo-mật)
515
- - [Tuyên bố miễn trừ](#tuyên-bố-miễn-trừ)
516
-
517
- ### Tính năng
518
-
519
- - Đăng nhập bằng mã QR qua HTTP server tự động (PNG trên browser + inline terminal + base64)
520
- - Quản lý đa tài khoản với proxy riêng biệt cho từng tài khoản (1:1)
521
- - Gửi tin nhắn, hình ảnh, file, danh thiếp, sticker, reaction
522
- - Gửi thẻ ngân hàng (55+ ngân hàng Việt Nam)
523
- - Tạo và gửi ảnh QR chuyển khoản qua qr.sepay.vn
524
- - Quản lý bạn bè (danh sách, tìm kiếm, thêm, xóa, chặn, biệt danh, gợi ý)
525
- - Quản lý nhóm (tạo, đổi tên, thành viên, cài đặt, link, ghi chú, lời mời)
526
- - Quản lý hội thoại (tắt thông báo, ghim, lưu trữ)
527
- - Xuất/nhập credentials cho triển khai trên server
528
- - HTTP server local hiển thị QR cho VPS (qua SSH tunnel)
529
- - Output `--json` cho mọi lệnh, phục vụ scripting và coding agent
530
-
531
- ### Yêu cầu
532
-
533
- - **Node.js** >= 20
534
- - **npm** (đi kèm Node.js)
535
-
536
- ### Cài đặt
537
-
538
- ```bash
539
- npm install -g zalo-agent-cli
540
- ```
541
-
542
- Hoặc chạy không cần cài:
543
-
544
- ```bash
545
- npx zalo-agent-cli login
546
- ```
547
-
548
- Hoặc clone để phát triển:
549
-
550
- ```bash
551
- git clone https://github.com/PhucMPham/zalo-agent-cli.git
552
- cd zalo-agent-cli
553
- npm install
554
- npm link
555
- ```
556
-
557
- ### Bắt đầu nhanh
558
-
559
- #### 1. Đăng nhập
560
-
561
- ```bash
562
- zalo-agent login
563
61
  ```
564
62
 
565
- HTTP server tự khởi động và hiện URL (ví dụ `http://ip:18927/qr`). Mở URL trên trình duyệt, quét bằng **Zalo app > Quét mã QR** (không dùng camera thường). Thông tin đăng nhập tự động lưu tại `~/.zalo-agent-cli/`.
566
-
567
- #### 2. Tìm thread ID
568
-
569
- `thread_id` là ID của người dùng (tin nhắn riêng) hoặc ID nhóm (nhóm chat). Bạn cần nó cho hầu hết các lệnh gửi tin.
63
+ Mỗi tin nhắn đến sẽ hiện `threadId`. Dùng `--json` để lấy dạng JSON.
570
64
 
571
- ```bash
572
- # Tìm bạn bè theo tên → lấy thread_id
573
- zalo-agent friend search "Phúc"
574
-
575
- # Xem danh sách hội thoại gần đây (bạn bè + nhóm) kèm thread_id
576
- zalo-agent conv recent
577
-
578
- # Chỉ xem nhóm
579
- zalo-agent conv recent --groups-only
580
- ```
581
-
582
- #### 3. Gửi tin nhắn
65
+ ### 4. Gửi tin nhắn
583
66
 
584
67
  ```bash
585
- # Gửi cho cá nhân (type 0, mặc định)
68
+ # Gửi cho cá nhân
586
69
  zalo-agent msg send <THREAD_ID> "Xin chào!"
587
70
 
588
- # Gửi vào nhóm (type 1)
71
+ # Gửi vào nhóm
589
72
  zalo-agent msg send <THREAD_ID> "Xin chào nhóm!" -t 1
590
73
  ```
591
74
 
592
- #### 4. Xem danh sách bạn bè
593
-
594
- ```bash
595
- zalo-agent friend list
596
- ```
597
-
598
- #### 5. Quản lý hồ sơ cá nhân
599
-
600
- ```bash
601
- # Xem hồ sơ
602
- zalo-agent profile me
603
-
604
- # Đổi ảnh đại diện
605
- zalo-agent profile avatar /đường/dẫn/ảnh.jpg
606
-
607
- # Cập nhật tiểu sử
608
- zalo-agent profile bio "Phụ tùng ô tô chính hãng"
609
-
610
- # Xem cài đặt quyền riêng tư
611
- zalo-agent profile settings
612
-
613
- # Thay đổi cài đặt (VD: ẩn trạng thái online)
614
- zalo-agent profile set online-status 0
615
- ```
616
-
617
- #### 6. Tạo khảo sát (Poll) trong nhóm
618
-
619
- ```bash
620
- # Tạo poll multi-choice, tự đóng sau 60 phút
621
- zalo-agent poll create <groupId> "Chọn ngày họp" "Thứ 2" "Thứ 4" "Thứ 6" --multi --expire 60
622
-
623
- # Xem kết quả
624
- zalo-agent poll info <pollId>
625
-
626
- # Bỏ phiếu (dùng option ID từ poll info)
627
- zalo-agent poll vote <pollId> 123 456
628
-
629
- # Đóng poll
630
- zalo-agent poll lock <pollId>
631
- ```
632
-
633
- #### 7. Nhắc nhở (Reminder)
634
-
635
- ```bash
636
- # Tạo nhắc nhở hàng ngày trong nhóm lúc 9h sáng
637
- zalo-agent reminder create <groupId> "Họp standup" -t 1 --time "2026-03-16 09:00" --repeat daily
638
-
639
- # Xem danh sách nhắc nhở
640
- zalo-agent reminder list <groupId> -t 1
641
-
642
- # Xem ai đã chấp nhận/từ chối
643
- zalo-agent reminder responses <reminderId>
644
-
645
- # Sửa nhắc nhở
646
- zalo-agent reminder edit <reminderId> <groupId> "Tiêu đề mới" -t 1 --time "2026-03-17 10:00"
647
-
648
- # Xóa nhắc nhở
649
- zalo-agent reminder remove <reminderId> <groupId> -t 1
650
- ```
651
-
652
- Chế độ lặp: `none` (không lặp), `daily` (hàng ngày), `weekly` (hàng tuần), `monthly` (hàng tháng)
653
-
654
- ### Danh sách lệnh
655
-
656
- Xem đầy đủ tại [phần tiếng Anh](#command-reference) phía trên. Tất cả lệnh đều giống nhau.
657
-
658
- ### Đa tài khoản & Proxy
659
-
660
- Mỗi tài khoản Zalo có thể gắn với 1 proxy riêng biệt.
661
-
662
- ```bash
663
- # Đăng nhập qua proxy
664
- zalo-agent account login --proxy "http://user:pass@proxy:8080" --name "Shop A"
665
-
666
- # Xem danh sách (mật khẩu proxy luôn bị ẩn)
667
- zalo-agent account list
668
-
669
- # Chuyển tài khoản
670
- zalo-agent account switch <ID>
671
- ```
75
+ ---
672
76
 
673
- **Lưu ý quan trọng:**
77
+ ## Danh sách lệnh
78
+
79
+ Tất cả lệnh hỗ trợ `--json`. Tài liệu đầy đủ: **[Wiki](https://github.com/PhucMPham/zalo-agent-cli/wiki)**
80
+
81
+ | Nhóm lệnh | Mô tả | Docs |
82
+ |------------|--------|------|
83
+ | `msg` | Gửi tin nhắn, hình, file, voice, video, sticker, link, thẻ chuyển khoản, QR | [Tin nhắn](https://github.com/PhucMPham/zalo-agent-cli/wiki/Tin-Nh%E1%BA%AFn) |
84
+ | `friend` | Danh sách, tìm, thêm, xóa, chặn, biệt danh, gợi ý | [Bạn bè](https://github.com/PhucMPham/zalo-agent-cli/wiki/B%E1%BA%A1n-B%C3%A8) |
85
+ | `group` | Tạo, đổi tên, thành viên, cài đặt, link, ghi chú, lời mời | [Nhóm & Cộng đồng](https://github.com/PhucMPham/zalo-agent-cli/wiki/Nh%C3%B3m) |
86
+ | `conv` | Tắt thông báo, ghim, lưu trữ, ẩn hội thoại, tự xóa | [Hội thoại](https://github.com/PhucMPham/zalo-agent-cli/wiki/H%E1%BB%99i-Tho%E1%BA%A1i) |
87
+ | `profile` | Xem/cập nhật hồ sơ, ảnh đại diện, quyền riêng tư | [Hồ sơ](https://github.com/PhucMPham/zalo-agent-cli/wiki/H%E1%BB%93-S%C6%A1) |
88
+ | `poll` | Tạo, bỏ phiếu, đóng khảo sát | [Khảo sát](https://github.com/PhucMPham/zalo-agent-cli/wiki/Kh%E1%BA%A3o-S%C3%A1t) |
89
+ | `reminder` | Tạo, sửa, xóa nhắc nhở | [Nhắc nhở](https://github.com/PhucMPham/zalo-agent-cli/wiki/Nh%E1%BA%AFc-Nh%E1%BB%9F) |
90
+ | `auto-reply` | Quản lý trả lời tự động | [Trả lời tự động](https://github.com/PhucMPham/zalo-agent-cli/wiki/Tr%E1%BA%A3-L%E1%BB%9Di-T%E1%BB%B1-%C4%90%E1%BB%99ng) |
91
+ | `quick-msg` | Tin nhắn nhanh đã lưu | [Tin nhắn nhanh](https://github.com/PhucMPham/zalo-agent-cli/wiki/Tin-Nh%E1%BA%AFn-Nhanh) |
92
+ | `label` | Nhãn hội thoại | [Nhãn](https://github.com/PhucMPham/zalo-agent-cli/wiki/Nh%C3%A3n) |
93
+ | `catalog` | zBusiness — danh mục sản phẩm | [zBusiness](https://github.com/PhucMPham/zalo-agent-cli/wiki/zBusiness) |
94
+ | `listen` | Lắng nghe tin nhắn real-time, webhook, lưu JSONL | [Lắng nghe](https://github.com/PhucMPham/zalo-agent-cli/wiki/L%E1%BA%AFng-Nghe) |
95
+ | `account` | Đa tài khoản & proxy | [Tài khoản](https://github.com/PhucMPham/zalo-agent-cli/wiki/T%C3%A0i-Kho%E1%BA%A3n) |
96
+ | **`oa`** | **Zalo Official Account API v3.0 — OAuth, tin nhắn, follower, tag, webhook** | **[Official Account](https://github.com/PhucMPham/zalo-agent-cli/wiki/Official-Account)** |
97
+
98
+ Xem thêm: [Đa tài khoản & Proxy](https://github.com/PhucMPham/zalo-agent-cli/wiki/%C4%90a-T%C3%A0i-Kho%E1%BA%A3n-&-Proxy) · [Cài đặt VPS](https://github.com/PhucMPham/zalo-agent-cli/wiki/C%C3%A0i-%C4%90%E1%BA%B7t-VPS) · [Thẻ chuyển khoản & QR](https://github.com/PhucMPham/zalo-agent-cli/wiki/Th%E1%BA%BB-Chuy%E1%BB%83n-Kho%E1%BA%A3n-&-QR) · [Official Account](https://github.com/PhucMPham/zalo-agent-cli/wiki/Official-Account)
674
99
 
675
- - Zalo giới hạn 1 tài khoản = 1 thiết bị (IMEI). Mỗi lần quét QR tự tạo IMEI mới.
676
- - Dùng 1 proxy riêng cho mỗi tài khoản — dùng chung proxy có nguy cơ bị khóa cả 2.
677
- - Hỗ trợ: `http://`, `https://`, `socks5://`
678
- - Mật khẩu proxy **không bao giờ** hiển thị — luôn bị ẩn thành `***`.
100
+ ---
679
101
 
680
- ### Sử dụng trên VPS / Headless / CI
102
+ ## Tính năng
681
103
 
682
- #### Cách A: QR qua trình duyệt (khuyến nghị)
104
+ - Đăng nhập QR qua HTTP server tự động (browser + terminal)
105
+ - Đa tài khoản với proxy riêng biệt (1:1)
106
+ - 90+ lệnh phủ hết tính năng Zalo
107
+ - **Zalo Official Account (OA) API v3.0** — OAuth login, gửi tin nhắn, quản lý follower, webhook listener
108
+ - Thẻ chuyển khoản (55+ ngân hàng VN) & QR VietQR
109
+ - Lắng nghe real-time với webhook & lưu JSONL local
110
+ - Output `--json` cho mọi lệnh — scripting & AI agents
111
+ - Credentials mã hóa tại chỗ (quyền 0600)
112
+ - **Dual mode**: interactive (human) + non-interactive (AI agents, CI/CD)
683
113
 
684
- ```bash
685
- # Trên VPS — HTTP server tự động khởi động
686
- zalo-agent login
687
- # Output: QR available at http://ip-vps:18927/qr
114
+ ---
688
115
 
689
- # Mở URL trên trình duyệt, quét bằng Zalo app > Quét mã QR
690
- ```
116
+ ## Ủng hộ
691
117
 
692
- > Server tự detect IP public và thử port 18927, 8080, 3000, 9000.
693
- > Đảm bảo ít nhất 1 port mở trong firewall.
118
+ Nếu tool này giúp bạn tiết kiệm thời gian, hãy mua cho chúng tôi một ly cà phê!
694
119
 
695
- #### Cách B: Xuất/nhập credentials
120
+ <p align="center">
121
+ <img src="assets/donate-qr.jpg" width="280" alt="Donate qua VietQR (OCB)" />
122
+ <br/>
123
+ <em>Quét bằng app ngân hàng bất kỳ</em>
124
+ </p>
696
125
 
697
- ```bash
698
- # Trên máy local
699
- zalo-agent login
700
- zalo-agent account export --output ./creds.json
126
+ ---
701
127
 
702
- # Chuyển sang server
703
- scp ./creds.json user@server:~/
128
+ ## English
704
129
 
705
- # Trên server (không cần QR)
706
- zalo-agent login --credentials ~/creds.json
707
- ```
130
+ CLI tool for Zalo automation — multi-account, proxy support, bank transfers, QR payments.
708
131
 
709
- ### Thẻ ngân hàng & Thanh toán QR
132
+ > [!TIP]
133
+ > **AI Agent Skill** — Use with OpenClaw, Claude Code, or any SKILL.md-compatible agent:
134
+ > ```bash
135
+ > clawhub install zalo-agent # OpenClaw (from ClawHub registry)
136
+ > cp -r skill/ ~/.claude/skills/zalo-agent/ # Claude Code
137
+ > ```
138
+ > 15+ command groups · listen mode + webhook · 55+ VN banks · multi-account + proxy
139
+ > See [skill/SKILL.md](skill/SKILL.md) · [Eval scenarios](skill/evals/)
710
140
 
711
- #### Gửi thẻ ngân hàng (55+ ngân hàng VN)
141
+ ### Quick Start
712
142
 
713
143
  ```bash
714
- zalo-agent msg send-bank THREAD_ID 0123456789 --bank ocb
715
- zalo-agent msg send-bank THREAD_ID 0123456789 --bank vietcombank --name "NGUYEN VAN A"
144
+ npm install -g zalo-agent-cli
145
+ zalo-agent login # 1. Login via QR
146
+ zalo-agent friend search "Name" # 2. Find a friend
147
+ zalo-agent listen # 3. Listen for threadId
148
+ zalo-agent msg send <THREAD_ID> "Hello!" # 4. Send a message
716
149
  ```
717
150
 
718
- #### Gửi QR chuyển khoản VietQR
151
+ ### Commands
719
152
 
720
- ```bash
721
- zalo-agent msg send-qr-transfer THREAD_ID 0123456789 --bank vcb \
722
- --amount 500000 --content "thanh toan" --template qronly
723
- ```
153
+ Full docs: **[Wiki](https://github.com/PhucMPham/zalo-agent-cli/wiki)**
724
154
 
725
- Template: `compact` (khung VietQR), `print` (logo V), `qronly` (chỉ mã QR)
155
+ | Group | Description | Docs |
156
+ |-------|-------------|------|
157
+ | `msg` | Text, images, files, voice, video, stickers, links, bank cards, QR | [Messages](https://github.com/PhucMPham/zalo-agent-cli/wiki/Messages) |
158
+ | `friend` | List, find, add, remove, block, alias, recommendations | [Friends](https://github.com/PhucMPham/zalo-agent-cli/wiki/Friends) |
159
+ | `group` | Create, rename, members, settings, links, notes, invites | [Groups](https://github.com/PhucMPham/zalo-agent-cli/wiki/Groups) |
160
+ | `conv` | Mute, pin, archive, hidden, auto-delete | [Conversations](https://github.com/PhucMPham/zalo-agent-cli/wiki/Conversations) |
161
+ | `profile` | Profile, avatar gallery, privacy | [Profile](https://github.com/PhucMPham/zalo-agent-cli/wiki/Profile) |
162
+ | `poll` | Create, vote, lock polls | [Polls](https://github.com/PhucMPham/zalo-agent-cli/wiki/Polls) |
163
+ | `reminder` | Create, edit, remove reminders | [Reminders](https://github.com/PhucMPham/zalo-agent-cli/wiki/Reminders) |
164
+ | `auto-reply` | Auto-reply rules | [Auto-Reply](https://github.com/PhucMPham/zalo-agent-cli/wiki/Auto-Reply) |
165
+ | `quick-msg` | Saved quick messages | [Quick Messages](https://github.com/PhucMPham/zalo-agent-cli/wiki/Quick-Messages) |
166
+ | `label` | Conversation labels | [Labels](https://github.com/PhucMPham/zalo-agent-cli/wiki/Labels) |
167
+ | `catalog` | zBusiness catalogs & products | [Catalog](https://github.com/PhucMPham/zalo-agent-cli/wiki/Catalog) |
168
+ | `listen` | Real-time listener, webhook, JSONL | [Listener](https://github.com/PhucMPham/zalo-agent-cli/wiki/Listener) |
169
+ | `account` | Multi-account & proxy | [Accounts](https://github.com/PhucMPham/zalo-agent-cli/wiki/Accounts) |
170
+ | **`oa`** | **Zalo Official Account API v3.0 — OAuth, messaging, followers, webhook** | **[Official Account](https://github.com/PhucMPham/zalo-agent-cli/wiki/Official-Account)** |
726
171
 
727
- Nội dung chuyển khoản: tối đa 50 ký tự (theo chuẩn VietQR/NAPAS).
172
+ ### Support Us
728
173
 
729
- ### Bảo mật
174
+ If this tool saves you time, consider buying us a coffee!
730
175
 
731
- - Credentials lưu tại `~/.zalo-agent-cli/credentials/` với quyền **0600** (chỉ chủ sở hữu đọc được)
732
- - Cấu hình proxy lưu riêng, không nằm trong file credentials
733
- - Mật khẩu proxy **không bao giờ** hiển thị — luôn bị ẩn
734
- - HTTP server QR chỉ lắng nghe `127.0.0.1` (không truy cập từ bên ngoài)
176
+ <p align="center">
177
+ <img src="assets/donate-qr.jpg" width="280" alt="Donate via VietQR (OCB)" />
178
+ <br/>
179
+ <em>Scan with any Vietnamese banking app</em>
180
+ </p>
735
181
 
736
- ### Tuyên bố miễn trừ
182
+ ---
737
183
 
738
- > ⚠️ **Cảnh báo:** Tool này sử dụng [zca-js](https://github.com/AKAspanion/zca-js) — thư viện gọi API Zalo **không chính thức**. Zalo không hỗ trợ và **tài khoản của bạn có thể bị khóa (ban)**. Dùng trên tinh thần tự chịu trách nhiệm.
184
+ ## Star History
739
185
 
740
- Đây là dự án **không chính thức** và **không liên kết với Zalo hay Tập đoàn VNG**. Xem [DISCLAIMER.md](DISCLAIMER.md) để biết chi tiết.
186
+ [![Star History Chart](https://api.star-history.com/svg?repos=PhucMPham/zalo-agent-cli&type=Date)](https://star-history.com/#PhucMPham/zalo-agent-cli&Date)
741
187
 
742
- ### Giấy phép
188
+ ## License
743
189
 
744
- [MIT](LICENSE)
190
+ [MIT](LICENSE) · See [DISCLAIMER.md](DISCLAIMER.md) for full terms.