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 independiente.

En una compilación anterior o una instalación personalizada que excluya Zalo, instale 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. Cree un token de bot en https://bot.zaloplatforms.com (inicie sesión, cree un bot y configure los ajustes). El token es 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. Establezca el token, ya sea mediante la variable de entorno ZALO_BOT_TOKEN=... (solo para la cuenta predeterminada) o en la configuración.
3. Reinicie el Gateway.
4. Apruebe 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ñada más entradas en channels.zalo.accounts.<id>, cada una con sus propios botToken/name. channels.zalo.botToken (plana, sin accounts) es una abreviatura 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 1:1 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 interfaz de producto diferente y pueden comportarse de forma distinta; esta página no los abarca.

Cómo funciona

• Los mensajes entrantes se normalizan en el sobre de canal compartido con marcadores de posición para contenido multimedia.
• Las respuestas siempre se enrutan de vuelta al mismo chat de Zalo; no se utilizan respuestas con cita (replyToMode está desactivado de forma fija).
• De forma predeterminada, se utiliza sondeo prolongado (getUpdates); el modo Webhook está disponible mediante channels.zalo.webhookUrl.
• Los grupos requieren 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 apruebe. Los códigos caducan después de 1 hora.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Detalles: Vinculación
• channels.zalo.allowFrom acepta identificadores numéricos de usuario de Zalo (sin búsqueda por nombre de usuario). open requiere "*".

Grupos

El Plugin admite chats grupales (chatTypes: ["direct", "group"]) y estos están 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 remitente pueden activar el bot en grupos; si no está establecido, utiliza allowFrom como alternativa.
• Resolución predeterminada: cuando channels.zalo está configurado, un valor no establecido de groupPolicy se resuelve como open. Cuando channels.zalo falta por completo, 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 pudo añadirse a ningún grupo. Si ocurre, compruébelo en los ajustes de Zalo Bot Platform del bot; se trata de una restricción de la plataforma, no de una política de OpenClaw.

Sondeo prolongado frente a Webhook

• Valor predeterminado: sondeo prolongado (no se requiere una URL pública).
• Modo Webhook: establezca channels.zalo.webhookUrl y channels.zalo.webhookSecret.
  • La URL del Webhook debe utilizar HTTPS.
  • El secreto del Webhook debe tener entre 8 y 256 caracteres.
  • Zalo envía eventos con una cabecera X-Bot-Api-Secret-Token, que se comprueba mediante una comparación de tiempo constante.
  • El HTTP del Gateway gestiona las solicitudes del Webhook en channels.zalo.webhookPath (de forma predeterminada, la ruta de la URL del Webhook).
  • Las solicitudes deben utilizar Content-Type: application/json (o un tipo multimedia +json).
  • HTTP 200 solo se devuelve después de que el evento sin procesar se almacene de forma persistente; los fallos de almacenamiento devuelven HTTP 500.
  • Según la documentación de la API de Zalo, el sondeo 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: no son compatibles con el Plugin.
• Transmisión: el Plugin declara la capacidad de transmisión por bloques, pero Zalo no dispone de opciones específicas para ajustar la cola de salida ni la combinación de texto (a diferencia de otros canales regionales); si esto es importante para el caso de uso, compruebe el comportamiento actual en su entorno.

Capacidades

Destinos de entrega (CLI/Cron)

Utilice un ID de chat como destino:

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

Solución de problemas

El bot no responde:

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

El Webhook no recibe eventos:

• Confirme que la URL del Webhook utiliza HTTPS
• Confirme que el secreto tiene entre 8 y 256 caracteres
• Confirme que se puede acceder al extremo HTTP del Gateway en la ruta configurada
• Confirme que el sondeo getUpdates no se esté ejecutando también (son mutuamente excluyentes)
• Una ráfaga de solicitudes puede devolver HTTP 429 (120 solicitudes / 60s por ruta+IP); espere y vuelva 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 abreviatura heredada para una sola cuenta de los campos anteriores; se admiten ambas formas.

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

Contenido 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