> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuracall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata de Modelo

> Información contextual para segmentar y filtrar análisis de llamadas

## ¿Qué es el Metadata?

El metadata son **campos de información contextual** que se envían junto con cada análisis de llamada. A diferencia de las variables, el metadata no se extrae de la conversación sino que se proporciona externamente.

<CardGroup cols={2}>
  <Card title="Variables" icon="microphone">
    Datos **extraídos de la llamada** por la IA durante el análisis
  </Card>

  <Card title="Metadata" icon="tag">
    Datos **proporcionados externamente** al crear el análisis
  </Card>
</CardGroup>

## ¿Por qué usar Metadata?

El metadata permite contextualizar y segmentar los análisis para obtener insights más profundos:

<CardGroup cols={2}>
  <Card title="Segmentación" icon="chart-pie">
    Agrupa análisis por área, campaña, supervisor u otros criterios
  </Card>

  <Card title="Filtrado" icon="filter">
    Filtra reportes y estadísticas por valores específicos
  </Card>

  <Card title="Dashboards" icon="gauge">
    Alimenta widgets y gráficos con datos segmentados
  </Card>

  <Card title="Comparativas" icon="code-compare">
    Compara rendimiento entre diferentes segmentos
  </Card>
</CardGroup>

## Estructura de Metadata

| Campo            | Tipo    | Descripción                          | Requerido |
| ---------------- | ------- | ------------------------------------ | --------- |
| `key`            | string  | Identificador único (snake\_case)    | Sí        |
| `readable_name`  | string  | Nombre legible para la interfaz      | Sí        |
| `type`           | string  | Tipo de dato esperado                | Sí        |
| `grouping_field` | boolean | Si se usa para agrupar en dashboards | No        |

### Tipos de Datos Soportados

| Tipo      | Descripción     | Ejemplo                            |
| --------- | --------------- | ---------------------------------- |
| `STRING`  | Texto           | "Ventas Norte", "Campaña Q4"       |
| `INTEGER` | Número entero   | ID de sucursal, número de empleado |
| `DATE`    | Fecha           | Fecha de la campaña                |
| `BOOLEAN` | Verdadero/Falso | Es cliente VIP                     |

## El Campo `grouping_field`

El campo `grouping_field` es especialmente importante. Cuando se marca como `true`, ese campo de metadata aparece como **opción de agrupación** en los dashboards y reportes de Neuracall.

### Ejemplo Visual

<Tree>
  <Tree.Folder name="Metadata con grouping_field: true" defaultOpen>
    <Tree.File name="area → Aparece en filtros del dashboard" />

    <Tree.File name="supervisor → Permite agrupar por supervisor" />

    <Tree.File name="campana → Habilita comparativas por campaña" />
  </Tree.Folder>
</Tree>

### Estadísticas por Campo de Agrupación

Con campos de agrupación configurados, puedes usar el endpoint de estadísticas:

```bash theme={null}
GET /v1/stats/grouping-fields?field=area&model_id=uuid
```

Esto devuelve métricas agregadas (promedio NeuraScore, total de llamadas, etc.) por cada valor único del campo.

## Casos de Uso Comunes

### Segmentación por Área

```json theme={null}
{
  "key": "area",
  "readable_name": "Área de Negocio",
  "type": "STRING",
  "grouping_field": true
}
```

Valores típicos: "Ventas", "Soporte", "Cobranza", "Retención"

### Tracking de Campañas

```json theme={null}
{
  "key": "campana",
  "readable_name": "Campaña",
  "type": "STRING",
  "grouping_field": true
}
```

Valores típicos: "Black Friday 2024", "Retención Q4", "Cross-sell Premium"

### Identificación de Supervisor

```json theme={null}
{
  "key": "supervisor_id",
  "readable_name": "ID de Supervisor",
  "type": "STRING",
  "grouping_field": true
}
```

Permite comparar rendimiento de equipos por supervisor.

### Clasificación de Cliente

```json theme={null}
{
  "key": "segmento_cliente",
  "readable_name": "Segmento de Cliente",
  "type": "STRING",
  "grouping_field": true
}
```

Valores típicos: "Premium", "Standard", "Nuevo"

## Gestión vía API

### Listar Metadata de un Modelo

```bash theme={null}
GET /v1/models/{model_id}/metadata
Authorization: Bearer <token>
```

### Crear Campo de Metadata

```bash theme={null}
POST /v1/models/{model_id}/metadata
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "area",
  "readable_name": "Área de Negocio",
  "type": "STRING",
  "grouping_field": true
}
```

### Actualizar Metadata

```bash theme={null}
PUT /v1/models/{model_id}/metadata/{metadata_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "area",
  "readable_name": "Área de Operaciones",
  "type": "STRING",
  "grouping_field": true
}
```

## Envío de Metadata al Crear Análisis

Cuando creas un análisis de llamada, incluyes los valores de metadata en el request:

```bash theme={null}
POST /v1/call-analysis
Authorization: Bearer <token>
Content-Type: multipart/form-data

{
  "model_id": "uuid-del-modelo",
  "audio_file": <archivo>,
  "metadata": {
    "area": "Ventas Norte",
    "supervisor_id": "SUP-001",
    "campana": "Black Friday 2024",
    "segmento_cliente": "Premium"
  }
}
```

<Note>
  Solo puedes enviar metadata cuyos keys estén definidos en el modelo. Valores con keys no definidos serán ignorados.
</Note>

## Restricciones Importantes

<Warning>
  **No se puede modificar ni eliminar metadata si el modelo tiene análisis existentes.**

  Esta restricción garantiza la integridad de los datos históricos. Los análisis completados
  mantienen su estructura original para que los reportes comparativos sean consistentes.
</Warning>

### ¿Qué hacer si necesitas modificar metadata?

1. **Crear un nuevo modelo**: Duplica el modelo con los campos de metadata actualizados
2. **Agregar campos**: Puedes agregar nuevos campos de metadata a modelos existentes
3. **Desactivar el modelo**: Desactiva el modelo actual y crea uno nuevo con la estructura deseada

## Diferencia entre Metadata y Variables de Extracción

| Aspecto           | Metadata                        | Variable de Extracción               |
| ----------------- | ------------------------------- | ------------------------------------ |
| **Origen**        | Proporcionado al crear análisis | Extraído de la llamada por IA        |
| **Momento**       | Conocido antes del análisis     | Descubierto durante el análisis      |
| **Ejemplo**       | Área del agente, campaña        | Producto mencionado, fecha de pago   |
| **Uso principal** | Segmentación y filtrado         | Captura de información de la llamada |

## Mejores Prácticas

<Steps>
  <Step title="Define campos de agrupación estratégicos">
    Piensa qué segmentaciones serán más útiles para tu negocio antes de definir el metadata.
  </Step>

  <Step title="Usa keys consistentes">
    Mantén una convención de nombres (snake\_case) consistente en todos tus modelos.
  </Step>

  <Step title="Limita los campos de agrupación">
    3-5 campos con `grouping_field: true` es ideal. Demasiados complican los dashboards.
  </Step>

  <Step title="Documenta los valores esperados">
    Mantén un catálogo de valores válidos para cada campo de metadata.
  </Step>
</Steps>

## Relación con Otros Recursos

<CardGroup cols={2}>
  <Card title="Estadísticas por Campo" icon="chart-bar" href="/api-reference/stats/grouping-fields">
    Endpoint para obtener métricas agrupadas
  </Card>

  <Card title="API de Metadata" icon="code" href="/api-reference/models/metadata/list">
    Referencia completa de endpoints
  </Card>
</CardGroup>