@symerian/symi 3.0.21 → 3.0.22

package/docs/channels/whatsapp.md

@@ -1,444 +0,0 @@
----
-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).
-
-<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>
-
-## Onboarding
-
-<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
-symi channels login --channel whatsapp
-```
-
-    For a specific account:
-
-```bash
-symi channels login --channel whatsapp --account work
-```
-
-  </Step>
-
-  <Step title="Start the gateway">
-
-```bash
-symi gateway
-```
-
-  </Step>
-
-  <Step title="Approve first pairing request (if using pairing mode)">
-
-```bash
-symi pairing list whatsapp
-symi pairing approve whatsapp <CODE>
-```
-
-    Pairing requests expire after 1 hour. Pending requests are capped at 3 per channel.
-
-  </Step>
-</Steps>
-
-<Note>
-Symi recommends running WhatsApp on a separate number when possible. (The channel metadata and onboarding 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 Symi
-    - 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 Symi 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 effectively `open`.
-
-  </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 `[symi]`
-
-## 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 cap for auto-replies: `agents.defaults.mediaMaxMb` (default `5MB`)
-    - 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: `~/.symi/credentials/whatsapp/<accountId>/creds.json`
-    - backup file: `creds.json.bak`
-    - legacy default auth in `~/.symi/credentials/` is still recognized/migrated for default-account flows
-  </Accordion>
-
-  <Accordion title="Logout behavior">
-    `symi 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
-    symi channels login --channel whatsapp
-    symi channels status
-    ```
-
-  </Accordion>
-
-  <Accordion title="Linked but disconnected / reconnect loop">
-    Symptom: linked account with repeated disconnects or reconnect attempts.
-
-    Fix:
-
-    ```bash
-    symi doctor
-    symi 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 `symi.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
-
-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

@@ -1,192 +0,0 @@
----
-summary: "Zalo bot support status, capabilities, and configuration"
-read_when:
-  - Working on Zalo features or webhooks
-title: "Zalo"
----
-
-# Zalo (Bot API)
-
-Status: experimental. Direct messages only; groups coming soon per Zalo docs.
-
-## Plugin required
-
-Zalo ships as a plugin and is not bundled with the core install.
-
-- Install via CLI: `symi plugins install @symi/zalo`
-- Or select **Zalo** during onboarding and confirm the install prompt
-- Details: [Plugins](/tools/plugin)
-
-## Onboarding
-
-1. Install the Zalo plugin:
-   - From a source checkout: `symi plugins install ./extensions/zalo`
-   - From npm (if published): `symi plugins install @symi/zalo`
-   - Or pick **Zalo** in onboarding and confirm the install prompt
-2. Set the token:
-   - Env: `ZALO_BOT_TOKEN=...`
-   - Or config: `channels.zalo.botToken: "..."`.
-3. Restart the gateway (or finish onboarding).
-4. DM access is pairing by default; approve the pairing code on first contact.
-
-Minimal config:
-
-```json5
-{
-  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 not yet supported (Zalo docs state "coming soon").
-
-## Onboarding (quick 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
-{
-  channels: {
-    zalo: {
-      enabled: true,
-      botToken: "12345689:abc-xyz",
-      dmPolicy: "pairing",
-    },
-  },
-}
-```
-
-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:
-  - `symi pairing list zalo`
-  - `symi 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).
-
-## 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
-
-- **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          | ❌ Coming soon (per Zalo docs) |
-| 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: `symi message send --channel zalo --target 123456789 --message "hi"`.
-
-## Troubleshooting
-
-**Bot doesn't respond:**
-
-- Check that the token is valid: `symi channels status --probe`
-- Verify the sender is approved (pairing or allowFrom)
-- Check gateway logs: `symi 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
-
-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.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 token file.
-- `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>.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.