@quantumclaw/quantumclaw 2026.3.22

package/docs/channels/whatsapp.md

@@ -0,0 +1,460 @@
+---
+summary: "WhatsApp channel support, access controls, delivery behavior, and operations"
+read_when:
+  - Working on WhatsApp/web channel behavior or inbox routing
+title: "WhatsApp"
+---
+
+# WhatsApp (Web channel)
+
+Status: production-ready via WhatsApp Web (Baileys). Gateway owns linked session(s).
+
+## Install (on demand)
+
+- Onboarding (`quantumclaw onboard`) and `quantumclaw channels add --channel whatsapp`
+  prompt to install the WhatsApp plugin the first time you select it.
+- `quantumclaw channels login --channel whatsapp` also offers the install flow when
+  the plugin is not present yet.
+- Dev channel + git checkout: defaults to the local plugin path.
+- Stable/Beta: defaults to the npm package `@quantumclaw/whatsapp`.
+
+Manual install stays available:
+
+```bash
+quantumclaw plugins install @quantumclaw/whatsapp
+```
+
+<CardGroup cols={3}>
+  <Card title="Pairing" icon="link" href="/channels/pairing">
+    Default DM policy is pairing for unknown senders.
+  </Card>
+  <Card title="Channel troubleshooting" icon="wrench" href="/channels/troubleshooting">
+    Cross-channel diagnostics and repair playbooks.
+  </Card>
+  <Card title="Gateway configuration" icon="settings" href="/gateway/configuration">
+    Full channel config patterns and examples.
+  </Card>
+</CardGroup>
+
+## Quick setup
+
+<Steps>
+  <Step title="Configure WhatsApp access policy">
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      dmPolicy: "pairing",
+      allowFrom: ["+15551234567"],
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+15551234567"],
+    },
+  },
+}
+```
+
+  </Step>
+
+  <Step title="Link WhatsApp (QR)">
+
+```bash
+quantumclaw channels login --channel whatsapp
+```
+
+    For a specific account:
+
+```bash
+quantumclaw channels login --channel whatsapp --account work
+```
+
+  </Step>
+
+  <Step title="Start the gateway">
+
+```bash
+quantumclaw gateway
+```
+
+  </Step>
+
+  <Step title="Approve first pairing request (if using pairing mode)">
+
+```bash
+quantumclaw pairing list whatsapp
+quantumclaw pairing approve whatsapp <CODE>
+```
+
+    Pairing requests expire after 1 hour. Pending requests are capped at 3 per channel.
+
+  </Step>
+</Steps>
+
+<Note>
+QuantumClaw recommends running WhatsApp on a separate number when possible. (The channel metadata and setup flow are optimized for that setup, but personal-number setups are also supported.)
+</Note>
+
+## Deployment patterns
+
+<AccordionGroup>
+  <Accordion title="Dedicated number (recommended)">
+    This is the cleanest operational mode:
+
+    - separate WhatsApp identity for QuantumClaw
+    - clearer DM allowlists and routing boundaries
+    - lower chance of self-chat confusion
+
+    Minimal policy pattern:
+
+    ```json5
+    {
+      channels: {
+        whatsapp: {
+          dmPolicy: "allowlist",
+          allowFrom: ["+15551234567"],
+        },
+      },
+    }
+    ```
+
+  </Accordion>
+
+  <Accordion title="Personal-number fallback">
+    Onboarding supports personal-number mode and writes a self-chat-friendly baseline:
+
+    - `dmPolicy: "allowlist"`
+    - `allowFrom` includes your personal number
+    - `selfChatMode: true`
+
+    In runtime, self-chat protections key off the linked self number and `allowFrom`.
+
+  </Accordion>
+
+  <Accordion title="WhatsApp Web-only channel scope">
+    The messaging platform channel is WhatsApp Web-based (`Baileys`) in current QuantumClaw channel architecture.
+
+    There is no separate Twilio WhatsApp messaging channel in the built-in chat-channel registry.
+
+  </Accordion>
+</AccordionGroup>
+
+## Runtime model
+
+- Gateway owns the WhatsApp socket and reconnect loop.
+- Outbound sends require an active WhatsApp listener for the target account.
+- Status and broadcast chats are ignored (`@status`, `@broadcast`).
+- Direct chats use DM session rules (`session.dmScope`; default `main` collapses DMs to the agent main session).
+- Group sessions are isolated (`agent:<agentId>:whatsapp:group:<jid>`).
+
+## Access control and activation
+
+<Tabs>
+  <Tab title="DM policy">
+    `channels.whatsapp.dmPolicy` controls direct chat access:
+
+    - `pairing` (default)
+    - `allowlist`
+    - `open` (requires `allowFrom` to include `"*"`)
+    - `disabled`
+
+    `allowFrom` accepts E.164-style numbers (normalized internally).
+
+    Multi-account override: `channels.whatsapp.accounts.<id>.dmPolicy` (and `allowFrom`) take precedence over channel-level defaults for that account.
+
+    Runtime behavior details:
+
+    - pairings are persisted in channel allow-store and merged with configured `allowFrom`
+    - if no allowlist is configured, the linked self number is allowed by default
+    - outbound `fromMe` DMs are never auto-paired
+
+  </Tab>
+
+  <Tab title="Group policy + allowlists">
+    Group access has two layers:
+
+    1. **Group membership allowlist** (`channels.whatsapp.groups`)
+       - if `groups` is omitted, all groups are eligible
+       - if `groups` is present, it acts as a group allowlist (`"*"` allowed)
+
+    2. **Group sender policy** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
+       - `open`: sender allowlist bypassed
+       - `allowlist`: sender must match `groupAllowFrom` (or `*`)
+       - `disabled`: block all group inbound
+
+    Sender allowlist fallback:
+
+    - if `groupAllowFrom` is unset, runtime falls back to `allowFrom` when available
+    - sender allowlists are evaluated before mention/reply activation
+
+    Note: if no `channels.whatsapp` block exists at all, runtime group-policy fallback is `allowlist` (with a warning log), even if `channels.defaults.groupPolicy` is set.
+
+  </Tab>
+
+  <Tab title="Mentions + /activation">
+    Group replies require mention by default.
+
+    Mention detection includes:
+
+    - explicit WhatsApp mentions of the bot identity
+    - configured mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
+    - implicit reply-to-bot detection (reply sender matches bot identity)
+
+    Security note:
+
+    - quote/reply only satisfies mention gating; it does **not** grant sender authorization
+    - with `groupPolicy: "allowlist"`, non-allowlisted senders are still blocked even if they reply to an allowlisted user's message
+
+    Session-level activation command:
+
+    - `/activation mention`
+    - `/activation always`
+
+    `activation` updates session state (not global config). It is owner-gated.
+
+  </Tab>
+</Tabs>
+
+## Personal-number and self-chat behavior
+
+When the linked self number is also present in `allowFrom`, WhatsApp self-chat safeguards activate:
+
+- skip read receipts for self-chat turns
+- ignore mention-JID auto-trigger behavior that would otherwise ping yourself
+- if `messages.responsePrefix` is unset, self-chat replies default to `[{identity.name}]` or `[quantumclaw]`
+
+## Message normalization and context
+
+<AccordionGroup>
+  <Accordion title="Inbound envelope + reply context">
+    Incoming WhatsApp messages are wrapped in the shared inbound envelope.
+
+    If a quoted reply exists, context is appended in this form:
+
+    ```text
+    [Replying to <sender> id:<stanzaId>]
+    <quoted body or media placeholder>
+    [/Replying]
+    ```
+
+    Reply metadata fields are also populated when available (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164).
+
+  </Accordion>
+
+  <Accordion title="Media placeholders and location/contact extraction">
+    Media-only inbound messages are normalized with placeholders such as:
+
+    - `<media:image>`
+    - `<media:video>`
+    - `<media:audio>`
+    - `<media:document>`
+    - `<media:sticker>`
+
+    Location and contact payloads are normalized into textual context before routing.
+
+  </Accordion>
+
+  <Accordion title="Pending group history injection">
+    For groups, unprocessed messages can be buffered and injected as context when the bot is finally triggered.
+
+    - default limit: `50`
+    - config: `channels.whatsapp.historyLimit`
+    - fallback: `messages.groupChat.historyLimit`
+    - `0` disables
+
+    Injection markers:
+
+    - `[Chat messages since your last reply - for context]`
+    - `[Current message - respond to this]`
+
+  </Accordion>
+
+  <Accordion title="Read receipts">
+    Read receipts are enabled by default for accepted inbound WhatsApp messages.
+
+    Disable globally:
+
+    ```json5
+    {
+      channels: {
+        whatsapp: {
+          sendReadReceipts: false,
+        },
+      },
+    }
+    ```
+
+    Per-account override:
+
+    ```json5
+    {
+      channels: {
+        whatsapp: {
+          accounts: {
+            work: {
+              sendReadReceipts: false,
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    Self-chat turns skip read receipts even when globally enabled.
+
+  </Accordion>
+</AccordionGroup>
+
+## Delivery, chunking, and media
+
+<AccordionGroup>
+  <Accordion title="Text chunking">
+    - default chunk limit: `channels.whatsapp.textChunkLimit = 4000`
+    - `channels.whatsapp.chunkMode = "length" | "newline"`
+    - `newline` mode prefers paragraph boundaries (blank lines), then falls back to length-safe chunking
+  </Accordion>
+
+  <Accordion title="Outbound media behavior">
+    - supports image, video, audio (PTT voice-note), and document payloads
+    - `audio/ogg` is rewritten to `audio/ogg; codecs=opus` for voice-note compatibility
+    - animated GIF playback is supported via `gifPlayback: true` on video sends
+    - captions are applied to the first media item when sending multi-media reply payloads
+    - media source can be HTTP(S), `file://`, or local paths
+  </Accordion>
+
+  <Accordion title="Media size limits and fallback behavior">
+    - inbound media save cap: `channels.whatsapp.mediaMaxMb` (default `50`)
+    - outbound media send cap: `channels.whatsapp.mediaMaxMb` (default `50`)
+    - per-account overrides use `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
+    - images are auto-optimized (resize/quality sweep) to fit limits
+    - on media send failure, first-item fallback sends text warning instead of dropping the response silently
+  </Accordion>
+</AccordionGroup>
+
+## Acknowledgment reactions
+
+WhatsApp supports immediate ack reactions on inbound receipt via `channels.whatsapp.ackReaction`.
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      ackReaction: {
+        emoji: "👀",
+        direct: true,
+        group: "mentions", // always | mentions | never
+      },
+    },
+  },
+}
+```
+
+Behavior notes:
+
+- sent immediately after inbound is accepted (pre-reply)
+- failures are logged but do not block normal reply delivery
+- group mode `mentions` reacts on mention-triggered turns; group activation `always` acts as bypass for this check
+- WhatsApp uses `channels.whatsapp.ackReaction` (legacy `messages.ackReaction` is not used here)
+
+## Multi-account and credentials
+
+<AccordionGroup>
+  <Accordion title="Account selection and defaults">
+    - account ids come from `channels.whatsapp.accounts`
+    - default account selection: `default` if present, otherwise first configured account id (sorted)
+    - account ids are normalized internally for lookup
+  </Accordion>
+
+  <Accordion title="Credential paths and legacy compatibility">
+    - current auth path: `~/.quantumclaw/credentials/whatsapp/<accountId>/creds.json`
+    - backup file: `creds.json.bak`
+    - legacy default auth in `~/.quantumclaw/credentials/` is still recognized/migrated for default-account flows
+  </Accordion>
+
+  <Accordion title="Logout behavior">
+    `quantumclaw channels logout --channel whatsapp [--account <id>]` clears WhatsApp auth state for that account.
+
+    In legacy auth directories, `oauth.json` is preserved while Baileys auth files are removed.
+
+  </Accordion>
+</AccordionGroup>
+
+## Tools, actions, and config writes
+
+- Agent tool support includes WhatsApp reaction action (`react`).
+- Action gates:
+  - `channels.whatsapp.actions.reactions`
+  - `channels.whatsapp.actions.polls`
+- Channel-initiated config writes are enabled by default (disable via `channels.whatsapp.configWrites=false`).
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Not linked (QR required)">
+    Symptom: channel status reports not linked.
+
+    Fix:
+
+    ```bash
+    quantumclaw channels login --channel whatsapp
+    quantumclaw channels status
+    ```
+
+  </Accordion>
+
+  <Accordion title="Linked but disconnected / reconnect loop">
+    Symptom: linked account with repeated disconnects or reconnect attempts.
+
+    Fix:
+
+    ```bash
+    quantumclaw doctor
+    quantumclaw logs --follow
+    ```
+
+    If needed, re-link with `channels login`.
+
+  </Accordion>
+
+  <Accordion title="No active listener when sending">
+    Outbound sends fail fast when no active gateway listener exists for the target account.
+
+    Make sure gateway is running and the account is linked.
+
+  </Accordion>
+
+  <Accordion title="Group messages unexpectedly ignored">
+    Check in this order:
+
+    - `groupPolicy`
+    - `groupAllowFrom` / `allowFrom`
+    - `groups` allowlist entries
+    - mention gating (`requireMention` + mention patterns)
+    - duplicate keys in `quantumclaw.json` (JSON5): later entries override earlier ones, so keep a single `groupPolicy` per scope
+
+  </Accordion>
+
+  <Accordion title="Bun runtime warning">
+    WhatsApp gateway runtime should use Node. Bun is flagged as incompatible for stable WhatsApp/Telegram gateway operation.
+  </Accordion>
+</AccordionGroup>
+
+## Configuration reference pointers
+
+Primary reference:
+
+- [Configuration reference - WhatsApp](/gateway/configuration-reference#whatsapp)
+
+High-signal WhatsApp fields:
+
+- access: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`
+- delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`
+- multi-account: `accounts.<id>.enabled`, `accounts.<id>.authDir`, account-level overrides
+- operations: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`
+- session behavior: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms.<id>.historyLimit`
+
+## Related
+
+- [Pairing](/channels/pairing)
+- [Channel routing](/channels/channel-routing)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Troubleshooting](/channels/troubleshooting)

package/docs/channels/zalo.md

@@ -0,0 +1,243 @@
+---
+summary: "Zalo bot support status, capabilities, and configuration"
+read_when:
+  - Working on Zalo features or webhooks
+title: "Zalo"
+---
+
+# Zalo (Bot API)
+
+Status: experimental. DMs are supported. The [Capabilities](#capabilities) section below reflects current Marketplace-bot behavior.
+
+## Plugin required
+
+Zalo ships as a plugin and is not bundled with the core install.
+
+- Install via CLI: `quantumclaw plugins install @quantumclaw/zalo`
+- Or select **Zalo** during setup and confirm the install prompt
+- Details: [Plugins](/tools/plugin)
+
+## Quick setup (beginner)
+
+1. Install the Zalo plugin:
+   - From a source checkout: `quantumclaw plugins install ./extensions/zalo`
+   - From npm (if published): `quantumclaw plugins install @quantumclaw/zalo`
+   - Or pick **Zalo** in setup and confirm the install prompt
+2. Set the token:
+   - Env: `ZALO_BOT_TOKEN=...`
+   - Or config: `channels.zalo.accounts.default.botToken: "..."`.
+3. Restart the gateway (or finish setup).
+4. DM access is pairing by default; approve the pairing code on first contact.
+
+Minimal config:
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      accounts: {
+        default: {
+          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.
+
+This page reflects current QuantumClaw behavior for **Zalo Bot Creator / Marketplace bots**.
+**Zalo Official Account (OA) bots** are a different Zalo product surface and may behave differently.
+
+- 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.
+- The [Capabilities](#capabilities) section below shows current Marketplace-bot support.
+
+## 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 full bot token (typically `numeric_id:secret`). For Marketplace bots, the usable runtime token may appear in the bot's welcome message after creation.
+
+### 2) Configure the token (env or config)
+
+Example:
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      accounts: {
+        default: {
+          botToken: "12345689:abc-xyz",
+          dmPolicy: "pairing",
+        },
+      },
+    },
+  },
+}
+```
+
+If you later move to a Zalo bot surface where groups are available, you can add group-specific config such as `groupPolicy` and `groupAllowFrom` explicitly. For current Marketplace-bot behavior, see [Capabilities](#capabilities).
+
+Env option: `ZALO_BOT_TOKEN=...` (works for the default account only).
+
+Multi-account support: use `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 are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `quantumclaw pairing list zalo`
+  - `quantumclaw pairing approve zalo <CODE>`
+- Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
+- `channels.zalo.allowFrom` accepts numeric user IDs (no username lookup available).
+
+## Access control (Groups)
+
+For **Zalo Bot Creator / Marketplace bots**, group support was not available in practice because the bot could not be added to a group at all.
+
+That means the group-related config keys below exist in the schema, but were not usable for Marketplace bots:
+
+- `channels.zalo.groupPolicy` controls group inbound handling: `open | allowlist | disabled`.
+- `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.
+- Runtime note: if `channels.zalo` is missing entirely, runtime still falls back to `groupPolicy="allowlist"` for safety.
+
+The group policy values (when group access is available on your bot surface) are:
+
+- `groupPolicy: "disabled"` — blocks all group messages.
+- `groupPolicy: "open"` — allows any group member (mention-gated).
+- `groupPolicy: "allowlist"` — fail-closed default; only allowed senders are accepted.
+
+If you are using a different Zalo bot product surface and have verified working group behavior, document that separately rather than assuming it matches the Marketplace-bot flow.
+
+## 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` (defaults to the webhook URL path).
+  - 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 are mutually exclusive per Zalo API docs.
+
+## Supported message types
+
+For a quick support snapshot, see [Capabilities](#capabilities). The notes below add detail where the behavior needs extra context.
+
+- **Text messages**: Full support with 2000 character chunking.
+- **Plain URLs in text**: Behave like normal text input.
+- **Link previews / rich link cards**: See the Marketplace-bot status in [Capabilities](#capabilities); they did not reliably trigger a reply.
+- **Image messages**: See the Marketplace-bot status in [Capabilities](#capabilities); inbound image handling was unreliable (typing indicator without a final reply).
+- **Stickers**: See the Marketplace-bot status in [Capabilities](#capabilities).
+- **Voice notes / audio files / video / generic file attachments**: See the Marketplace-bot status in [Capabilities](#capabilities).
+- **Unsupported types**: Logged (for example, messages from protected users).
+
+## Capabilities
+
+This table summarizes current **Zalo Bot Creator / Marketplace bot** behavior in QuantumClaw.
+
+| Feature                     | Status                                  |
+| --------------------------- | --------------------------------------- |
+| Direct messages             | ✅ Supported                            |
+| Groups                      | ❌ Not available for Marketplace bots   |
+| Media (inbound images)      | ⚠️ Limited / verify in your environment |
+| Media (outbound images)     | ⚠️ Not re-tested for Marketplace bots   |
+| Plain URLs in text          | ✅ Supported                            |
+| Link previews               | ⚠️ Unreliable for Marketplace bots      |
+| Reactions                   | ❌ Not supported                        |
+| Stickers                    | ⚠️ No agent reply for Marketplace bots  |
+| Voice notes / audio / video | ⚠️ No agent reply for Marketplace bots  |
+| File attachments            | ⚠️ No agent reply for Marketplace bots  |
+| 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: `quantumclaw message send --channel zalo --target 123456789 --message "hi"`.
+
+## Troubleshooting
+
+**Bot doesn't respond:**
+
+- Check that the token is valid: `quantumclaw channels status --probe`
+- Verify the sender is approved (pairing or allowFrom)
+- Check gateway logs: `quantumclaw 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)
+
+The flat top-level keys (`channels.zalo.botToken`, `channels.zalo.dmPolicy`, and similar) are a legacy single-account shorthand. Prefer `channels.zalo.accounts.<id>.*` for new configs. Both forms are still documented here because they exist in the schema.
+
+Provider options:
+
+- `channels.zalo.enabled`: enable/disable channel startup.
+- `channels.zalo.botToken`: bot token from Zalo Bot Platform.
+- `channels.zalo.tokenFile`: read token from a regular file path. Symlinks are rejected.
+- `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). Present in config; see [Capabilities](#capabilities) and [Access control (Groups)](#access-control-groups) for current Marketplace-bot behavior.
+- `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.<id>.botToken`: per-account token.
+- `channels.zalo.accounts.<id>.tokenFile`: per-account regular token file. Symlinks are rejected.
+- `channels.zalo.accounts.<id>.name`: display name.
+- `channels.zalo.accounts.<id>.enabled`: enable/disable account.
+- `channels.zalo.accounts.<id>.dmPolicy`: per-account DM policy.
+- `channels.zalo.accounts.<id>.allowFrom`: per-account allowlist.
+- `channels.zalo.accounts.<id>.groupPolicy`: per-account group policy. Present in config; see [Capabilities](#capabilities) and [Access control (Groups)](#access-control-groups) for current Marketplace-bot behavior.
+- `channels.zalo.accounts.<id>.groupAllowFrom`: per-account group sender allowlist.
+- `channels.zalo.accounts.<id>.webhookUrl`: per-account webhook URL.
+- `channels.zalo.accounts.<id>.webhookSecret`: per-account webhook secret.
+- `channels.zalo.accounts.<id>.webhookPath`: per-account webhook path.
+- `channels.zalo.accounts.<id>.proxy`: per-account proxy URL.