Zalo

Zalo

Overview

Use this skill to turn Zalo requests into safe, concrete Codex work. Prefer the official API for integrations and use Browser or Computer Use only for user-facing Zalo web/desktop workflows that do not have a reliable API path.

Decision Flow

1. Classify the request:
   • OA/OpenAPI, ZNS/ZBS, Social API, OAuth, webhook, or backend integration.
   • Browser/Computer Use task against Zalo web or the Windows Zalo app.
   • Content/operations task such as drafting replies, campaign copy, or SOPs.
2. For API work, load references/official-sources.md when exact endpoints, scopes, quotas, or policy constraints matter. Verify current details against official Zalo docs before implementing production behavior.
3. Check credentials without exposing them. Run scripts/zalo_env_check.py before live calls.
4. Use a dry-run or draft-first workflow for anything that sends messages, changes OA settings, updates templates, or modifies customer data.

Credential Rules

• Never ask the user to paste access tokens, refresh tokens, app secrets, phone numbers, or customer lists into chat when an environment variable, local secret file, or existing app config can be used.
• Never print full secrets in final answers, logs, or command summaries. Redact to the first and last 4 characters when needed.
• Prefer these environment variables:
  • ZALO_APP_ID
  • ZALO_SECRET_KEY
  • ZALO_OA_ACCESS_TOKEN
  • ZALO_OA_REFRESH_TOKEN
  • ZALO_API_BASE optional, defaulting to https://openapi.zalo.me
• If a token refresh produces a new refresh token, tell the user where it was written or that it must replace the previous value. Do not silently discard it.

API Work

Use the bundled scripts for repeatable checks and small manual calls:

python scripts/zalo_env_check.py --profile oa
python scripts/zalo_oa_refresh.py --dry-run
python scripts/zalo_oa_request.py GET /v3.0/oa/profile
python scripts/zalo_oa_request.py POST /v3.0/oa/message/cs --json payload.json

For implementation work:

• Keep endpoint paths and payload shapes close to official docs or to the user's existing integration.
• Use access_token request header for OA OpenAPI calls unless the current official docs for that endpoint specify another authentication scheme.
• Treat ZNS/ZBS/template messages as policy-bound: verify consent, allowed template category, quota, and template approval before sending.
• Add retries only for transient failures. Do not retry sends blindly if the API may have accepted the message.
• Store webhook verification secrets server-side. Log event IDs and timestamps, not full customer payloads.

Browser And Desktop Work

Use the Browser plugin for local/web targets and Computer Use for the Windows Zalo app. Ask the user to complete login, QR, OTP, or 2FA steps themselves.

Before sending or changing live data:

• Identify the exact target account, OA, chat, user, or group.
• Prepare the content and show the user the action summary.
• Require explicit current-turn confirmation for sends, deletes, broadcasts, template submissions, or account setting changes.

Message And Data Safety

• Separate drafting from sending.
• Do not mass-message, scrape contacts, bypass user consent, or automate spam-like behavior.
• Minimize PII in prompts, logs, and generated files. Redact phone numbers and customer IDs unless exact values are required for the task.
• For marketing or notification workflows, flag the need to confirm Zalo policy, user consent, and template approval.

References

• references/official-sources.md: official Zalo documentation links and current OAuth OA notes.
• references/api-patterns.md: environment variables, request patterns, error-handling guidance.

When the user's request depends on exact current Zalo limits, scopes, message formats, or compliance rules, browse official Zalo docs before answering or editing production code.