Saltar al contenido principal
Nivel: Intermedio · Etiquetas: WhatsApp, Soporte, Handoff Funcionalidades: handoff humano · comandos de escape (allowCommands) · eventos 'handoff', 'resume' y 'message' · comandos con argumentos · enviar fuera de un handler · bot.delay()

Requisitos

  • Node.js 22.12 o superior y una carpeta vacía con "type": "module" en su package.json (Inicio rápido).

El bot completo

Cómo funciona

  1. La compuerta. Mientras un chat está en handoff, el bot no enruta sus mensajes: ni handlers, ni flujos, ni catch-all. Solo siguen funcionando los comandos de handoff.allowCommands que tienen un bot.command(), así que /bot siempre trae de vuelta al bot.
  2. Empezar el handoff. ctx.handoff() cierra la compuerta de este chat y cancela cualquier conversación en curso. El handler que hace el handoff todavía puede responder.
  3. Avisar a los agentes. El evento 'handoff' se emite una vez por handoff. bot.send(chatId, texto) envía fuera de un handler, aquí al chat de cada agente. El número de ticket acorta los comandos del agente.
  4. Reenviar. Los mensajes de un chat en handoff se siguen guardando y siguen emitiendo el evento 'message', que los reenvía a los agentes. (Tu CRM o tu bandeja de entrada se suscribiría aquí).
  5. Comandos de agente. bot.command('reply', (ctx, args) => ...) recibe las palabras que siguen al comando. isAgent(ctx) comprueba el id del remitente, así que cualquier otro que escriba /reply no obtiene nada.
  6. De vuelta al bot. bot.resume(chatId, { reason }) reabre la compuerta y emite 'resume' con ese motivo, lo llame quien lo llame: el agente (/done), el usuario (/bot) o el temporizador.
  7. El timeout. bot.delay(AGENT_TIMEOUT, fn) se ejecuta una vez a los 10 minutos, y cada respuesta del agente lo reinicia. Si ningún agente escribe a tiempo, el chat vuelve al bot con el mensaje de timeout. El handler de 'resume' cancela el temporizador acabe como acabe el handoff.
El estado del handoff se guarda en el store, así que con un store persistente (SQLite, Redis) un chat sigue con los agentes tras un reinicio. Este ejemplo guarda tickets y temporizadores en memoria: reconstrúyelos al arrancar con bot.listHandoffs() si necesitas que sobrevivan.

Pruébalo

El agente es el usuario agente: :as agente cambia a él, y las líneas bot → agente › son lo que el bot envía al chat del agente.

Ejecútalo en WhatsApp o Telegram

Pon en AGENTS los ids de los agentes (envía /id desde el teléfono de cada agente para verlos), arranca con node bot.js y escanea el QR desde WhatsApp → Dispositivos vinculados:
En Telegram los ids son números (AGENTS=123456789); instala @botmesh/telegram y cambia el provider como en O conectar Telegram.

Siguientes pasos