Listener

Listener (listen)

Real-time message listener with webhook and local storage.

# Basic listen
zalo-agent listen

# DM only + webhook
zalo-agent listen -f user -w https://your-n8n.com/webhook/zalo

# Save messages locally as JSONL
zalo-agent listen --save ./zalo-logs

# JSON mode + save + webhook
zalo-agent --json listen --save ./zalo-logs -w https://webhook.url

# Auto-accept friend requests
zalo-agent listen --auto-accept

Flags

Flag	Description
-e <events>	Event types: message, friend, group, reaction
-f <filter>	Filter: user, group, all
-w <url>	Webhook URL
--save <dir>	Save JSONL locally
--no-self	Exclude own messages
--auto-accept	Auto-accept friend requests

JSONL Storage

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.

Local Cache (v1.1.0)

listen also passively writes every event to a per-account SQLite database:

~/.zalo-agent-cli/accounts/<ownId>/zalo.db

This enables cache-first reads for other commands:

Command	Cache behavior
friend list	Reads from cache; --no-cache forces live
friend search	Reads from cache; --no-cache forces live
conv recent	Reads from cache; --no-cache forces live
msg history	Reads from cache; --no-cache fetches live + backfills
msg search	FTS5 full-text search on cached messages

See Local Cache for full details.