Skip to main content

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

CampoTipoDescripciónRequerido
keystringIdentificador único (snake_case)Sí
readable_namestringNombre legible para la interfazSí
typestringTipo de dato esperadoSí
grouping_fieldbooleanSi se usa para agrupar en dashboardsNo

​
Tipos de Datos Soportados

TipoDescripciónEjemplo
STRINGTexto”Ventas Norte”, “Campaña Q4”
INTEGERNúmero enteroID de sucursal, número de empleado
DATEFechaFecha de la campaña
BOOLEANVerdadero/FalsoEs 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?

  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

AspectoMetadataVariable de Extracción
OrigenProporcionado al crear análisisExtraído de la llamada por IA
MomentoConocido antes del análisisDescubierto durante el análisis
EjemploÁrea del agente, campañaProducto mencionado, fecha de pago
Uso principalSegmentación y filtradoCaptura de información de la llamada

​
Mejores Prácticas

1

Define campos de agrupación estratégicos

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

Usa keys consistentes

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

Limita los campos de agrupación

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

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