Quick Overview

Watch a 14-second introduction to all the features and commands available in zca-cli.

Quick Overview

Watch a 14-second introduction to all the features and commands available in zca-cli.

What's New

Latest updates and improvements in zca-cli.

v0.0.30March 2026

Release Highlights

v0.0.30

Alias Support & Pagination Fix

Friend aliases now stored in contacts cache and shown in listener output. Paginated alias fetching — users with 100+ aliases no longer lose data. Fixed 'zca listen' overwriting alias cache on reconnect.

2026-03-02

v0.0.29

Security & Stability Hardening

17 edge-case fixes across the codebase: reconnect guard prevents duplicate timers, atomic event cache consume, SSRF redirect validation with max-hop protection, sendMessage timeout wrappers, profile-scoped contacts cache, idempotent one-time job cleanup, cron DOW=7 Sunday fix, ReDoS input truncation, stale PID lock detection, and more.

2026-03-01

v0.0.28

Background Daemon & Event Caching

Never miss a message — background daemon auto-starts after any command, caching up to 5,000 events to disk. When 'zca listen' starts, it replays all cached events you missed while offline.

2026-03-01

v0.0.27

Process Stability

Fixed one-shot commands (msg send, friend list, etc.) hanging after completion. Improved process exit handling.

2026-03-01

v0.0.26

Core Library Patch (zca-js 2.1.1)

Upgraded zca-js from 2.1.0 to 2.1.1 with bug fixes and stability patches. Cleaned up deprecated packages.

2026-02-25

Getting Started

Learn how to install and set up zca-cli for Zalo automation in minutes.

Requirements

Node.js 18 or higher
npm, pnpm, or yarn package manager
A valid zca-cli license (for full functionality)
A Zalo account

Installation

Install zca-cli globally using your preferred package manager:

terminal

# Using terminal
$ curl -fsSL get.zca-cli.dev/install.sh | bash
.
#or Using PowerShell
$ irm get.zca-cli.dev/install.ps1 | iex
.

After installation, verify it works by running:

$ zca --version

Quick Start

Follow these steps to start using zca-cli:

Step 1: Activate your license

First, get your device support code and activate your license:

# Get your device support code
$ zca license support-code
.
# Activate with your license key
$ zca license activate "YOUR_LICENSE_KEY"

Step 2: Login with QR code

$ zca auth login

Open your Zalo app and scan the QR code displayed in the terminal.

Step 3: Send your first message

Send a message to any user or group:

# Send to a user
$ zca msg send USER_ID "Hello from zca-cli!"
.
# Send to a group
$ zca msg send GROUP_ID "Hello team!" --group

Command Structure

zca-cli uses a hierarchical command structure:

$ zca [--profile <name>] <command-group> <command> [arguments] [options]

Command Groups

auth

Authentication

msg

Messaging

group

Group management

friend

Friend management

me

Profile/account

account

Multi-account

listen

Real-time events

license

License management

Getting Help

Use the --help flag to see available commands:

# General help
$ zca --help
.
# Help for a command group
$ zca msg --help
.
# Help for a specific command
$ zca msg send --help

Authentication

Manage your Zalo authentication with QR code login, credentials, and session management.

Overview

zca-cli stores your authentication credentials securely on your device. Once logged in, you can use any command without re-authenticating. Credentials are stored per profile, allowing you to manage multiple Zalo accounts.

Commands

zca auth login

Usage

$ zca auth login [options]

Options

Flag	Description	Default
-q, --qr-path <path>	Save the QR code to a file	—

Examples

$ zca auth login

Save QR code to a file

$ zca auth login --qr-path ./qr.png

zca auth login-creds

Usage

$ zca auth login-creds

Examples

Re-authenticate with saved credentials

$ zca auth login-creds

zca auth logout

Logout and clear all saved credentials for the current profile.

Usage

$ zca auth logout

Examples

Logout from current profile

$ zca auth logout

zca auth status

Check authentication status and validate credentials.

Usage

$ zca auth status

Examples

Check current login status

$ zca auth status

zca auth cache-refresh

Refresh the contacts cache (friends and groups). Useful after adding new contacts.

Usage

$ zca auth cache-refresh

Examples

Refresh contacts cache

$ zca auth cache-refresh

zca auth cache-info

Show information about the cached contacts.

Usage

$ zca auth cache-info

Examples

Show cache information

$ zca auth cache-info

zca auth cache-clear

Clear the contacts cache.

Usage

$ zca auth cache-clear

Examples

Clear all cached contacts

$ zca auth cache-clear

Tips

Session Persistence

After logging in with zca auth login, your session is saved. Use zca auth login-creds to re-authenticate without scanning the QR again.

Expired Credentials

If you see "Credentials may be expired", run zca auth login to get a fresh session.

Config Location

Run zca auth status to see where your config is stored.

Messaging

Send text, images, videos, voice messages, stickers, and more to users or groups.

Important

All messaging commands accept a -g, --group flag to send to groups instead of users. Without this flag, messages are sent to individual users.

Commands

zca msg send

Send a text message to a user or group.

Usage

$ zca msg send <threadId> <message> [options]

