> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# Estados y eventos

Usa este catálogo para diseñar integraciones y pruebas. Los nombres de eventos
son contrato; el estado visual de una pestaña no lo sustituye.

## Estados del ticket

| Estado | Entrada habitual | Salida habitual | Efecto |
|---|---|---|---|
| `open` | Ticket creado, respuesta de cliente o reapertura autorizada | Respuesta, cola, Pendientes, cierre o de-escalado | Está activo y puede asignarse. |
| `snoozed` | Silencio del cliente después de una respuesta o acción Pendientes | Nuevo mensaje, reapertura o acción del agente | No consume capacidad. |
| `closed` | Cierre explícito o de-escalado | Nueva atención según la política del canal | No debe reabrirse por un simple timeout. |

Asignación (`assigned_agent_id`), equipo, prioridad y `close_reason` son
atributos adicionales. `close_reason=inactivity` puede existir por compatibilidad
con histórico, pero no representa el autocierre vigente por inactividad.

## Señales HappyRobot

| Evento | Cuándo | Resultado esperado |
|---|---|---|
| `escalation_started` | Ticket creado y listo para la atención humana | El workflow conoce que la conversación ha cruzado a TeLeo. |
| `escalation_ended` | De-escalado aceptado | El workflow puede devolver la conversación al bot. |
| `escalation_closed` | Cierre permanente del agente | El workflow conoce que la atención terminó según el control acordado. |

La señal se publica sobre el tópico de la sesión y en el mismo entorno del run.
La entrega es fire-and-forget: un error se registra y no borra el mensaje ni
bloquea la consola. La API key de señales es server-only y nunca aparece en un
payload o log.

## Webhook de respuesta

Cuando un agente responde públicamente:

1. TeLeo guarda el mensaje;
2. TeLeo intenta el webhook configurado para la sesión;
3. HappyRobot entrega el texto al cliente;
4. un fallo queda registrado para diagnóstico o reintento.

Las notas privadas no producen una respuesta de cliente. Un webhook repetido o
fuera de orden debe ser idempotente en el consumidor.

## Eventos de automatización

La app puede disparar acciones HTTP a partir de eventos como:

| Trigger | Ejemplo de uso |
|---|---|
| `ticket_created` | Notificar al sistema de casos. |
| `customer_reply` | Actualizar una cola externa. |
| `agent_reply` | Sincronizar una respuesta pública. |
| `ticket_status_changed` | Auditar un movimiento de estado. |
| `ticket_closed` | Registrar cierre y métricas. |

Las automatizaciones deben filtrar por entorno y condiciones, usar headers
server-side y guardar solo la evidencia mínima. Una automatización no debe
reintentar una mutación sin idempotencia.

## Correlación mínima

Cada evento debe transportar o resolver:

```text
session_id
external_ticket_id
correlation_id
environment
event
created_at
```

Añade `message_id`, `agent_id` o `case_id` solo cuando sean necesarios y estén
autorizados. No uses el cuerpo del mensaje como identificador.