Skill: codedao12/zalo (version 1.0.1)

--- name: zalo description: OpenClaw skill for Zalo Bot API workflows (bot token) plus optional guidance on unofficial personal automation tools. --- # Zalo Bot Skill (Advanced) ## Purpose Provide a production-oriented guide for Zalo Bot API workflows (token-based), with a separate, clearly marked branch for unofficial personal automation tools. ## Best fit - You use the Zalo Bot Platform / bot token path. - You need clear webhook or long-polling handling. - You want professional conversation UX guidance. ## Not a fit - You require guaranteed, officially supported personal-account automation. - You need rich media streaming or advanced file pipelines. ## Quick orientation - Read `references/zalo-bot-overview.md` for platform scope and constraints. - Read `references/zalo-bot-token-and-setup.md` for token setup and connection flow. - Read `references/zalo-bot-messaging-capabilities.md` for capability checklist. - Read `references/zalo-bot-ux-playbook.md` for UX and conversation patterns. - Read `references/zalo-bot-webhook-routing.md` for webhook/polling handling. - Read `references/zalo-personal-zca-js.md` for the unofficial personal-account branch. - Read `references/zalo-n8n-automation.md` for automation notes and cautions. ## Required inputs - Bot token and bot configuration. - Target workflow (notify, support, broadcast). - Delivery model (webhook or polling). ## Expected output - A clear bot workflow plan, method checklist, and operational guardrails. ## Operational notes - Validate inbound events and handle retries safely. - Keep replies concise; rate-limit outgoing messages. - Prefer explicit allowlists for any automation flow. ## Security notes - Never log tokens or credentials. - Treat all state files and cookies as secrets.

path: references/zalo-personal-zca-js.md
content: # Personal Zalo Automation (Unofficial)

## Overview
- `zca-js` is an unofficial library that automates Zalo Web.
- It typically requires cookies and device identifiers.
- Some tools wrap Zalo Web via `zca-cli` for automation.

## Risks and constraints
- Unofficial automation can violate platform terms.
- Accounts may be limited or banned.
- Cookies and session state are sensitive and must be protected.

## When to consider
- Only for personal, low-risk workflows.
- Only with explicit user consent and acceptance of risk.

## Operational notes
- Store cookies securely and rotate often.
- Avoid running on shared hosts.
- Prefer official bot APIs when possible.


path: references/zalo-bot-token-and-setup.md
content: # Bot Token and Setup

## 1) Token acquisition
- Obtain the bot token from the Zalo Bot Platform dashboard.
- Treat it like a secret; never log or commit it.

## 2) OpenClaw integration (if used)
- Configure via env: `ZALO_BOT_TOKEN` or config file (`channels.zalo.botToken`).
- Optional: `channels.zalo.tokenFile` to load from a file.
- Pairing policy: `channels.zalo.dmPolicy` (e.g., pairing/allowlist/open/disabled).
- Webhook configuration:
  - `channels.zalo.webhookUrl`
  - `channels.zalo.webhookSecret`
  - `channels.zalo.webhookPath`

## 3) Webhook vs polling
- Webhook: configure a public HTTPS endpoint and verify requests.
- Polling: run a long-lived worker and store the latest cursor.

## 4) Operational hygiene
- Rotate tokens if compromised.
- Keep separate tokens for dev and prod.


path: references/zalo-n8n-automation.md
content: # n8n Automation Notes

## Recommended approach
- Use the built-in HTTP Request node for bot API calls.
- Keep tokens in credentials or environment variables.

## Community nodes
- If you evaluate third-party nodes (e.g., "n8n-nodes-ultimate"), verify source, maintenance, and security posture before production use.

## Safety
- Do not store cookies or tokens in workflow JSON exports.
- Apply rate limiting and retry backoff.


path: references/zalo-bot-ux-playbook.md
content: # Bot UX Playbook

## Command set (baseline)
- "help": show capabilities and examples
- "status": show latest job result or queue state
- "settings": allow toggles via quick replies if available

## Conversation patterns
- Acknowledge quickly, then do heavy work asynchronously.
- Keep responses short and action-oriented.
- Always provide a next step or suggestion.

## Error handling UX
- For unknown input, send a gentle fallback + examples.
- Avoid repeating the same fallback in a loop.


path: references/zalo-bot-webhook-routing.md
content: # Webhook and Polling Routing

## 1) Webhook handling
- Verify incoming requests using the configured webhook secret.
- When `webhookSecret` is set, validate the `X-Bot-Api-Secret-Token` header.
- Respond quickly; process asynchronously.
- De-duplicate events by message ID or event ID.

## 2) Polling handling
- Store and advance the cursor/offset.
- Make handlers idempotent to survive retries.

## 3) Routing rules
- If a postback/callback exists, handle it before plain text.
- Route by intent or command first; fallback last.


path: references/zalo-bot-overview.md
content: # Zalo Bot Platform Overview

## 1) Scope
- Bot API is focused on 1:1 DM conversations.
- Group support is typically not available (or marked as “coming soon”).

## 2) Delivery models
- Long polling is commonly used by default.
- Webhook mode is available when you provide a public HTTPS endpoint.

## 3) Key constraints (typical)
- Outbound text is chunked around 2000 characters.
- Media uploads/downloads are capped (default 5 MB in OpenClaw).
- Users must be paired/approved before you can message them.

## 4) Token usage
- A bot token is required for send and management calls.
- Store tokens securely and rotate if compromised.

## 5) Reliability
- Expect retries and handle duplicate events.
- Use backoff on rate limits.


path: references/zalo-bot-messaging-capabilities.md
content: # Bot Messaging Capabilities (Checklist)

> Note: Confirm exact method names and payloads in the official Zalo Bot Platform docs.

## Core outbound
- Send text messages
- Send images or files (within size limits)
- Send rich/structured messages if supported
- Show typing/acknowledge states if supported

## Inbound handling
- Receive user text messages
- Receive attachments
- Receive postback or button events (if supported)

## User and conversation
- Fetch user profile metadata (if permitted)
- Track conversation context per user
- Respect opt-in / pairing requirements

## Moderation and safety
- Reject unsupported content types
- Throttle outbound messages
- Filter or sanitize user input


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)