Options

Flag	Description	Default
-g, --group	Send to a group instead of a user	—
-q, --quote <json>	Quote/reply to a message (JSON with msgId, cliMsgId, uidFrom, ts)	—
-m, --mention <spec...>	Mention user(s): uid:pos:len (repeatable)	—
-s, --style <spec...>	Text style(s): start:len:type (types: b,i,u,s,c_db342e,f_13,f_18)	—
--urgency <level>	Urgency: 0=default, 1=important, 2=urgent	—
--ttl <ms>	Auto-delete timer in milliseconds	—
-a, --attachment <files...>	Attach file(s) to the message	—

Examples

Send to a user

$ zca msg send 123456789 "Hello!"

Send to a group

$ zca msg send 987654321 "Hello team!" --group

Reply to a message

$ zca msg send 123456789 "reply text" --quote '{"msgId":"123","cliMsgId":"456","uidFrom":"789","ts":1700000000}'

Mention user in group

$ zca msg send 987654321 "@Alice hello" -g --mention "alice_uid:0:6"

Bold text with urgent priority

$ zca msg send 123456789 "IMPORTANT" --style "0:9:b" --urgency 1

Auto-delete after 5 minutes

$ zca msg send 123456789 "secret" --ttl 300000

zca msg image

Send an image from a local file or URL.

Usage

$ zca msg image <threadId> [file] [options]

Options

Flag	Description	Default
-g, --group	Send to a group instead of a user	—
-u, --url <urls...>	Send image from URL(s)	—
-m, --message <text>	Add a caption to the image	—

Examples

Send local image file

$ zca msg image 123456789 ./photo.jpg

Send image from URL

$ zca msg image 123456789 -u "https://example.com/img.png"

Send image with caption

$ zca msg image 123456789 ./photo.jpg -m "Check this out!"

zca msg video

Send a video from a local file or URL.

Usage

$ zca msg video <threadId> [file] [options]

Options

Flag	Description	Default
-g, --group	Send to a group instead of a user	—
-u, --url <urls...>	Send video from URL(s)	—
-t, --thumbnail <url>	Custom thumbnail URL	—

Examples

Send local video file

$ zca msg video 123456789 ./video.mp4

Send video from URL

$ zca msg video 123456789 -u "https://example.com/video.mp4"

zca msg voice

Send a voice message from a local file or URL.

Usage

$ zca msg voice <threadId> [file] [options]

Options

Flag	Description	Default
-g, --group	Send to a group instead of a user	—
-u, --url <urls...>	Send voice from URL(s)	—

Examples

Send local audio file

$ zca msg voice 123456789 ./audio.mp3

Send voice from URL

$ zca msg voice 123456789 -u "https://example.com/voice.mp3"

zca msg sticker

Send a sticker by ID.

Usage

$ zca msg sticker <threadId> <stickerId> [options]

Options

Flag	Description	Default
-g, --group	Send to a group instead of a user	—

Examples

Send a sticker

$ zca msg sticker 123456789 12345

zca msg link

Share a URL link.

Usage

$ zca msg link <threadId> <url> [options]

Options

Flag	Description	Default
-g, --group	Send to a group instead of a user	—

Examples

Share a link

$ zca msg link 123456789 "https://github.com/user/repo"

zca msg card

