Official Account (VN)

Official Account (OA)

Quản lý Zalo Official Account qua API v3.0 chính thức. Độc lập với tài khoản cá nhân (zca-js).

Lưu ý: Một số API cần upgrade OA tier. Xem zalo.cloud/oa/pricing.

Bắt đầu nhanh

Interactive (con người)

zalo-agent oa init

Wizard hướng dẫn: nhập credentials → OAuth login → chọn tunnel → webhook setup.

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 server)

zalo-agent oa login --app-id <ID> --secret <KEY> --callback-host https://your-vps.com
# Copy URL auth → mở trên browser local → VPS nhận token

---

Xác thực

Lệnh	Mô tả
oa init	Setup wizard (interactive + non-interactive)
oa login --app-id <id> --secret <key>	OAuth login (mở browser)
oa login ... --callback-host <url>	OAuth từ VPS (bind 0.0.0.0)
oa refresh	Làm mới access token
oa setup <token>	Set token thủ công
oa whoami	Xem thông tin OA

Tin nhắn

# Text (message type: cs | transaction | promotion)
zalo-agent oa msg text <user-id> "Xin chào" [-m cs]

# Ảnh
zalo-agent oa msg image <user-id> --image-url https://...
zalo-agent oa msg image <user-id> --image-id <attachment_id>

# File (cần upload trước)
zalo-agent oa msg file <user-id> <file-id>

# Danh sách
zalo-agent oa msg list <user-id> '[{"title":"A"},{"title":"B"}]'

# Kiểm tra trạng thái
zalo-agent oa msg status <message-id>

Người theo dõi

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

Nhãn (Tag)

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>

Upload media

zalo-agent oa upload image ./photo.jpg    # Trả về attachment_id
zalo-agent oa upload file ./doc.pdf       # Trả về file token

Hội thoại

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

Webhook Listener

# Cơ bản
zalo-agent oa listen -p 3000

# Với MAC verification
zalo-agent oa listen -p 3000 -s <SECRET>

# Lọc events
zalo-agent oa listen -e user_send_text,follow

# Domain verification
zalo-agent oa listen --verify-domain <CODE>

# JSON pipe
zalo-agent --json oa listen | while read -r event; do
  echo "$event" | jq '.message.text'
done

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

Khác

zalo-agent oa menu '{"buttons":[...]}'              # Cập nhật menu OA
zalo-agent oa article create|list|detail             # Bài viết
zalo-agent oa store product-create|product-list      # Sản phẩm
zalo-agent oa store category-create|category-list    # Danh mục
zalo-agent oa store order-create                     # Đơn hàng

Cách expose webhook

Cách	Lệnh
ngrok	oa init --tunnel ngrok
cloudflared	oa init --tunnel cloudflared
VPS riêng	oa init --webhook-url https://...
n8n	Dùng n8n-nodes-zalo-oa-integration

Yêu cầu từ Zalo

• Domain phải được xác thực (Xác thực domain)
• Webhook URL phải HTTPS
• IP Việt Nam để nhận đầy đủ thông tin user
• Phải trả về 200 OK trong 5 giây

Credentials

Lưu tại ~/.zalo-agent/oa-credentials.json (quyền 0600).

Quản lý nhiều OA với --oa-id:

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

Bảo mật

• File credentials: chỉ owner đọc (0600)
• MAC: HMAC-SHA256 so sánh timing-safe
• Whitelist message type: cs, transaction, promotion
• Giới hạn body: 1MB
• OAuth callback: 127.0.0.1 (local) / 0.0.0.0 (VPS)