US-036 — Devolución al agente

Detalle de la historia¶

Historia¶

Como operador de FleteChat involucrado en un handoff, quiero que la conversación se devuelva al agente automático cuando corresponda (caso resuelto, cliente sin respuesta, o mi desconexión prolongada), para que el agente retome con contexto completo, el cliente siempre sepa que volvió al asistente y ninguna sesión quede colgada en handoff.

Persona de usuario¶

Aplica al operador asignado al handoff (operator o admin) que decide devolver la conversación, al cliente final (que recibe notificación cuando el agente retoma), y al sistema (que ejecuta la devolución automática si el operador se desconecta sin cerrar).

Contexto de negocio¶

Un handoff debe devolverse al agente para que la conversación continúe con fluidez. Si la conversación quedara anclada al operador humano indefinidamente, cada mensaje futuro del cliente tendría que pasar por él, lo que no escala. La devolución cierra el ciclo: el cliente vuelve al flujo conversacional estándar y puede cotizar, consultar estatus o hacer cualquier otra acción con el agente, con la ventaja de que el agente ahora conoce lo conversado con el operador.

Hay tres caminos de devolución, todos con la misma consecuencia funcional (cambio de estado a ai_handling, contexto completo al agente, notificación obligatoria al cliente):

1. Camino A — Caso resuelto: el operador resolvió y hace click en "Devolver al agente" desde el chat del handoff.
2. Camino B — Cliente sin respuesta: tras un intercambio, el cliente deja de contestar y el operador decide cerrar la sesión devolviéndola al agente (también con click explícito en el backoffice).
3. Camino C — Desconexión del operador: el operador cierra la pestaña, cierra sesión o pierde conexión sin devolver explícitamente. Tras un timeout configurable (ver PR-151), FleteChat ejecuta la devolución automática para evitar sesiones colgadas.

En los tres caminos, FleteChat notifica al cliente que la sesión con el asesor terminó. Si la ventana de 24 h de WhatsApp está abierta, la notificación va como mensaje libre; si está cerrada, va por plantilla Meta aprobada (ver PR-152). Ninguna devolución ocurre en silencio (ver PR-150 en US-033).

Diálogo de referencia¶

Camino A — Operador cierra con caso resuelto (ventana 24 h abierta)¶

(Después de resolver el caso, el operador escribe una nota de cierre opcional:)

Operador, Juan Rodríguez: María, quedó todo resuelto con la factura del E42; le emitimos la nota de crédito hoy mismo. Gracias por su paciencia.

(Click en "Devolver al agente".)

Agente (notificación automática de devolución): La sesión con nuestro asesor terminó. Si necesita algo más, escríbame por aquí y el asistente le responderá o lo pasamos con un asesor nuevamente.

Camino B — Cliente sin respuesta, ventana 24 h cerrada (plantilla Meta)¶

(El operador atendió parcialmente; el cliente dejó de responder; pasaron más de 24 h desde el último mensaje del cliente. El operador da click en "Devolver al agente por falta de respuesta". FleteChat dispara la plantilla Meta aprobada:)

Agente (plantilla Meta de devolución): La sesión con nuestro asesor terminó por falta de respuesta. Cuando pueda retomar, escriba por aquí y el asistente le atenderá o lo pasará con un asesor si lo necesita.

Cliente escribe después de la devolución¶

Cliente, María: Gracias, Juan. Otra cosa: ¿me puedes cotizar un envío de Bogotá a Panamá para el próximo lunes?

Agente: Con gusto, María. Para armarle la cotización necesito un poco más: ¿qué modalidad prefiere (aéreo, marítimo LCL, FCL) y cuánto pesa o mide la carga?

Criterios de aceptación¶

Camino A — Devolución explícita por caso resuelto¶

1. Desde el chat del handoff, el operador asignado tiene un botón "Devolver al agente" claramente visible.
2. Al hacer click, FleteChat abre un modal que permite al operador escribir un mensaje de cierre opcional dirigido al cliente (texto libre) y confirmar la devolución.
3. Si el operador escribe un mensaje de cierre, FleteChat lo envía al cliente por WhatsApp como último mensaje del operador antes de la devolución (sujeto al estado de la ventana de 24 h; si está cerrada, el mensaje libre del operador no se puede enviar y se avisa al operador en el modal).

