rune-ext-zalo

Register an OA app, implement the OAuth2 PKCE flow with dual token management, then send messages via the v3.0 /message/cs endpoint. Add a webhook server with signature verification and token auto-refresh middleware to handle expiring access tokens.

Run a webhook server and MCP server in the same Node.js process sharing an in-memory message queue. Expose tools like zalo_read_messages, zalo_send_message, and zalo_get_profile so the agent can poll incoming messages and reply through the OA API.

The OA API is the official, production-safe track for business chatbots using OAuth2 and webhooks. zca-js is an unofficial reverse-engineered library for personal accounts that violates Zalo's ToS and risks account bans, suitable only for prototypes and personal projects.

Error 12 means the user has not interacted with your OA in the last 7 days, so customer service messages are blocked. Use pre-approved Transaction or Promotion templates instead, which bypass the 7-day window.

Implement token-bucket rate limiting per endpoint with exponential backoff before any messaging call. Treat sustained HTTP 429 responses as a ban-risk signal and back off for at least 60 seconds rather than retrying immediately.

No. zca-js uses unofficial APIs that violate Zalo's Terms of Service, can break without notice, and risk permanent account suspension. For production business systems, use the Official Account API track instead.