Configura Zalo Bot API en tu Gateway

Integrar un nuevo canal de mensajería suele ser un proceso tedioso cuando las configuraciones son complejas o las APIs no se comportan como esperas. Si necesitas dar soporte o enviar notificaciones en regiones específicas, contar con una conexión directa y estable es fundamental para que tus mensajes lleguen a su destino sin fricciones.

Zalo es una aplicación de mensajería enfocada en Vietnam y su Bot API permite que el Gateway gestione conversaciones 1:1. Es una opción ideal para flujos de soporte donde necesitas un enrutamiento determinista hacia la plataforma de origen.

Requisitos previos

• El plugin @openclaw/zalo instalado.
• Una cuenta en Zalo Bot Platform con un bot creado.
• Un bot token (formato: 12345689:abc-xyz).

Inicio rápido

Configura tu bot en menos de 5 minutos siguiendo estos pasos:

1. Instala el plugin: Usa el CLI para añadir la extensión: openclaw plugins install @openclaw/zalo (También puedes seleccionarlo durante el proceso de onboarding).

2. Configura el token: Puedes usar una variable de entorno ZALO_BOT_TOKEN=... o añadirlo directamente a tu archivo de configuración:

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

3. Reinicia el Gateway: El canal se activará en cuanto el token sea validado.

4. Vincula tu cuenta: Por defecto, el acceso por DM usa pairing. Cuando contactes al bot por primera vez, verás un código que debes aprobar para permitir la comunicación.

Funcionamiento y límites

El canal de Zalo en el Gateway normaliza los mensajes entrantes y asegura que las respuestas vuelvan siempre al chat original. Es importante que consideres estas restricciones técnicas:

• Mensajes de texto: El límite de la API de Zalo es de 2000 caracteres; el Gateway fragmentará automáticamente los textos que superen esta longitud.
• Streaming: Está bloqueado por defecto debido a las limitaciones de longitud de caracteres de la plataforma.
• Multimedia: Las descargas y subidas están limitadas a 5 MB por defecto mediante channels.zalo.mediaMaxMb.
• Grupos: Actualmente no están soportados (según los docs de Zalo, esta función llegará pronto).

Control de acceso (DMs)

Si utilizas la política de pairing, los remitentes desconocidos verán sus mensajes ignorados hasta que apruebes su código (que expira en 1 hora). Usa estos comandos:

• openclaw pairing list zalo
• openclaw pairing approve zalo <CODE>

Webhooks vs Long-polling

Por defecto, el plugin utiliza long-polling, por lo que no necesitas una URL pública. Si prefieres usar webhooks, debes configurar channels.zalo.webhookUrl (requiere HTTPS) y channels.zalo.webhookSecret (entre 8 y 256 caracteres). Ten en cuenta que ambos métodos son mutuamente excluyentes según la documentación oficial de Zalo.

Solución de problemas

El bot no responde:

• Verifica que el token sea válido con: openclaw channels status --probe.
• Comprueba que el remitente esté aprobado en la lista de pairing o allowFrom.
• Revisa los logs del sistema: openclaw logs --follow.

El webhook no recibe eventos:

• Asegúrate de que tu URL utiliza el protocolo HTTPS.
• Verifica que el Gateway sea alcanzable en la ruta configurada en channels.zalo.webhookPath.
• Confirma que no tienes activo el sistema de polling, ya que Zalo solo permite un método a la vez.

Si necesitas ayuda personalizada para tu configuración, consulta al AI Setup Assistant.

Próximos pasos

• Plugins
• Pairing
• Configuration Reference