Zalo

Estado: experimental. Tanto los mensajes directos como los chats grupales están implementados; la tabla de capacidades que aparece a continuación refleja el comportamiento verificado en bots de Zalo Bot Creator / Marketplace.

Plugin incluido

Zalo se distribuye como Plugin incluido en las versiones actuales de OpenClaw, por lo que las compilaciones empaquetadas no necesitan una instalación aparte.

En una compilación anterior o una instalación personalizada que excluya Zalo, instala directamente el paquete npm:

• Instalación: openclaw plugins install @openclaw/zalo
• Versión fijada: openclaw plugins install @openclaw/zalo@2026.6.11
• Desde un repositorio local: openclaw plugins install ./path/to/local/zalo-plugin
• Detalles: Plugins

Configuración rápida

1. Crea un token de bot en https://bot.zaloplatforms.com (inicia sesión, crea un bot y configura los ajustes). El token tiene el formato numeric_id:secret; en los bots de Marketplace, el token utilizable en tiempo de ejecución puede aparecer en el mensaje de bienvenida del bot.
2. Define el token mediante la variable de entorno ZALO_BOT_TOKEN=... (solo para la cuenta predeterminada) o en la configuración.
3. Reinicia el Gateway.
4. Aprueba el código de vinculación en el primer contacto por mensaje directo (la política predeterminada para mensajes directos es la vinculación).

Configuración mínima:

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

Varias cuentas: añade más entradas en channels.zalo.accounts.<id>, cada una con sus propios valores botToken/name. channels.zalo.botToken (plano, sin accounts) es una forma abreviada heredada para una sola cuenta; para configuraciones nuevas, se recomienda accounts.<id>.*.

Qué es

Zalo es una aplicación de mensajería orientada a Vietnam. Su API de bots permite que el Gateway ejecute un bot tanto para conversaciones individuales como para chats grupales, con enrutamiento determinista de vuelta a Zalo (el modelo nunca elige los canales).

Esta página trata sobre los bots de Zalo Bot Creator / Marketplace. Los bots de Zalo Official Account (OA) corresponden a una superficie de producto distinta y pueden comportarse de manera diferente; esta página no los cubre.

Cómo funciona

• Los mensajes entrantes se normalizan en el contenedor compartido del canal con marcadores de posición para contenido multimedia.
• Las respuestas siempre se enrutan de vuelta al mismo chat de Zalo; no se usan respuestas con cita (replyToMode está desactivado de forma fija).
• De forma predeterminada se usa sondeo prolongado (getUpdates); el modo Webhook está disponible mediante channels.zalo.webhookUrl.
• En los grupos se requiere una @mención para activar el bot; esto no se puede configurar por canal.

Límites

Control de acceso

Mensajes directos

• channels.zalo.dmPolicy: pairing (predeterminado) | allowlist | open | disabled.
• Vinculación: los remitentes desconocidos reciben un código de vinculación; los mensajes se ignoran hasta que se aprueba. Los códigos caducan al cabo de 1 hora.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Detalles: Vinculación
• channels.zalo.allowFrom acepta identificadores numéricos de usuarios de Zalo (sin búsqueda por nombre de usuario). open requiere "*".

Grupos

El Plugin admite chats grupales (chatTypes: ["direct", "group"]), sujetos a una mención y a la política de grupos:

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom restringe qué identificadores de remitentes pueden activar el bot en grupos; si no está definido, se utiliza allowFrom.
• Resolución predeterminada: cuando channels.zalo está configurado, un groupPolicy sin definir se resuelve como open. Cuando channels.zalo no existe en absoluto, el tiempo de ejecución adopta de forma segura allowlist.
• Advertencia observada en entornos reales: en algunas configuraciones de bots de Marketplace, el bot no se pudo añadir a ningún grupo. Si te ocurre, compruébalo en los ajustes de Zalo Bot Platform de tu bot; es una restricción de la plataforma, no una política de OpenClaw.

Sondeo prolongado frente a Webhook

• Valor predeterminado: sondeo prolongado (no se requiere una URL pública).
• Modo Webhook: define channels.zalo.webhookUrl y channels.zalo.webhookSecret.
  • La URL del Webhook debe usar HTTPS.
  • El secreto del Webhook debe tener entre 8 y 256 caracteres.
  • Zalo envía los eventos con una cabecera X-Bot-Api-Secret-Token, que se verifica mediante una comparación en tiempo constante.
  • El servidor HTTP del Gateway procesa las solicitudes del Webhook en channels.zalo.webhookPath (de forma predeterminada, la ruta de la URL del Webhook).
  • Las solicitudes deben usar Content-Type: application/json (o un tipo multimedia +json).
  • Según la documentación de la API de Zalo, el sondeo mediante getUpdates y el Webhook son mutuamente excluyentes.

Tipos de mensajes compatibles

• Texto: compatibilidad completa, dividido en fragmentos de 2000 caracteres.
• Contenido multimedia: entrante y saliente, limitado por mediaMaxMb.
• Reacciones, hilos, encuestas y comandos nativos: el Plugin no los admite.
• Transmisión: el Plugin declara la capacidad de transmisión por bloques, pero Zalo no dispone de controles específicos de ajuste para la cola saliente o la combinación de texto (a diferencia de otros canales regionales); si esto es importante para tu caso de uso, verifica el comportamiento actual en tu entorno.

Capacidades

Destinos de entrega (CLI/Cron)

Usa un identificador de chat como destino:

openclaw message send --channel zalo --target 123456789 --message "hi"

Solución de problemas

El bot no responde:

• Comprueba el token: openclaw channels status --probe
• Verifica que el remitente esté aprobado (vinculación o allowFrom)
• Comprueba los registros del Gateway: openclaw logs --follow

El Webhook no recibe eventos:

• Confirma que la URL del Webhook use HTTPS
• Confirma que el secreto tenga entre 8 y 256 caracteres
• Confirma que el punto de conexión HTTP del Gateway sea accesible en la ruta configurada
• Confirma que el sondeo mediante getUpdates no se esté ejecutando también (son mutuamente excluyentes)
• Una ráfaga de solicitudes puede devolver HTTP 429 (120 solicitudes / 60 s por ruta+IP); espera y vuelve a intentarlo

Referencia de configuración

Configuración completa: Configuración

channels.zalo.botToken, channels.zalo.dmPolicy y otras claves planas de nivel superior son la forma abreviada heredada para una sola cuenta de los campos anteriores; se admiten ambas formas.

Opción de entorno: ZALO_BOT_TOKEN=... solo se resuelve como el token de la cuenta predeterminada.

Relacionado

• Descripción general de los canales - todos los canales compatibles
• Vinculación - autenticación de mensajes directos y flujo de vinculación
• Grupos - comportamiento de los chats grupales y activación mediante menciones
• Enrutamiento de canales - enrutamiento de sesiones para mensajes
• Seguridad - modelo de acceso y refuerzo de seguridad