Send a contact card (share a user's profile).

Usage

$ zca msg card <threadId> <contactId> [options]

Options

Flag	Description	Default
-g, --group	Send to a group instead of a user	—

Examples

Share a contact card

$ zca msg card 123456789 987654321

zca msg react

Add a reaction to a message.

Usage

$ zca msg react <msgId> <cliMsgId> <threadId> <reaction> [options]

Options

Flag	Description	Default
-g, --group	React in a group conversation	—

Examples

Add a reaction

$ zca msg react msg123 cli123 123456789 "❤️"

zca msg typing

Send a typing indicator.

Usage

$ zca msg typing <threadId> [options]

Options

Flag	Description	Default
-g, --group	Show typing in a group	—

Examples

Show typing indicator

$ zca msg typing 123456789

zca msg forward

Forward a message to multiple threads.

Usage

$ zca msg forward <message> <targets...> [options]

Options

Flag	Description	Default
-g, --group	Forward to groups	—

Examples

Forward to multiple users

$ zca msg forward "Important update" 123 456 789

zca msg delete

Delete a message.

Usage

$ zca msg delete <msgId> <cliMsgId> <uidFrom> <threadId> [options]

Options

Flag	Description	Default
-g, --group	Delete in a group conversation	—
-m, --only-me	Delete only for yourself	—

zca msg undo

Recall (unsend) a message.

Usage

$ zca msg undo <msgId> <cliMsgId> <threadId> [options]

Options

Flag	Description	Default
-g, --group	Recall in a group conversation	—

zca msg upload

Upload an attachment and get the URL.

Usage

$ zca msg upload [file] <threadId> [options]

Options

Flag	Description	Default
-g, --group	Upload for a group conversation	—
-u, --url <urls...>	Upload from URL(s)	—

zca msg bank-card

Send a bank card/payment info

Usage

$ zca msg bank-card <threadId> <bankBin> <accountNumber> [options]

Options

Flag	Description	Default
-n, --name <name>	Account holder name	—
-g, --group	Send to group	—

Examples

Send bank card (970418 = BIDV)

$ zca msg bank-card 123456789 970418 "1234567890" -n "John Doe"

zca msg seen

Mark message(s) as seen

Usage

$ zca msg seen <json> [options]

Options

Flag	Description	Default
-g, --group	Message is in a group	—

Examples

Mark message as seen (JSON params)

$ zca msg seen '{"msgId":"123","cliMsgId":"456",...}' -g

Use JSON file with @ prefix

$ zca msg seen @params.json

zca msg delivered

Mark message(s) as delivered

Usage

$ zca msg delivered <json> [options]

Options

Flag	Description	Default
-g, --group	Message is in a group	—
-s, --seen	Also mark as seen	—

zca msg report

Report a user or group thread

Usage

$ zca msg report <threadId> <reason> [options]

Options

Flag	Description	Default
-c, --content <text>	Report details (required for "other" reason)	—
-g, --group	Thread is a group	—

Examples

Report user for fraud (reasons: sensitive, annoy, fraud, other)

$ zca msg report 123456789 fraud

zca msg parse-link

Parse link metadata (title, description, thumbnail)

Usage

$ zca msg parse-link <url>

Examples

Get link preview metadata

$ zca msg parse-link "https://github.com"

Tips

Finding Thread IDs

Use zca friend list --json or zca group list --json to get user and group IDs.

Batch Sending

Use msg forward to send the same message to multiple recipients in one command.

Group Management

Create, manage, and administer Zalo groups with full control over members, settings, and invites.

Basic Commands

zca group list

List all groups you're a member of.

Usage

$ zca group list [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

Examples

List groups in table format

$ zca group list

List groups as JSON

$ zca group list --json

zca group info

Get detailed information about a group.

Usage

$ zca group info <groupId>

Examples

Get group info

$ zca group info 123456789

zca group members

List all members in a group with full profile details.

Usage

$ zca group members <groupId> [options]

Options

Flag	Description	Default
-j, --json	Output full member profiles as JSON	—

Examples

List group members in table format

$ zca group members 123456789

Get full member profiles as JSON

$ zca group members 123456789 --json

zca group create

Create a new group with specified members.

Usage

$ zca group create <name> <members...>

Examples

Create a new group

$ zca group create "Project Team" 111 222 333

Group Settings

zca group rename

Change the group name.

Usage

$ zca group rename <groupId> <name>

Examples

Rename a group

$ zca group rename 123456789 "New Name"

zca group avatar

Change the group avatar image.

Usage

$ zca group avatar <groupId> <file>

Examples

Set group avatar

$ zca group avatar 123456789 ./avatar.jpg

zca group settings

Update group settings like name lock and admin message highlighting.

Usage

$ zca group settings <groupId> [options]

Options

Flag	Description	Default
--lock-name	Lock group name (only admin can change)	—
--unlock-name	Unlock group name	—
--sign-admin	Highlight admin messages	—
--no-sign-admin	Disable admin message highlighting	—

Examples

Lock the group name

$ zca group settings 123456789 --lock-name

Member Management

zca group add

Add members to a group.

Usage

$ zca group add <groupId> <userIds...>

Examples

Add members to group

$ zca group add 123456789 111 222

zca group remove

Remove members from a group.

Usage

$ zca group remove <groupId> <userIds...>

Examples

Remove a member

$ zca group remove 123456789 111

zca group add-deputy

Promote a member to group deputy (admin).

Usage

$ zca group add-deputy <groupId> <userId>

zca group remove-deputy

Demote a deputy back to regular member.

Usage

$ zca group remove-deputy <groupId> <userId>

zca group transfer

Transfer group ownership to another member.

Usage

$ zca group transfer <groupId> <newOwnerId>

zca group block

Block a member in the group.

Usage

$ zca group block <groupId> <userId>

zca group unblock

Unblock a member in the group.

Usage

$ zca group unblock <groupId> <userId>

zca group blocked

List blocked members in a group.

Usage

$ zca group blocked <groupId>

Invite Links

zca group enable-link

Enable the group invite link.

Usage

$ zca group enable-link <groupId>

zca group disable-link

Disable the group invite link.

Usage

$ zca group disable-link <groupId>

zca group link-detail

Get the group's invite link details.

Usage

$ zca group link-detail <groupId>

zca group join-link

Join a group via invite link.

Usage

$ zca group join-link <linkId>

Pending Members

zca group pending

List pending member requests.

Usage

$ zca group pending <groupId>

zca group review

Approve or deny pending member requests.

Usage

$ zca group review <groupId> <userId> <action>

Examples

Approve a member request

$ zca group review 123456789 111 approve

Deny a member request

$ zca group review 123456789 111 deny

Leave & Disperse

zca group leave

Leave a group.

Usage

$ zca group leave <groupId>

zca group disperse

Dissolve a group (owner only). This cannot be undone.

Usage

$ zca group disperse <groupId>

Friend Management

Manage your Zalo friends: search, add, block, set nicknames, and more.

Basic Commands

zca friend list

List all your friends.

Usage

$ zca friend list [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

Examples

List friends in table format

$ zca friend list

List friends as JSON

$ zca friend list --json

zca friend find

Search for users by phone number or name.

Usage

$ zca friend find <query> [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

Examples

Find by phone number

$ zca friend find 0901234567

Find by name

$ zca friend find "John Doe"

zca friend online

List friends who are currently online.

Usage

$ zca friend online [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

zca friend recommendations

Get friend recommendations.

Usage

$ zca friend recommendations [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

Friend Requests

zca friend add

Send a friend request.

Usage

$ zca friend add <userId> [options]

Options

Flag	Description	Default
-m, --message <msg>	Custom request message	"Hello!"

Examples

Send with default message

$ zca friend add 123456789

Send with custom message

$ zca friend add 123456789 -m "Hi from zca-cli!"

zca friend accept

Accept a friend request.

Usage

$ zca friend accept <userId>

zca friend reject

Reject a friend request.

Usage

$ zca friend reject <userId>

zca friend cancel

Cancel a sent friend request.

Usage

$ zca friend cancel <userId>

zca friend sent

View friend requests you've sent.

Usage

$ zca friend sent [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

zca friend request-status

Check the status of a friend request.

Usage

$ zca friend request-status <userId>

Managing Friends

zca friend remove

Remove a friend from your list.

Usage

$ zca friend remove <userId>

zca friend alias

Set a nickname for a friend.

Usage

$ zca friend alias <userId> <alias>

Examples

Set a nickname

$ zca friend alias 123456789 "Best Friend"

zca friend remove-alias

Remove a nickname from a friend.

Usage

$ zca friend remove-alias <userId>

zca friend aliases

List all friend nicknames.

Usage

$ zca friend aliases [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

Blocking

zca friend block

Block a user.

Usage

$ zca friend block <userId>

zca friend unblock

Unblock a user.

Usage

$ zca friend unblock <userId>

zca friend block-feed

Block a user from viewing your feed.

Usage

$ zca friend block-feed <userId>

zca friend unblock-feed

Unblock a user from viewing your feed.

Usage

$ zca friend unblock-feed <userId>

Other

zca friend boards

Get friend boards for a conversation.

Usage

$ zca friend boards <conversationId> [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

Profile & Account

Manage your Zalo profile, avatar, online status, and account information.

Commands

zca me info

Get your account information.

Usage

$ zca me info [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

Examples

Get your account info

$ zca me info

zca me id

Get your Zalo user ID.

Usage

$ zca me id

Examples

Get your Zalo ID

$ zca me id

zca me update

Update your profile information.

Usage

$ zca me update [options]

Options

Flag	Description	Default
-n, --name <name>	Set your display name	—
-g, --gender <gender>	Set your gender (male/female)	—
-b, --birthday <date>	Set your birthday (YYYY-MM-DD)	—

Examples

Update your display name

$ zca me update --name "New Name"

Update name and birthday

$ zca me update --name "John" --birthday "1990-01-15"

zca me avatar

Change your profile avatar.

Usage

$ zca me avatar <file>

Examples

Set avatar from file

$ zca me avatar ./photo.jpg

zca me avatars

List all your avatars.

Usage

$ zca me avatars [options]

Options

Flag	Description	Default
-j, --json	Output as JSON	—

zca me delete-avatar

Delete an avatar.

Usage

$ zca me delete-avatar <id>

zca me reuse-avatar

Set a previous avatar as your current one.

Usage

$ zca me reuse-avatar <id>

zca me status

Update your online status.

Usage

$ zca me status <status>

Examples

Set status to online

$ zca me status online

Set status to offline

$ zca me status offline

zca me last-online

Check when a user was last online.

Usage

$ zca me last-online <userId>

Examples

Check last online time

$ zca me last-online 123456789

Multi-Account Support

Manage multiple Zalo accounts with profiles. Switch between accounts easily.

How it Works

zca-cli supports multiple Zalo accounts through a profile system. Each profile stores its own credentials, contacts cache, and settings independently.

Profile Resolution Order

--profile CLI flag (highest priority)
ZCA_PROFILE environment variable
Default profile setting (set via account switch)
Falls back to "default" profile

Using Profiles

Method 1: --profile Flag

Use the --profile flag with any command:

# Login to work account
$ zca --profile work auth login
.
# Send message from work account
$ zca --profile work msg send 123456789 "Hello from work"
.
# Login to personal account
$ zca --profile personal auth login
.
# Send from personal account
$ zca --profile personal msg send 987654321 "Hello from personal"

Method 2: Environment Variable

Set the ZCA_PROFILE environment variable:

# Set profile for current session
$ export ZCA_PROFILE=work
.
# All commands now use the work profile
$ zca msg send 123456789 "Hello"
$ zca group list
.
# Or use inline
$ ZCA_PROFILE=work zca msg send 123456789 "Hello"

Commands

zca account list

List all account profiles with their status.

Usage

$ zca account list

Examples

List all profiles

$ zca account list

Short alias

$ zca account ls

zca account switch

Set the default profile.

Usage

$ zca account switch <name>

Examples

Switch to work profile

$ zca account switch work

Using 'use' alias

$ zca account use personal

zca account current

Show the currently active profile.

Usage

$ zca account current

Examples

Show current profile

$ zca account current

Using 'whoami' alias

$ zca account whoami

zca account add

Create a new profile (provides instructions for login).

Usage

$ zca account add [name]

Examples

Create 'work' profile

$ zca account add work

Interactive profile creation

$ zca account new

zca account label

Set a description label for a profile.

Usage

$ zca account label <name> <label>

Examples

Set a label for work profile

$ zca account label work "Office Zalo"

zca account remove

Remove a profile and all its data.

Usage

$ zca account remove <name>

Examples

Remove a profile

$ zca account remove old-account

Short alias

$ zca account rm old-account

Example Workflow

multi-account-setup.sh

1# Step 1: Login to your work account
2$ zca --profile work auth login
3# Scan QR with your work Zalo
4.
5# Step 2: Login to your personal account
6$ zca --profile personal auth login
7# Scan QR with your personal Zalo
8.
9# Step 3: Label your profiles
10$ zca account label work "Office - Company Zalo"
11$ zca account label personal "My personal Zalo"
12.
13# Step 4: Set default profile
14$ zca account switch work
15.
16# Step 5: List all profiles
17$ zca account list
18# Output:
19#   work (default) - Office - Company Zalo
20#   personal - My personal Zalo
21.
22# Now you can use them:
23$ zca msg send 123 "From work (default)"
24$ zca --profile personal msg send 456 "From personal"

Multi-Account API Server

Serve multiple Zalo profiles from a single REST API server with the --accounts option. Each profile gets its own URL prefix for routing.

multi-account-serve.sh

1# Serve multiple profiles from one server
2$ zca serve --accounts work,personal
3.
4# Each profile gets its own URL prefix:
5# GET /api/work/friends    → work profile
6# GET /api/personal/friends → personal profile
7# GET /api/friends          → default (work)
8.
9# Example: Send from different accounts
10$ curl -X POST http://localhost:56789/api/work/messages/text \
11$   -H 'Content-Type: application/json' \
12$   -d '{"threadId":"123","message":"From work"}'
13.
14$ curl -X POST http://localhost:56789/api/personal/messages/text \
15$   -H 'Content-Type: application/json' \
16$   -d '{"threadId":"456","message":"From personal"}'
17.
18# Real-time events are isolated per profile
19$ curl -N http://localhost:56789/api/work/events     # work events only
20$ curl -N http://localhost:56789/api/personal/events # personal events only

Combine with auth: Add --auth-bearer or --auth-basic to protect all profiles. Example: zca serve --accounts work,personal --auth-bearer my-token

Tips

Profile Names

Use only letters, numbers, dashes, and underscores in profile names. Examples: work, personal-2, company_main

Separate Caches

Each profile maintains its own contacts cache. After switching profiles, your friend and group lists reflect that account's contacts.

Scripting

For scripts, use the environment variable method to avoid repeating --profile on every command.

Real-time Listener

Listen for incoming messages in real-time. Supports webhooks, echo mode, and auto-restart.

Overview

The listen command starts a persistent connection to Zalo's servers, receiving messages as they arrive. This is perfect for building bots, webhooks, or automated responses.

Command

zca listen

Start the real-time message listener.

Usage

$ zca listen [options]

Options

Flag	Description	Default
-e, --echo	Echo received messages back to sender	—
-p, --prefix <prefix>	Only process messages starting with this prefix	—
-w, --webhook <url>	Forward messages to this URL	—
-r, --raw	Output raw JSON format	—
-k, --keep-alive	Auto-restart on disconnect	—
--events <types>	Filter event types (comma-separated). Options: message, reaction, undo, group_event, typing, seen, delivered, friend_event	—
--self	Include own messages (default: skip self)	—

Event Types

The listener supports 8 event types. By default, all events are enabled. Use --events to filter.

message - Incoming messages

reaction - Message reactions

undo - Message recalls

group_event - Group changes (join, leave, settings)

typing - Typing indicators

seen - Message seen receipts

delivered - Delivery receipts

friend_event - Friend requests, blocks

# Listen for messages and reactions only
$ zca listen --events "message,reaction"
.
# Monitor group events with webhook
$ zca listen --events "group_event" --webhook "https://api.example.com/hook"
.
# Include own (self) messages
$ zca listen --self
.
# All events (default)
$ zca listen

Basic Usage

Start listening for messages:

# Start basic listener
$ zca listen
.
# Output:
# [User] John Doe (123456789): Hello!
# [Group] Project Team (987654321) | Jane (111222333): Meeting at 3pm

Press Ctrl+C to stop.

Echo Mode

Automatically reply with the same message (great for testing):

# Echo all messages
$ zca listen --echo
.
# Echo only messages starting with "!"
$ zca listen --echo --prefix "!"

With prefix filter, the prefix is stripped from the echo reply.

Webhook Integration

Forward messages to an HTTP endpoint:

# Send messages to your webhook
$ zca listen --webhook "https://your-server.com/webhook"
.
# Combine with prefix filter
$ zca listen --webhook "https://your-server.com/webhook" --prefix "!bot"

Webhook Payload

Your webhook receives POST requests with this JSON structure:

message-event-payload.json

$ {
$   "event": "message",
$   "threadId": "123456789",
$   "type": 0,
$   "content": "Hello world",
$   "msgType": "webchat",
$   "timestamp": 1705847123456,
$   "metadata": {
$     "isGroup": false,
$     "threadName": "John Doe",
$     "senderName": "John Doe",
$     "fromId": "123456789"
$   },
$   "raw": { /* full message object */ }
$ }

other-event-payload.json

$ {
$   "event": "reaction|undo|group_event|typing|seen|delivered|friend_event",
$   "threadId": "123456789",
$   "isGroup": false,
$   "data": { /* event-specific data */ },
$   "timestamp": 1705847123456,
$   "metadata": { "isGroup": false, "threadId": "123456789" }
$ }

Type Values

0 = User (direct message)
1 = Group message

Raw JSON Mode

Output messages as JSON (same format as webhook), useful for piping to other tools:

# Output as JSON
$ zca listen --raw
.
# Pipe to jq for processing
$ zca listen --raw | jq '.content'
.
# Save to file
$ zca listen --raw >> messages.jsonl

Auto-Restart

For production use, enable auto-restart with exponential backoff:

# Auto-restart on disconnect
$ zca listen --keep-alive
.
# Combine with webhook for reliable bot
$ zca listen --webhook "https://api.example.com/bot" --keep-alive

Backoff Strategy

Initial delay: 5 seconds
Multiplier: 2x on each retry
Maximum delay: 5 minutes
Resets to initial delay on successful connection

Session Keep-Alive

Keep your session alive without a full listener. Useful for maintaining authentication when you only need to send messages periodically.

zca keep-alive

Keep the session alive with periodic pings

Usage

$ zca keep-alive [options]

Options

Flag	Description	Default
-i, --interval <seconds>	Ping interval in seconds (default: 60, min: 5, max: 3600)	—

Examples

Default 60s ping interval

$ zca keep-alive

Ping every 30 seconds

$ zca keep-alive -i 30

Production Example

A typical production setup using systemd or pm2:

start-bot.sh

#!/bin/bash
# Production listener with all options
.
$ zca listen \
$   --webhook "https://api.mybot.com/zalo/webhook" \
$   --prefix "!bot" \
$   --keep-alive \
$   --raw \
$   --events "message,reaction,group_event"
.
# Include own messages (useful for logging all activity)
# zca listen --self --raw --keep-alive

Tips

Own Messages

By default, messages you send are filtered out. Use --self to include your own messages (useful for logging all activity).

Contact Names

The listener automatically caches contacts on connect. Names are resolved from cache for better readability.

Keep-Alive Ping

The listener sends a keep-alive ping every 60 seconds to maintain the connection.

REST API Server

Run a full-featured HTTP API server with 138 endpoints for building integrations, bots, and dashboards.

Overview

The zca serve command starts a local REST API server that exposes the entire Zalo API as HTTP endpoints. Use it to build web dashboards, integrate with automation platforms (n8n, Make, Zapier), or power chatbots.

138 REST endpoints

SSE Real-time event stream

QR Login Login via SSE stream

Multi-account Serve multiple profiles

Auth Bearer/Basic authentication

Rate limiting IP-based protection

CORS Cross-origin enabled

Command

zca serve

Start a REST API server exposing all Zalo API functionality

Usage

$ zca serve [options]

Options

Flag	Description	Default
--port <port>	Port to listen on (default: 56789)	—
--host <host>	Host to bind to (default: localhost)	—
--rate-limit <number>	Max requests per minute per IP, 0 to disable (default: 100)	—
--max-sse <number>	Max concurrent SSE connections, 0 for unlimited (default: 10)	—
--auth-bearer <token>	Require Bearer token authentication	—
--auth-basic <user:pass>	Require Basic authentication	—
--accounts <profiles>	Comma-separated profile names to serve	—
--self	Include own messages in SSE events (default: skip self)	—

Examples

Start with defaults (port 56789)

$ zca serve

Custom port

$ zca serve --port 8080

With Bearer token auth

$ zca serve --auth-bearer mytoken

Serve multiple Zalo profiles

$ zca serve --accounts work,personal

Multi-account with auth

$ zca serve --accounts work,personal --auth-bearer token --port 8080

Include own messages in SSE stream

$ zca serve --self

Quick Start

Start the server and interact with it using curl or any HTTP client:

# Start the API server
$ zca serve
.
# Send a text message
$ curl -X POST http://localhost:56789/api/messages/text \
$   -H 'Content-Type: application/json' \
$   -d '{"threadId":"USER_ID","message":"Hello from API!"}'
.
# Get your profile
$ curl http://localhost:56789/api/me
.
# List friends
$ curl http://localhost:56789/api/friends
.
# Listen for real-time events (SSE)
$ curl -N http://localhost:56789/api/events

API Categories

Visit http://localhost:56789/api for the full interactive endpoint index. Key categories:

Messages15 endpoints

Send text, images, videos, files, links, stickers, cards

Friends14 endpoints

List, search, add, block, alias management

Groups25 endpoints

Create, manage members, settings, roles, pins

Conversations18 endpoints

List, pin, hide, mute, auto-delete, labels

Polls7 endpoints

Create, vote, lock, share polls

Auto-Replies4 endpoints

CRUD auto-reply rules with scheduling

Settings8 endpoints

Privacy, online status, language, labels

Profile5 endpoints

Get/update profile, avatar, cover photo

Real-time Events (SSE)

Connect to /api/events for Server-Sent Events. Events are streamed in real-time as they occur. By default, own (self) messages are excluded. Use --self to include them:

# Include own messages in SSE events
$ zca serve --self

sse-events.js

$ const events = new EventSource("http://localhost:56789/api/events");
.
$ events.onmessage = (event) => {
$   const data = JSON.parse(event.data);
$   console.log(data.type, data);
$   // Types: "connected", "message", "reaction", "group_event"
$ };

sse-payload-example.json

$ {
$   "type": "message",
$   "threadId": "123456789",
$   "senderId": "987654321",
$   "content": "Hello!",
$   "timestamp": 1705847123456,
$   "isGroup": false
$ }

Rate Limiting & Security

Built-in IP-based rate limiting protects against abuse. When exceeded, the server returns HTTP 429 Too Many Requests with a Retry-After header.

Rate Limit

Default: 100 requests/minute per IP. Configure with --rate-limit. Set to 0 to disable.

SSE Connection Limit

Default: 10 concurrent SSE connections. Configure with --max-sse. Set to 0 for unlimited.

Request Size

Maximum request body: 10MB. Larger requests are rejected.

Authentication

Protect your API with Bearer token or HTTP Basic authentication. Both methods use constant-time comparison to prevent timing attacks.

bearer-auth.sh

# Start server with Bearer token
$ zca serve --auth-bearer my-secret-token
.
# Make authenticated request
$ curl http://localhost:56789/api/me \
$   -H "Authorization: Bearer my-secret-token"

basic-auth.sh

# Start server with Basic auth
$ zca serve --auth-basic admin:password123
.
# Make authenticated request
$ curl http://localhost:56789/api/me \
$   -H "Authorization: Basic $(echo -n admin:password123 | base64)"

Security tip: Use environment variables or a config file to store tokens instead of passing them on the command line. For production use, always run behind a reverse proxy with TLS/HTTPS.

Multi-Account Serving

Serve multiple Zalo profiles from a single server instance. Each profile is accessible via a URL prefix.

multi-account.sh

# Serve two profiles
$ zca serve --accounts work,personal
.
# Access work profile endpoints
$ curl http://localhost:56789/api/work/friends
.
# Access personal profile endpoints
$ curl http://localhost:56789/api/personal/friends
.
# Default profile (no prefix routes to first listed)
$ curl http://localhost:56789/api/friends  # routes to 'work'
.
# List all loaded profiles
$ curl http://localhost:56789/api

URL Routing

/api/{profile}/endpoint → profile-specific request
/api/endpoint → default profile (first in --accounts list)

SSE Events

Each profile has isolated SSE streams. Connect to /api/work/events for work profile events only.

Limits

Recommended: 3-5 profiles max. Each profile runs an independent API instance and listener.

Login QR via SSE

Allow users to login via QR code scan directly from your web/mobile app. The login flow streams real-time updates via SSE, from QR generation to successful authentication.

New feature: Login QR endpoints bypass authentication, so users can obtain credentials even when the server requires --auth-bearer or --auth-basic.

# Start login for a profile (returns SSE stream)
$ curl -X POST http://localhost:56789/api/auth/login-qr \
$   -H 'Content-Type: application/json' \
$   -d '{"profile":"work"}'
.
# Multi-account: profile via URL path
$ curl -X POST http://localhost:56789/api/work/auth/login-qr
.
# Check active login sessions
$ curl http://localhost:56789/api/auth/login-qr/status
.
# Abort a login session
$ curl -X POST http://localhost:56789/api/auth/login-qr/abort \
$   -H 'Content-Type: application/json' \
$   -d '{"profile":"work"}'

SSE Event Flow

connected→ Session started

qr_generated→ QR code ready (display to user)

qr_scanned→ User scanned in Zalo app

got_login_info→ Credentials received (saved server-side)

login_success→ Profile saved & loaded into server

Error Events

qr_expired→ QR code timed out (retry)

qr_declined→ User declined login

login_error→ Login failed (see error message)

async function loginWithQR(profile = 'default') {
  const res = await fetch('http://localhost:56789/api/auth/login-qr', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ profile })
  });
.
  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
.
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
.
    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n\n');
    buffer = lines.pop();
.
    for (const line of lines) {
      if (!line.trim()) continue;
.
      const eventMatch = line.match(/^event: (.+)$/m);
      const dataMatch = line.match(/^data: (.+)$/m);
.
      if (eventMatch && dataMatch) {
        const event = eventMatch[1];
        const data = JSON.parse(dataMatch[1]);
.
        switch (event) {
          case 'qr_generated':
            displayQRCode(data.code); // Show QR to user
            break;
          case 'qr_scanned':
            showUserInfo(data.avatar, data.display_name);
            break;
          case 'login_success':
            redirectToDashboard();
            break;
          case 'login_error':
            showError(data.error);
            break;
        }
      }
    }
  }
}

Security Notes

• Credentials never exposed via API (saved server-side only)
• Only one login per profile at a time (concurrent attempts get HTTP 409)
• Client disconnect automatically aborts the login flow
• Still rate-limited (default: 100 req/min) to prevent abuse

After Login

Profile is automatically saved to config and loaded into the running server with its own listener, routes, and SSE event stream. No server restart needed.

Tips

Use with automation tools

Connect n8n, Make, or Zapier to the REST API for no-code Zalo automation workflows.

Production deployment

For production use, put the server behind a reverse proxy (nginx) and bind to 0.0.0.0.

API index

Visit http://localhost:56789/api in your browser to see all available endpoints grouped by category.

License Management

Manage your zca-cli license: get support codes, activate, check status, and deactivate.

Overview

zca-cli requires a valid license for full functionality. Licenses can be bound to your device or your Zalo account, giving you flexibility in how you use the tool.

License Features

One-time purchase, perpetual license
Device or account-bound for security
Lifetime updates included
Priority support

License Types

zca-cli offers two license types to fit your workflow:

Device-Based License

Bound to your specific device using a hardware fingerprint. Best for single-device usage.

• Bound to one device via Support Code

• Works offline after activation

• Ideal for dedicated workstations

Get your Support Code:

zca license support-code

Account-Based License

Flexible

Bound to your Zalo User ID. Use on multiple devices with the same Zalo account.

• Use on unlimited devices

• Bound to your Zalo account

• Perfect for developers on the go

Get your Zalo User ID:

zca me id

Activation Process

Follow the steps for your license type to activate:

Device-Based Activation

Step 1: Get Your Support Code

Generate your unique device support code:

$ zca license support-code

This displays a code like ZCA-XXXX-XXXX-XXXX along with your device information.

Step 2: Purchase License

Visit zca-cli.dev and enter your support code during checkout. After payment, you'll receive your license key via email.

Step 3: Activate

Activate using your license key:

# Activate with your license key
$ zca license activate "YOUR_LICENSE_KEY_HERE"

Step 4: Verify

Check that your license is active:

$ zca license status

Account-Based Activation

Step 1: Login to Zalo

First, login to your Zalo account:

$ zca auth login

Step 2: Get Your Zalo User ID

Get your unique Zalo User ID:

$ zca me id

This displays your Zalo User ID like 1234567890123456789.

Step 3: Purchase License

Visit zca-cli.dev and select "Account-Based" license. Enter your Zalo User ID during checkout. After payment, you'll receive your license key via email.

Step 4: Activate

Activate using your license key:

# Activate with your license key
$ zca license activate "YOUR_LICENSE_KEY_HERE"

Commands

zca license support-code

Display your device support code for device-based license activation.

Usage

$ zca license support-code

Examples

Get your support code

$ zca license support-code

zca me id

Display your Zalo User ID for account-based license activation.

Usage

$ zca me id

Examples

Get your Zalo User ID

$ zca me id

zca license activate

Activate your license with the provided key.

Usage

$ zca license activate <key>

Examples

Activate with license key

$ zca license activate "eyJhbGciOiJFZDI1NTE5Ii..."

zca license status

Show current license status and details.

Usage

$ zca license status

Examples

Check license status

$ zca license status

zca license deactivate

Remove the license from this device.

Usage

$ zca license deactivate [options]

Options

Flag	Description	Default
-f, --force	Skip confirmation prompt	—

Examples

Deactivate license (with confirmation)

$ zca license deactivate

Force deactivate without confirmation

$ zca license deactivate --force

License Key Format

License keys can be provided in two formats:

Format 1: Compact

Payload and signature separated by a dot:

eyJwcm9kdWN0X2lkIjoiemNhLWNsaSI...signature

Format 2: JSON

Full JSON object with payload and signature:

$ {
$   "payload": "eyJwcm9kdWN0X2lkIjoiemNhLWNsaSI...",
$   "signature": "..."
$ }

FAQ

Which license type should I choose?

Choose Device-Based if you only use zca-cli on one computer. Choose Account-Based if you work across multiple devices (laptop, desktop, servers) with the same Zalo account.

Can I use one license on multiple devices?

With Device-Based license: No, it's bound to one device. With Account-Based license: Yes, unlimited devices as long as you use the same Zalo account.

Can I transfer my license to another device?

Device-Based licenses are bound to specific devices. Contact support if you need to transfer. Account-Based licenses work on any device with your Zalo account.

What happens if my hardware changes?

Minor hardware changes (like RAM upgrades) typically don't affect your license. Significant changes may require reactivation - contact support.

Where is the license stored?

Run zca license status to see the license file path. It's stored in your OS-specific app data directory.