Camino B — Devolución explícita por falta de respuesta del cliente¶

1. El chat del handoff ofrece un botón adicional "Devolver por falta de respuesta" que el operador puede usar cuando el cliente dejó de responder. La acción requiere confirmación.
2. Esta devolución no requiere mensaje del operador; la notificación obligatoria al cliente (ver AC 10) cubre el aviso. Si el operador quiere agregar una nota, el modal lo permite con la misma restricción de ventana 24 h que AC 3.
3. Queda distinguida en el audit log como motivo no_response (ver AC 13).

Camino C — Devolución automática por desconexión del operador¶

1. FleteChat monitorea la presencia del operador asignado en el chat del handoff (pestaña activa, sesión de backoffice válida, heartbeat). Si el operador se desconecta (cierra la pestaña, hace logout, pierde conexión por más que el tiempo de gracia de reconexión) y no devuelve explícitamente, FleteChat inicia un temporizador de cierre automático (ver PR-151).
2. Si el operador vuelve a abrir el chat antes de que venza el temporizador, el cierre automático se cancela.
3. Si el temporizador vence sin que el operador retome, FleteChat ejecuta la devolución automática: la conversación pasa a ai_handling, se dispara la notificación obligatoria al cliente (ver AC 10) y queda en el audit log como motivo operator_disconnect.

Notificación obligatoria al cliente (transversal a los tres caminos)¶

1. En los tres caminos (A, B, C), FleteChat envía al cliente una notificación de devolución indicando que la sesión con el asesor terminó y que el agente retoma la atención, invitándolo a continuar escribiendo cuando lo desee. Esta notificación es independiente del mensaje de cierre opcional del operador (AC 3).
2. Si la ventana de 24 h de WhatsApp está abierta, la notificación de devolución se envía como mensaje libre del agente.
3. Si la ventana de 24 h está cerrada, la notificación se envía por plantilla Meta aprobada registrada para este propósito (ver PR-152). El contenido de la plantilla es configurable por FleteChat y pasa por el ciclo de aprobación de Meta antes de usarse.

Cambio de estado y contexto¶

1. Al completarse la devolución (por cualquier camino), la conversación pasa del estado del handoff a ai_handling: el agente vuelve a responder los mensajes nuevos del cliente automáticamente.
2. El agente tiene acceso completo al historial de la conversación, incluidos los mensajes intercambiados entre el operador y el cliente durante el handoff, como parte de su contexto. FleteChat trata esos mensajes con la misma política de memoria persistente del resto de la conversación (ver historia correspondiente).
3. El agente no intenta "repetir" lo que el operador ya dijo: usa el contexto para continuar la conversación hacia adelante, no para reabrir temas cerrados.

Audit log¶

1. Cada devolución queda registrada en el audit log con: motivo (resolved, no_response, operator_disconnect), actor (operador, admin o sistema), timestamp, mensaje de cierre del operador (si hubo), mensaje de notificación al cliente (texto libre o nombre de la plantilla Meta usada), estado de la ventana 24 h al momento de la devolución, handoff ID y duración total del handoff.

Reintervención posterior¶

1. Si después de la devolución el cliente escribe algo que el agente considera que debe volver a transferir, se aplica de nuevo la historia de handoff (US-033), con consentimiento explícito del cliente. Un mismo cliente puede tener múltiples handoffs en la misma conversación, cada uno con su propio ciclo.

Edge cases¶

