> ## Documentation Index > Fetch the complete documentation index at: https://docs.fased.ai/llms.txt > Use this file to discover all available pages before exploring further. # Zalo # Zalo (Bot API) **Delivery:** Bundled. Zalo is the official bot path for teams or businesses that need to meet users inside the Zalo ecosystem. The plugin can long-poll by default or switch to a webhook model, while Fased keeps DM policy and group policy separate. Status: experimental. DMs are supported, and groups are available behind explicit policy controls. ## Setup from Agent > Channels Zalo ships with Fased as a local bundled channel extension. You do not need to download an npm package in a normal install. Open **Agents**, select the Agent, then use **Agent > Channels > Zalo**. Enter the bot token, save the channel, then restart the gateway if the UI reports that the runtime still needs to load. ## Quick setup (beginner) If you are just starting, use long-polling first. Move to webhook mode only when you need it and can expose a dedicated HTTPS path safely. 1. Set the token: * Env: `ZALO_BOT_TOKEN=...` * Or **Agent > Channels > Zalo**. 2. Restart the gateway if the UI asks for it. 3. DM access is pairing by default; approve the pairing code on first contact. Minimal config: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalo: { enabled: true, botToken: "12345689:abc-xyz", dmPolicy: "pairing", }, }, } ``` ## What it is Zalo is a Vietnam-focused messaging app. Its Bot API lets the Gateway run a bot for 1:1 conversations. It is a good fit for support or notifications where you want deterministic routing back to Zalo. * A Zalo Bot API channel owned by the Gateway. * Deterministic routing: replies go back to Zalo; the model never chooses channels. * DMs share the agent's main session. * Groups are supported with policy controls and default to fail-closed allowlist behavior. ## Setup (fast path) ### 1) Create a bot token (Zalo Bot Platform) 1. Go to [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) and sign in. 2. Create a new bot and configure its settings. 3. Copy the bot token (format: `12345689:abc-xyz`). ### 2) Configure the token (env or config) Example: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalo: { enabled: true, botToken: "12345689:abc-xyz", dmPolicy: "pairing", }, }, } ``` Env option: `ZALO_BOT_TOKEN=...` (works for the default account only). Multi-account support uses `channels.zalo.accounts` with per-account tokens and optional `name`. 3. Restart the gateway. Zalo starts when a token is resolved (env or config). 4. DM access defaults to pairing. Approve the code when the bot is first contacted. ## How it works (behavior) * Inbound messages are normalized into the shared channel envelope with media placeholders. * Replies always route back to the same Zalo chat. * Long-polling by default; webhook mode available with `channels.zalo.webhookUrl`. ## Limits * Outbound text is chunked to 2000 characters (Zalo API limit). * Media downloads/uploads are capped by `channels.zalo.mediaMaxMb` (default 5). * Streaming is blocked by default due to the 2000 char limit making streaming less useful. ## Access control (DMs) ### DM access * Default: `channels.zalo.dmPolicy = "pairing"`. Unknown senders receive a pairing code. Messages wait for approval, and codes expire after 1 hour. * Approve via: * `fased pairing list zalo` * `fased pairing approve zalo ` * Pairing is the default token exchange. Details: [Pairing](/channels/pairing) * `channels.zalo.allowFrom` accepts numeric user IDs (no username lookup available). ## Access control (Groups) * `channels.zalo.groupPolicy` controls group inbound handling: `open | allowlist | disabled`. * Default behavior is fail-closed: `allowlist`. * `channels.zalo.groupAllowFrom` restricts which sender IDs can trigger the bot in groups. * If `groupAllowFrom` is unset, Zalo falls back to `allowFrom` for sender checks. * `groupPolicy: "disabled"` blocks all group messages. * `groupPolicy: "open"` allows any group member (mention-gated). * Runtime note: if `channels.zalo` is missing entirely, runtime still falls back to `groupPolicy="allowlist"` for safety. ## Long-polling vs webhook * Default: long-polling (no public URL required). * Webhook mode: set `channels.zalo.webhookUrl` and `channels.zalo.webhookSecret`. * The webhook secret must be 8-256 characters. * Webhook URL must use HTTPS. * Zalo sends events with `X-Bot-Api-Secret-Token` header for verification. * Gateway HTTP handles webhook requests at `channels.zalo.webhookPath`. * Requests must use `Content-Type: application/json` (or `+json` media types). * Duplicate events (`event_name + message_id`) are ignored for a short replay window. * Burst traffic is rate-limited per path/source and may return HTTP 429. Note: getUpdates polling and webhook mode are mutually exclusive per Zalo API docs. ## Supported message types * **Text messages**: Full support with 2000 character chunking. * **Image messages**: Download and process inbound images; send images via `sendPhoto`. * **Stickers**: Logged but not fully processed (no agent response). * **Unsupported types**: Logged (e.g., messages from protected users). ## Capabilities | Feature | Status | | --------------- | -------------------------------------------------------- | | Direct messages | ✅ Supported | | Groups | ⚠️ Supported with policy controls (allowlist by default) | | Media (images) | ✅ Supported | | Reactions | ❌ Not supported | | Threads | ❌ Not supported | | Polls | ❌ Not supported | | Native commands | ❌ Not supported | | Streaming | ⚠️ Blocked (2000 char limit) | ## Delivery targets (CLI/cron) * Use a chat id as the target. * Example: `fased message send --channel zalo --target 123456789 --message "hi"`. ## Troubleshooting **Bot doesn't respond:** * Check that the token is valid: `fased channels status --probe` * Verify the sender is approved (pairing or allowFrom) * Check gateway logs: `fased logs --follow` **Webhook not receiving events:** * Ensure webhook URL uses HTTPS * Verify secret token is 8-256 characters * Confirm the gateway HTTP endpoint is reachable on the configured path * Check that getUpdates polling is not running (they're mutually exclusive) ## Configuration reference (Zalo) Full configuration: [Configuration](/gateway/configuration) Provider options: * `channels.zalo.enabled`: enable/disable channel startup. * `channels.zalo.botToken`: bot token from Zalo Bot Platform. * `channels.zalo.tokenFile`: read token from file path. * `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing). * `channels.zalo.allowFrom`: DM allowlist (user IDs). `open` requires `"*"`. The wizard will ask for numeric IDs. * `channels.zalo.groupPolicy`: `open | allowlist | disabled` (default: allowlist). * `channels.zalo.groupAllowFrom`: group sender allowlist (user IDs). Falls back to `allowFrom` when unset. * `channels.zalo.mediaMaxMb`: inbound/outbound media cap (MB, default 5). * `channels.zalo.webhookUrl`: enable webhook mode (HTTPS required). * `channels.zalo.webhookSecret`: webhook secret (8-256 chars). * `channels.zalo.webhookPath`: webhook path on the gateway HTTP server. * `channels.zalo.proxy`: proxy URL for API requests. Multi-account options: * `channels.zalo.accounts..botToken`: per-account token. * `channels.zalo.accounts..tokenFile`: per-account token file. * `channels.zalo.accounts..name`: display name. * `channels.zalo.accounts..enabled`: enable/disable account. * `channels.zalo.accounts..dmPolicy`: per-account DM policy. * `channels.zalo.accounts..allowFrom`: per-account allowlist. * `channels.zalo.accounts..groupPolicy`: per-account group policy. * `channels.zalo.accounts..groupAllowFrom`: per-account group sender allowlist. * `channels.zalo.accounts..webhookUrl`: per-account webhook URL. * `channels.zalo.accounts..webhookSecret`: per-account webhook secret. * `channels.zalo.accounts..webhookPath`: per-account webhook path. * `channels.zalo.accounts..proxy`: per-account proxy URL.