Metadata de Modelo

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

Variables

Datos extraídos de la llamada por la IA durante el análisis

Metadata

Datos proporcionados externamente al crear el análisis

¿Por qué usar Metadata?

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

Segmentación

Agrupa análisis por área, campaña, supervisor u otros criterios

Filtrado

Filtra reportes y estadísticas por valores específicos

Dashboards

Alimenta widgets y gráficos con datos segmentados

Comparativas

Compara rendimiento entre diferentes segmentos

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

Metadata con grouping_field: true

area → Aparece en filtros del dashboard

supervisor → Permite agrupar por supervisor

campana → Habilita comparativas por campaña

Estadísticas por Campo de Agrupación

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

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

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

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

Tracking de Campañas

{
  "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

{
  "key": "supervisor_id",
  "readable_name": "ID de Supervisor",
  "type": "STRING",
  "grouping_field": true
}

Permite comparar rendimiento de equipos por supervisor.

Clasificación de Cliente

{
  "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

GET /v1/models/{model_id}/metadata
Authorization: Bearer <token>

Crear Campo de Metadata

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

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:

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"
  }
}

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

Restricciones Importantes

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.

¿Qué hacer si necesitas modificar metadata?

Crear un nuevo modelo: Duplica el modelo con los campos de metadata actualizados
Agregar campos: Puedes agregar nuevos campos de metadata a modelos existentes
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

Define campos de agrupación estratégicos

Piensa qué segmentaciones serán más útiles para tu negocio antes de definir el metadata.

Usa keys consistentes

Mantén una convención de nombres (snake_case) consistente en todos tus modelos.

Limita los campos de agrupación

3-5 campos con grouping_field: true es ideal. Demasiados complican los dashboards.

Documenta los valores esperados

Mantén un catálogo de valores válidos para cada campo de metadata.

Relación con Otros Recursos

Estadísticas por Campo

Endpoint para obtener métricas agrupadas

API de Metadata

Referencia completa de endpoints

Introducción

Primeros Pasos

Guía de Usuario

Conceptos

Metadata de Modelo

¿Qué es el Metadata?

Variables

Metadata

¿Por qué usar Metadata?

Segmentación

Filtrado

Dashboards

Comparativas

Estructura de Metadata

Tipos de Datos Soportados

El Campo `grouping_field`

Ejemplo Visual

Estadísticas por Campo de Agrupación

Casos de Uso Comunes

Segmentación por Área

Tracking de Campañas

Identificación de Supervisor

Clasificación de Cliente

Gestión vía API

Listar Metadata de un Modelo

Crear Campo de Metadata

Actualizar Metadata

Envío de Metadata al Crear Análisis

Restricciones Importantes

¿Qué hacer si necesitas modificar metadata?

Diferencia entre Metadata y Variables de Extracción

Mejores Prácticas

Relación con Otros Recursos

Estadísticas por Campo

API de Metadata

​¿Qué es el Metadata?

Variables

Metadata

​¿Por qué usar Metadata?

Segmentación

Filtrado

Dashboards

Comparativas

​Estructura de Metadata

​Tipos de Datos Soportados

​El Campo grouping_field

​Ejemplo Visual

​Estadísticas por Campo de Agrupación

​Casos de Uso Comunes

​Segmentación por Área

​Tracking de Campañas

​Identificación de Supervisor

​Clasificación de Cliente

​Gestión vía API

​Listar Metadata de un Modelo

​Crear Campo de Metadata

​Actualizar Metadata

​Envío de Metadata al Crear Análisis

​Restricciones Importantes

​¿Qué hacer si necesitas modificar metadata?

​Diferencia entre Metadata y Variables de Extracción

​Mejores Prácticas

​Relación con Otros Recursos

Estadísticas por Campo

API de Metadata

¿Qué es el Metadata?

¿Por qué usar Metadata?

Estructura de Metadata

Tipos de Datos Soportados

El Campo `grouping_field`

Ejemplo Visual

Estadísticas por Campo de Agrupación

Casos de Uso Comunes

Segmentación por Área

Tracking de Campañas

Identificación de Supervisor

Clasificación de Cliente

Gestión vía API

Listar Metadata de un Modelo

Crear Campo de Metadata

Actualizar Metadata

Envío de Metadata al Crear Análisis

Restricciones Importantes

¿Qué hacer si necesitas modificar metadata?

Diferencia entre Metadata y Variables de Extracción

Mejores Prácticas

Relación con Otros Recursos