Zalo

​

Plugin incluido

• Instalar: openclaw plugins install @openclaw/zalo
• Versión fijada: openclaw plugins install @openclaw/zalo@2026.6.11
• Desde un checkout 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, configura 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. Define el token, ya sea como env ZALO_BOT_TOKEN=... (solo cuenta predeterminada) o en la configuración.
3. Reinicia el Gateway.
4. Aprueba el código de emparejamiento en el primer contacto por mensaje directo (la política predeterminada de mensajes directos es emparejamiento).

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

​

Qué es

​

Cómo funciona

• Los mensajes entrantes se normalizan en el sobre de canal compartido con marcadores de posición para medios.
• Las respuestas siempre se enrutan de vuelta al mismo chat de Zalo; no se usa respuesta con cita (replyToMode está fijo como desactivado).
• Long-polling (getUpdates) de forma predeterminada; el modo Webhook está disponible mediante channels.zalo.webhookUrl.
• Los grupos requieren una @mención para activar el bot; esto no es configurable por canal.

​

Límites

​

Control de acceso

​

Mensajes directos

• channels.zalo.dmPolicy: pairing (predeterminado) | allowlist | open | disabled.
• Emparejamiento: los remitentes desconocidos reciben un código de emparejamiento; 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: Emparejamiento
• channels.zalo.allowFrom acepta IDs numéricos de usuario de Zalo (sin búsqueda de nombre de usuario). open requiere "*".

​

Grupos

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom restringe qué IDs de remitente pueden activar el bot en grupos; recurre a allowFrom cuando no está definido.
• Resolución predeterminada: cuando channels.zalo está configurado, un groupPolicy no definido se resuelve como open. Cuando channels.zalo falta por completo, el runtime falla de forma cerrada a allowlist.
• Advertencia reportada en el mundo real: en algunas configuraciones de bots de Marketplace, el bot no se pudo agregar a ningún grupo. Si te ocurre, verifica la configuración de Zalo Bot Platform de tu bot; es una restricción del lado de la plataforma, no una política de OpenClaw.

​

Long-polling frente a Webhook

• Predeterminado: long-polling (no requiere 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 eventos con un encabezado X-Bot-Api-Secret-Token, comprobado con una comparación en tiempo constante.
  • HTTP del Gateway gestiona las solicitudes 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 de medio +json).
  • El sondeo getUpdates y el Webhook son mutuamente excluyentes según la documentación de la API de Zalo.

​

Tipos de mensaje compatibles

• Texto: compatibilidad completa, fragmentado en 2000 caracteres.
• Medios: entrantes/salientes, limitados por mediaMaxMb.
• Reacciones, hilos, encuestas, comandos nativos: no compatibles con el Plugin.
• Streaming: el Plugin declara capacidad de streaming por bloques, pero Zalo no tiene controles dedicados de cola saliente/fusión de texto (a diferencia de algunos otros canales regionales); verifica el comportamiento actual en tu entorno si esto importa para tu caso de uso.

​

Capacidades

​

Destinos de entrega (CLI/Cron)

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

​

Solución de problemas

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

• Confirma que la URL del Webhook use HTTPS
• Confirma que el secreto tenga entre 8 y 256 caracteres
• Confirma que el endpoint HTTP del Gateway sea accesible en la ruta configurada
• Confirma que el sondeo 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 reintenta

​

Referencia de configuración

​

Relacionado

• Descripción general de canales - todos los canales compatibles
• Emparejamiento - autenticación de mensajes directos y flujo de emparejamiento
• Grupos - comportamiento de chats grupales y activación por mención
• Enrutamiento de canales - enrutamiento de sesiones para mensajes
• Seguridad - modelo de acceso y hardening