Official Account

Official Account (OA)

Manage Zalo Official Account via official API v3.0. Independent from personal account (zca-js).

Note: Some APIs require OA tier upgrade. See zalo.cloud/oa/pricing.

Quick Start

Interactive (human)

zalo-agent oa init

Non-interactive (AI agent / CI)

zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook
zalo-agent oa init --app-id <ID> --secret <KEY> --tunnel ngrok -p 3000
zalo-agent oa init --app-id <ID> --secret <KEY> --webhook-url https://server.com/webhook

VPS (headless)

zalo-agent oa login --app-id <ID> --secret <KEY> --callback-host https://your-vps.com

---

Auth Commands

Command	Description
oa init	Guided setup wizard (interactive + non-interactive)
oa login --app-id <id> --secret <key>	OAuth login (opens browser)
oa login ... --callback-host <url>	OAuth from VPS (binds 0.0.0.0)
oa refresh	Refresh expired access token
oa setup <token>	Manually set access token
oa whoami	Show OA profile info

Messaging

zalo-agent oa msg text <user-id> "Hello" [-m cs|transaction|promotion]
zalo-agent oa msg image <user-id> --image-url https://...
zalo-agent oa msg image <user-id> --image-id <attachment_id>
zalo-agent oa msg file <user-id> <file-id>
zalo-agent oa msg list <user-id> '[{"title":"A"},{"title":"B"}]'
zalo-agent oa msg status <message-id>

Followers

zalo-agent oa follower list [--offset 0] [--count 50]
zalo-agent oa follower info <user-id>
zalo-agent oa follower update <user-id> '{"name":"..."}'

Tags

zalo-agent oa tag list
zalo-agent oa tag assign <user-id> <tag-name>
zalo-agent oa tag remove <tag-name>
zalo-agent oa tag untag <user-id> <tag-name>

Media Upload

zalo-agent oa upload image ./photo.jpg    # Returns attachment_id
zalo-agent oa upload file ./doc.pdf       # Returns file token

Conversations

zalo-agent oa conv recent [--count 10]
zalo-agent oa conv history <user-id> [--count 10]

Webhook Listener

zalo-agent oa listen -p 3000                        # Basic
zalo-agent oa listen -p 3000 -s <SECRET>            # With MAC verify
zalo-agent oa listen -e user_send_text,follow        # Filter events
zalo-agent oa listen --verify-domain <CODE>          # Domain verification
zalo-agent --json oa listen | jq '.message.text'     # JSON pipe

Events: follow, unfollow, user_send_text, user_send_image, user_send_file, user_send_location, user_send_sticker, user_send_gif, user_click_button, user_click_link

Other

zalo-agent oa menu '{"buttons":[...]}'
zalo-agent oa article create|list|detail
zalo-agent oa store product-create|product-list|product-info
zalo-agent oa store category-create|category-list
zalo-agent oa store order-create

Webhook Setup Options

Method	Command
ngrok	oa init --tunnel ngrok
cloudflared	oa init --tunnel cloudflared
Own server	oa init --webhook-url https://...
n8n	Use n8n-nodes-zalo-oa-integration

Credentials

Stored at ~/.zalo-agent/oa-credentials.json (chmod 600).

Multi-OA with --oa-id:

zalo-agent oa login --app-id <ID1> --secret <K1> --oa-id shop1
zalo-agent oa whoami --oa-id shop1

Security

• Credential file: owner-only (0600)
• MAC: HMAC-SHA256 timing-safe comparison
• Message type whitelist: cs, transaction, promotion
• Body size limit: 1MB
• OAuth callback: 127.0.0.1 (local) / 0.0.0.0 (VPS)