> **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.

# Modelo de datos

El modelo reside en HappyRobot Twin. La jerarquía conceptual que se debe
conservar en integraciones es:

```text
Run / sesión de HappyRobot
  └─ Ticket de TeLeo
       ├─ Cliente
       ├─ Resumen del bot
       ├─ Mensajes
       ├─ Equipo / agente
       └─ Tags / carpeta / automatizaciones
```

La app no crea una base de datos de negocio paralela. Los nombres de tablas son
un detalle de implementación del servicio y deben verificarse en el entorno;
esta referencia describe entidades y contratos, no datos reales.

## Entidades principales

| Entidad | Campos relevantes | Reglas |
|---|---|---|
| Ticket | Identificador externo, número, estado, prioridad, asunto, motivo, sesión, entorno, asignación, equipo, tags, timestamps y cierre. | El identificador externo estable permite idempotencia. |
| Customer | Nombre, contacto y campos Naturgy/Salesforce autorizados. | Minimizar; no inferir identidad desde texto o teléfono. |
| Message | Tipo de remitente (`customer`, `bot`, `agent`, `system`), contenido, autor, timestamp, nota privada y adjuntos. | Las notas privadas no son mensajes públicos. |
| BotSummary | Resumen, descripción de incidencia y sentimientos cuando el contrato los entrega. | Es contexto de handoff, no confirmación de negocio. |
| Agent / AgentProfile | Identidad, rol, equipo, disponibilidad, avatar y capacidad. | El rol y la disponibilidad se verifican en servidor. |
| Team | Nombre, descripción, color y objetivo de primera respuesta si aplica. | No equivale a un permiso de datos. |
| Tag | Etiqueta controlada de perfilado. | Se normaliza y clasifica; no autoriza acceso. |
| Folder | Carpeta por agente con reglas de tags. | Organiza vistas propias; no reemplaza RBAC. |
| Automation | Trigger, condiciones, acción HTTP, estado y resultado. | No guardar secretos en cuerpos o headers visibles. |

## Identificador y correlación

`session_id` es la referencia estable entre conversación y ticket. `run_id` puede
ser el nombre del mismo concepto según la interfaz del workflow. Conserva,
cuando estén autorizados:

```text
session_id / external_ticket_id
correlation_id
workflow_id y versión aprobada
entorno
case_id externo
```

No uses como contrato un enlace privado, un número de fila, un ID temporal de
UI o el orden de llegada. No expongas estos identificadores como autorización.

## Mensajes e histórico

La creación puede recibir el comentario inicial y un histórico del bot. Los
mensajes históricos deben distinguirse visualmente de las respuestas actuales.
Los tipos de remitente son:

* `customer`: mensaje del cliente;
* `bot`: mensaje del asistente o histórico;
* `agent`: respuesta humana;
* `system`: nota de ciclo o mantenimiento.

Un mensaje de agente puede ser público o una nota privada. Los adjuntos se
transportan como referencias de artefacto y se resuelven con permisos; no se
incrustan secretos ni se copian archivos sin límite.

## Tags y carpetas

Los tags recibidos del bot pueden llegar como objeto clave/valor, array o cadena
separada por comas. Se normalizan y se unen a los tags existentes; no deben
contener PII ni sustituir un ACL. Las carpetas son por agente y sus reglas
pueden combinar tags estáticos con tags dinámicos como estado, sin responder,
nuevo o prioridad.

## Run, MS y compatibilidad

El diseño de fases describe Run, MS y Mensajes para distinguir la sesión completa,
cada ciclo de apertura y cada interacción. Si el entorno todavía expone el
ticket como representación de la sesión, no se debe afirmar que existe una
entidad MS desplegada: documenta el modelo como objetivo y valida la migración
antes de usarlo para analítica.

## Propiedad de datos

* Twin: entidades de la consola y su timeline en el alcance configurado.
* HappyRobot: ejecución, sesión, señales y transcript que el tenant conserve.
* Salesforce/Mulesoft/Carolina: casos y estados de negocio.
* Omega: identidad y ficha que exponga.
* Connect: llamada, cola y transferencia de voz.

Un ticket puede referenciar un caso externo, pero no convierte a TeLeo en su
fuente de verdad.