• Operador cierra el chat del backoffice sin devolver al agente. FleteChat inicia el temporizador de cierre automático (Camino C). Si el operador vuelve a abrir el chat antes del vencimiento, el temporizador se cancela; si no, se ejecuta la devolución automática con notificación al cliente.
• Operador pierde conexión por una caída de red breve y vuelve a los pocos segundos. El tiempo de gracia de reconexión (heartbeat tolerante; configurable por FleteChat) absorbe estas micro-caídas sin disparar el cierre automático.
• Operador quiere devolver pero el cliente está escribiendo. El operador decide si espera a que termine de escribir o devuelve con el mensaje de cierre. Si devuelve, el agente será quien responda al próximo mensaje del cliente.
• Admin fuerza la devolución (por ejemplo, el operador asignado está fuera de turno y la conversación lleva horas sin atención). La acción queda auditada con el admin como actor y motivo resolved o no_response según corresponda; la notificación al cliente (AC 10) se envía igual.
• Devolución con mensaje de cierre vacío (Camino A o B). El mensaje de cierre opcional del operador no se envía. La notificación obligatoria de devolución (AC 10) sí se envía: en ningún escenario el cliente queda sin aviso.
• Ventana 24 h cerrada al momento de la devolución y plantilla Meta no aprobada todavía. FleteChat registra el intento como incidencia (la plantilla es un requisito operativo), deja la conversación en ai_handling y avisa al admin para gestionar la plantilla; el cliente recibirá la notificación en cuanto la plantilla esté disponible o al próximo mensaje del cliente (lo que ocurra primero).
• Cliente responde inmediatamente después de la devolución pero antes de que el agente haya "absorbido" el contexto. FleteChat asegura que la devolución y la actualización del contexto sean atómicas: el agente nunca responde sin el contexto completo del handoff.
• Operador se desconecta, vuelve, y vuelve a desconectarse. Cada desconexión reinicia el temporizador; FleteChat no acumula tiempos de desconexiones anteriores para evitar cierres sorpresivos.

Tamaño, prioridad y tipo¶

• Tamaño: M
• Prioridad: P1 — cierra el ciclo del handoff; sin devolución el handoff se vuelve unidireccional.
• Tipo: feature

Premisas¶

La historia está redactada bajo las siguientes premisas. Si alguna cambia, la historia debe revisarse y ajustarse en consecuencia. Todas deben ser confirmadas por el cliente antes de cerrar la historia.

• PR-145 — Tres caminos de devolución, todos notificados. La devolución al agente tiene tres caminos: (A) explícita del operador por caso resuelto, (B) explícita del operador por falta de respuesta del cliente, (C) automática por desconexión del operador sin devolución explícita. En los tres caminos FleteChat notifica proactivamente al cliente que la sesión con el asesor terminó (ver PR-150 en US-033).
• PR-146 — Contexto del handoff disponible al agente. Tras la devolución, el agente tiene acceso completo al historial de la conversación, incluidos los mensajes intercambiados durante el handoff, como parte de su memoria persistente de la conversación.
• PR-147 — Mensaje de cierre del operador opcional; notificación de devolución obligatoria. En los caminos A y B, el operador puede acompañar la devolución con un mensaje de cierre dirigido al cliente (texto libre, sujeto a la ventana de 24 h). La notificación de devolución (AC 10) es distinta y siempre se envía al cliente, en los tres caminos. Si la ventana de 24 h está abierta, la notificación va como mensaje libre del agente; si está cerrada, va por plantilla Meta (ver PR-152).
• PR-151 — Timeout de cierre automático por desconexión del operador. FleteChat ejecuta la devolución automática si el operador asignado al handoff se desconecta (cierre de pestaña, logout, heartbeat caído más allá del tiempo de gracia) y no retoma dentro de un temporizador configurable. Valor por defecto: 15 minutos. Tanto el temporizador como el tiempo de gracia de reconexión son parámetros configurables por FleteChat desde el backoffice sin cambios de código.
• PR-152 — Plantilla Meta de devolución al agente. FleteChat registra y mantiene aprobada por Meta una plantilla proactiva específica para notificar al cliente la devolución cuando la ventana de 24 h está cerrada. El contenido de la plantilla es configurable por FleteChat; cualquier cambio pasa por el ciclo de aprobación de Meta antes de usarse. La plantilla debe estar aprobada y activa para que los caminos B y C funcionen fuera de ventana.

Refinamiento y Definition of Ready¶

Notas¶

Checklist¶

• ✅ Historia escrita en formato Como / Quiero / Para
• ✅ Persona de usuario identificada
• ✅ Contexto de negocio documentado
• ✅ Criterios de aceptación observables y pass/fail
• ✅ Edge cases relevantes listados
• ✅ Tamaño y prioridad asignados
• ⬜ Premisas PR-145 a PR-147 y PR-151 a PR-152 confirmadas por el cliente
• ⬜ Reglas de negocio aplicables aprobadas
• ⬜ Requerimientos funcionales aplicables aprobados
• ⬜ Historia aprobada formalmente por el cliente