Zalo (Bot API)

Estado: experimental. Los DMs son compatibles; el manejo de grupos está disponible con controles explícitos de política de grupo.

Plugin requerido

Zalo se distribuye como plugin y no viene incluido en la instalación base.

  • Instalar vía CLI: openclaw plugins install @openclaw/zalo
  • O selecciona Zalo durante el onboarding y confirma el prompt de instalación
  • Detalles: Plugins

Configuración rápida (principiante)

  1. Instala el plugin de Zalo:
    • Desde un checkout de código fuente: openclaw plugins install ./extensions/zalo
    • Desde npm (si está publicado): openclaw plugins install @openclaw/zalo
    • O elige Zalo en el onboarding y confirma el prompt de instalación
  2. Configura el token:
    • Variable de entorno: ZALO_BOT_TOKEN=...
    • O en configuración: channels.zalo.botToken: "...".
  3. Reinicia el gateway (o termina el onboarding).
  4. El acceso a DMs usa emparejamiento de forma predeterminada; aprueba el código de emparejamiento en el primer contacto.

Configuración mínima:

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

Qué es

Zalo es una app de mensajería enfocada en Vietnam; su Bot API permite al Gateway ejecutar un bot para conversaciones 1:1. Es una buena opción para soporte o notificaciones donde quieres enrutamiento determinista de vuelta a Zalo.

  • Un canal de Zalo Bot API propiedad del Gateway.
  • Enrutamiento determinista: las respuestas van de vuelta a Zalo; el modelo nunca elige canales.
  • Los DMs comparten la sesión principal del agente.
  • Los grupos son compatibles con controles de política (groupPolicy + groupAllowFrom) y por defecto usan comportamiento cerrado de lista de acceso.

Configuración (ruta rápida)

1) Crear un token de bot (Zalo Bot Platform)

  1. Ve a https://bot.zaloplatforms.com e inicia sesión.
  2. Crea un nuevo bot y configura sus ajustes.
  3. Copia el token del bot (formato: 12345689:abc-xyz).

2) Configurar el token (env o configuración)

Ejemplo:

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

Opción de entorno: ZALO_BOT_TOKEN=... (funciona solo para la cuenta predeterminada).

Soporte multi-cuenta: usa channels.zalo.accounts con tokens por cuenta y name opcional.

  1. Reinicia el gateway. Zalo se inicia cuando se resuelve un token (env o configuración).
  2. El acceso a DMs usa emparejamiento de forma predeterminada. Aprueba el código cuando el bot sea contactado por primera vez.

Cómo funciona (comportamiento)

  • Los mensajes entrantes se normalizan en el envelope compartido del canal con placeholders de multimedia.
  • Las respuestas siempre se enrutan de vuelta al mismo chat de Zalo.
  • Long-polling de forma predeterminada; modo webhook disponible con channels.zalo.webhookUrl.

Límites

  • El texto saliente se fragmenta a 2000 caracteres (límite de la API de Zalo).
  • Las descargas/subidas de multimedia están limitadas por channels.zalo.mediaMaxMb (predeterminado 5).
  • El streaming está bloqueado de forma predeterminada debido a que el límite de 2000 caracteres hace que sea poco útil.

Control de acceso (DMs)

Acceso a DMs

  • Predeterminado: channels.zalo.dmPolicy = "pairing". Los remitentes desconocidos reciben un código de emparejamiento; los mensajes se ignoran hasta que se aprueben (los códigos expiran después de 1 hora).
  • Aprobar vía:
    • openclaw pairing list zalo
    • openclaw pairing approve zalo <CODE>
  • El emparejamiento es el intercambio de token predeterminado. Detalles: Emparejamiento
  • channels.zalo.allowFrom acepta IDs numéricos de usuario (no hay búsqueda de nombre de usuario disponible).

Control de acceso (Grupos)

  • channels.zalo.groupPolicy controla el manejo de mensajes entrantes de grupo: open | allowlist | disabled.
  • El comportamiento predeterminado es cerrado: allowlist.
  • channels.zalo.groupAllowFrom restringe qué IDs de remitente pueden activar al bot en grupos.
  • Si groupAllowFrom no está configurado, Zalo recurre a allowFrom para verificaciones de remitente.
  • groupPolicy: "disabled" bloquea todos los mensajes de grupo.
  • groupPolicy: "open" permite a cualquier miembro del grupo (con restricción de mención).
  • Nota de ejecución: si channels.zalo no existe en absoluto, el runtime aún recurre a groupPolicy="allowlist" por seguridad.

