Zalo

Estado: Experimental. Actualmente soporta solo DM (1:1); soporte grupal está "próximamente" según docs de Zalo.

Zalo se proporciona como plugin y no viene incluido con la instalación core.

- Instalación CLI: openclaw plugins install @openclaw/zalo

- O selecciona Zalo en onboarding y confirma el prompt de instalación

- Detalles: ''/plugin''

1. Instala el plugin Zalo:

- Desde checkout de source: openclaw plugins install ./extensions/zalo

- Desde npm (si está publicado): openclaw plugins install @openclaw/zalo

- O selecciona Zalo en onboarding y confirma el prompt de instalación

2. Configura el token:

- Env: ZALO_BOT_TOKEN=...

- O config: channels.zalo.botToken: "...".

3. Reinicia el gateway (o completa onboarding).

4. DM por defecto usa emparejamiento: primer contacto recibe código de emparejamiento, aprueba para procesar mensajes.

Configuración mínima:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

Zalo es una app de mensajería popular en Vietnam; Bot API permite al Gateway ejecutar un bot 1:1. Adecuado para escenarios de soporte/notificación (necesita enrutamiento determinístico de vuelta a Zalo).

- Un canal Zalo Bot API gestionado por Gateway.

- Enrutamiento determinístico: las respuestas solo van de vuelta a Zalo, el modelo no elegirá canal.

- Los DMs comparten sesión principal del agente.

- Chat grupal aún no soportado (docs de Zalo dicen "próximamente").

#

1. Open https://bot.zaloplatforms.com and log in.

2. Create a new bot and complete setup.

3. Copy bot token (format: 12345689:abc-xyz).

#

Example:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

Environment variable method: ZALO_BOT_TOKEN=... (only applies to default account).

Multi-account: use channels.zalo.accounts to configure each account's token (optional name).

3. Restart gateway. Zalo starts when token is resolvable (env or config).

4. DM defaults to pairing: approve pairing code on first contact.

- Inbound messages are normalized to generic channel envelope (with media placeholders).

- Replies always go back to same Zalo chat.

- Defaults to long-polling; can enable webhook mode via channels.zalo.webhookUrl.

- Outbound text segmented by 2000 characters (Zalo API limit).

- Media download/upload limit: channels.zalo.mediaMaxMb (default 5MB).

- Streaming disabled by default due to 2000 character limit making streaming less meaningful.

#

- Default: channels.zalo.dmPolicy = "pairing". Unknown senders receive pairing code; messages ignored before approval (pairing code expires in 1 hour).

- Approve:

- openclaw pairing list zalo

- openclaw pairing approve zalo <CODE>

- Pairing is default token exchange. Details: ''/start/pairing''

- channels.zalo.allowFrom only accepts numeric user IDs (no username lookup).

- Default: long-polling (no public URL required).

- Webhook mode: set channels.zalo.webhookUrl and channels.zalo.webhookSecret.

- Secret must be 8–256 characters.

- Webhook URL must be HTTPS.

- Zalo uses X-Bot-Api-Secret-Token header for verification.

- Gateway handles webhook at channels.zalo.webhookPath (defaults to webhook URL's path).

Note: Per Zalo API docs, getUpdates (polling) and webhook are mutually exclusive.

- Text: Fully supported (2000 character segmentation).

- Images: Supports downloading/processing inbound images; outbound via sendPhoto.

- Stickers: Logged but not fully processed (usually doesn't trigger agent reply).

- Unsupported types: Only logged (e.g., messages from protected users).

| Feature | Status |

| -- |

| DM | ✅ Supported |

| Group chat | ❌ Zalo docs say coming soon |

| Media (images) | ✅ Supported |

| Reactions | ❌ Not supported |

| Threads | ❌ Not supported |

| Polls | ❌ Not supported |

| Native tokens | ❌ Not supported |

| Streaming | ⚠️ Disabled by default (2000 char limit) |

- target uses chat id.

- Example: openclaw message send --channel zalo --target 123456789 --message "hi".

Bot not responding:

- Use openclaw channels status --probe to check if token is valid

- Confirm sender is approved (pairing or allowFrom)

- Check logs: openclaw logs --follow

Webhook not receiving events:

- Confirm webhook URL is HTTPS

- Confirm secret length is 8–256 characters

- Confirm gateway's HTTP endpoint is reachable at configured path

- Confirm getUpdates polling is not running (mutually exclusive)

Full configuration: ''/gateway/configuration''

Provider options:

- channels.zalo.enabled

- channels.zalo.botToken

- channels.zalo.tokenFile (read from file)

- channels.zalo.dmPolicy: pairing | allowlist | open | disabled (default pairing)

- channels.zalo.allowFrom: DM allowlist (user IDs); open requires "*"; wizard asks for numeric ID

- channels.zalo.mediaMaxMb: Inbound/outbound media limit (MB, default 5)

- channels.zalo.webhookUrl: Enable webhook mode (requires HTTPS)

- channels.zalo.webhookSecret: Webhook secret (8–256 characters)

- channels.zalo.webhookPath: Gateway's webhook path

- channels.zalo.proxy: Proxy URL for API requests

Multi-account options:

- channels.zalo.accounts.<id>.botToken

- channels.zalo.accounts.<id>.tokenFile

- channels.zalo.accounts.<id>.name

- channels.zalo.accounts.<id>.enabled

- channels.zalo.accounts.<id>.dmPolicy

- channels.zalo.accounts.<id>.allowFrom

- channels.zalo.accounts.<id>.webhookUrl

- channels.zalo.accounts.<id>.webhookSecret

- channels.zalo.accounts.<id>.webhookPath

- channels.zalo.accounts.<id>.proxy