Modo de Devolución de Llamada de WeCom — Aplicaciones Personalizadas

Piénsalo como si le asignaras un buzón de oficina dedicado a tu asistente de IA—en lugar de tenerlo al acecho en chats grupales, le das su propio escritorio donde la gente puede acercarse y dejar mensajes directamente.

¿Cuál es la Gran Diferencia?

Hermes Agent te ofrece dos formas de conectar WeCom (WeChat Empresarial). El modo Bot es como un asistente amigable que se une a chats grupales—rápido de configurar, pero limitado. El modo callback es diferente: creas una aplicación personalizada que aparece en la barra lateral de WeCom de tus empleados, igual que cualquier aplicación oficial. Se siente nativo, soporta múltiples empresas y maneja mensajes cifrados de forma segura.

¿La desventaja? Necesitas un servidor público para recibir mensajes. Pero no te preocupes—un túnel simple como ngrok funciona bien para probar.

Cómo Funciona Realmente

Aquí está el flujo en términos sencillos:

Alguien envía un mensaje a tu aplicación personalizada en WeCom.
WeCom cifra ese mensaje y lo envía al endpoint HTTP de tu servidor.
Hermes lo descifra, lo pone en cola para el agente de IA e inmediatamente le dice a WeCom “recibido” (en silencio—el usuario no ve nada todavía).
El agente piensa durante 3 a 30 minutos (dependiendo de tu tarea).
Hermes envía la respuesta de vuelta de forma proactiva usando la API de mensajes de WeCom.

Sin sondeos. Sin demoras. Solo una conversación asíncrona y limpia.

Configuración Paso a Paso

1. Crea la Aplicación en el Panel de Administración de WeCom

Inicia sesión en la Consola de Administración de WeCom, ve a Aplicaciones → Crear aplicación.
Anota tu ID de Empresa (parte superior de la consola) y crea un Secreto de Empresa.
En la página de resumen de la aplicación, obtén el ID de Agente.

En Recibir Mensajes, configura:

URL: http://TU_IP_PUBLICA:8645/wecom/callback
Token: genera uno aleatorio
EncodingAESKey: genera una clave de 43 caracteres

2. Configura las Variables de Entorno

Añade estas a tu archivo .env:

WECOM_CALLBACK_CORP_ID = tu-id-de-empresa
WECOM_CALLBACK_CORP_SECRET = tu-secreto-de-empresa
WECOM_CALLBACK_AGENT_ID = 1000002
WECOM_CALLBACK_TOKEN = tu-token-de-callback
WECOM_CALLBACK_ENCODING_AES_KEY = tu-clave-aes-de-43-caracteres

# Opcional
WECOM_CALLBACK_PORT = 8645
WECOM_CALLBACK_ALLOWED_USERS = usuario1,usuario2

3. Inicia la Puerta de Enlace

hermes gateway

Nota: Solo usa hermes gateway start después de haber ejecutado hermes gateway install para registrar el servicio.

El adaptador de callback inicia un servidor HTTP en el puerto 8645. WeCom verificará la URL mediante una solicitud GET y luego comenzará a enviar mensajes mediante POST.

Referencia de Configuración

También puedes configurar estos parámetros en config.yaml bajo platforms.wecom_callback.extra:

Configuración	Valor Predeterminado	Descripción
`corp_id`	—	Obligatorio. Tu ID de Empresa de WeCom
`corp_secret`	—	Obligatorio. Secreto de la aplicación
`agent_id`	—	Obligatorio. ID de Agente de tu aplicación
`token`	—	Obligatorio. Token de verificación del callback
`encoding_aes_key`	—	Obligatorio. Clave AES de 43 caracteres
`host`	sin definir (doble pila)	Dirección de enlace para el servidor HTTP
`port`	8645	Puerto para el servidor de callback

Conclusión

El modo Callback de WeCom es la forma “oficial” de integrar Hermes en tu flujo de trabajo empresarial. Requiere más configuración que el bot, pero la recompensa es una experiencia de aplicación pulida y de primera clase para tus usuarios.

Consejo práctico: Comienza con ngrok antes de exponer un servidor real. Ejecuta ngrok http 8645, usa esa URL en la consola de WeCom y prueba con un solo usuario. Una vez que funcione, cambia a un servidor de producción y restringe WECOM_CALLBACK_ALLOWED_USERS a tu equipo. ¡Feliz construcción!