Long-polling vs webhook

  • Predeterminado: long-polling (no se requiere URL pública).
  • Modo webhook: configura channels.zalo.webhookUrl y channels.zalo.webhookSecret.
    • El secreto del webhook debe tener entre 8 y 256 caracteres.
    • La URL del webhook debe usar HTTPS.
    • Zalo envía eventos con el encabezado X-Bot-Api-Secret-Token para verificación.
    • El HTTP del Gateway maneja solicitudes de webhook en channels.zalo.webhookPath (por defecto la ruta de la URL del webhook).
    • Las solicitudes deben usar Content-Type: application/json (o tipos de media +json).
    • Los eventos duplicados (event_name + message_id) se ignoran durante una ventana corta de replay.
    • El tráfico en ráfaga tiene límite de velocidad por ruta/fuente y puede devolver HTTP 429.

Nota: getUpdates (polling) y webhook son mutuamente excluyentes según la documentación de la API de Zalo.

Tipos de mensajes soportados

  • Mensajes de texto: Soporte completo con fragmentación a 2000 caracteres.
  • Mensajes de imagen: Descarga y procesamiento de imágenes entrantes; envío de imágenes vía sendPhoto.
  • Stickers: Se registran pero no se procesan completamente (sin respuesta del agente).
  • Tipos no soportados: Se registran (ej. mensajes de usuarios protegidos).

Capacidades

CaracterísticaEstado
Mensajes directosSoportado
GruposSoportado con controles de política (allowlist por defecto)
Multimedia (imágenes)Soportado
ReaccionesNo soportado
HilosNo soportado
EncuestasNo soportado
Comandos nativosNo soportado
StreamingBloqueado (límite de 2000 caracteres)

Destinos de entrega (CLI/cron)

  • Usa un ID de chat como destino.
  • Ejemplo: openclaw message send --channel zalo --target 123456789 --message "hola".

Resolución de problemas

El bot no responde:

  • Verifica que el token sea válido: openclaw channels status --probe
  • Verifica que el remitente esté aprobado (emparejamiento o allowFrom)
  • Revisa los logs del gateway: openclaw logs --follow

El webhook no recibe eventos:

  • Asegúrate de que la URL del webhook use HTTPS
  • Verifica que el token secreto tenga entre 8 y 256 caracteres
  • Confirma que el endpoint HTTP del gateway sea accesible en la ruta configurada
  • Verifica que el polling getUpdates no esté ejecutándose (son mutuamente excluyentes)

Referencia de configuración (Zalo)

Configuración completa: Configuración

Opciones del proveedor:

  • channels.zalo.enabled: habilitar/deshabilitar inicio del canal.
  • channels.zalo.botToken: token del bot de Zalo Bot Platform.
  • channels.zalo.tokenFile: leer token desde una ruta de archivo regular. Los symlinks se rechazan.
  • channels.zalo.dmPolicy: pairing | allowlist | open | disabled (predeterminado: pairing).
  • channels.zalo.allowFrom: lista de acceso DM (IDs de usuario). open requiere "*". El asistente pedirá IDs numéricos.
  • channels.zalo.groupPolicy: open | allowlist | disabled (predeterminado: allowlist).
  • channels.zalo.groupAllowFrom: lista de acceso de remitentes de grupo (IDs de usuario). Recurre a allowFrom cuando no está configurado.
  • channels.zalo.mediaMaxMb: límite de multimedia entrante/saliente (MB, predeterminado 5).
  • channels.zalo.webhookUrl: habilitar modo webhook (se requiere HTTPS).
  • channels.zalo.webhookSecret: secreto del webhook (8-256 caracteres).
  • channels.zalo.webhookPath: ruta del webhook en el servidor HTTP del gateway.
  • channels.zalo.proxy: URL del proxy para solicitudes API.

Opciones multi-cuenta:

  • channels.zalo.accounts.<id>.botToken: token por cuenta.
  • channels.zalo.accounts.<id>.tokenFile: archivo de token regular por cuenta. Los symlinks se rechazan.
  • channels.zalo.accounts.<id>.name: nombre para mostrar.
  • channels.zalo.accounts.<id>.enabled: habilitar/deshabilitar cuenta.
  • channels.zalo.accounts.<id>.dmPolicy: política de DM por cuenta.
  • channels.zalo.accounts.<id>.allowFrom: lista de acceso por cuenta.
  • channels.zalo.accounts.<id>.groupPolicy: política de grupo por cuenta.
  • channels.zalo.accounts.<id>.groupAllowFrom: lista de acceso de remitentes de grupo por cuenta.
  • channels.zalo.accounts.<id>.webhookUrl: URL de webhook por cuenta.
  • channels.zalo.accounts.<id>.webhookSecret: secreto de webhook por cuenta.
  • channels.zalo.accounts.<id>.webhookPath: ruta de webhook por cuenta.
  • channels.zalo.accounts.<id>.proxy: URL de proxy por cuenta.
arrow_back
Anterior
Whatsapp
Siguiente
Zalouser
arrow_forward