Ir al contenido

API de Metadatos de Llamadas

Los informes de call center necesitan datos que no están en el audio: cuándo ocurrió la llamada, qué agente la atendió, si fue entrante o saliente, quién colgó primero. Hay tres formas de aportarlos:

  • Por archivo al subirlo, como campos adicionales en POST /api/files/ — ideal cuando su sistema sube las grabaciones una por una
  • Por archivo después, con PATCH /api/files/{id}/ — para correcciones y para metadatos que llegan después de la grabación
  • Por proyecto, como manifiesto CSV en POST /api/projects/{id}/call-manifest/ — ideal para cargas masivas y para completar metadatos a posteriori

Las tres escriben en el mismo lugar, así que puede combinarlas; prevalece la última escritura. Los metadatos enviados por la API siempre tienen prioridad sobre el nombre del agente que la IA extrae de la conversación.

Los metadatos que tiene una llamada en cada momento se pueden consultar en el recurso del archivo, en call_metadata.

Todos los endpoints requieren una cookie de sesión o una clave de API — consulte Autenticación.


Metadatos del agente con análisis automático

Sección titulada «Metadatos del agente con análisis automático»

En un proyecto de llamadas con el análisis automático activado, cada llamada se analiza poco después de llegar. Si para entonces la llamada no tiene agente, los informes usan el nombre que la IA oyó en la conversación, que puede ser incorrecto o dividir a un agente en varios. Para evitarlo, indique quién es el agente de una de estas formas:

  • En la subida, con agent_id, agent_name o agent_email
  • En un manifiesto enviado antes, con una fila de ese archivo que tenga agente
  • Por una subida anterior con el mismo nombre de archivo, cuyo agente haya aportado usted

En caso contrario, la subida se realiza igualmente y la llamada se procesa como siempre, pero la respuesta 201 incluye una lista warnings junto a los campos habituales del archivo:

{
"id": 1042,
"status": "transcribing",
"warnings": [
{
"code": "call_metadata_missing",
"detail": "Este proyecto analiza las llamadas automáticamente, pero esta llamada no tiene metadatos del agente, ...",
"docs_url": "https://docs.uspeech.io/es/api/call-metadata/"
}
]
}

La clave warnings solo aparece cuando hay un aviso, y solo en las subidas con clave de API de grabaciones y transcripciones SRT/VTT. En la aplicación web, el aviso se muestra en la página de Conversaciones.

Si sus metadatos solo pueden llegar después de las grabaciones, envíelos en cuanto los tenga. El nombre real sustituye al deducido, y los informes se actualizan sin volver a analizar la llamada.


El endpoint de subida de archivos acepta metadatos de llamada opcionales junto a los campos habituales (consulte Subir Grabaciones para la petición base).

Content-Type: multipart/form-data

Campos adicionales del formulario:

CampoTipoDescripción
call_datetimefecha y horaCuándo ocurrió la llamada (ISO 8601, ej. 2026-06-15T09:12:00Z)
agent_idtexto (≤64)Identificador del agente en sus propios sistemas
agent_nametexto (≤255)Nombre visible del agente
agent_emailcorreoCorreo del agente. Permite que un agente invitado con esta dirección vea sus propias llamadas. Un agent_id que sea una dirección de correo válida se interpreta también como el correo del agente
directiontextoinbound o outbound
ended_bytextoQuién colgó primero, según tu marcador: customer (el cliente) o agent (el agente). Exime los pasos de cierre de la rúbrica en las llamadas que el cliente abandonó antes de la despedida del agente
caller_numbertexto (≤64)Número telefónico del cliente
campaigntexto (≤255)Nombre de la campaña o cola

Los campos que no envíe simplemente no se establecen. Aquí los valores vacíos se ignoran, de modo que un campo en blanco nunca tapa una fila de manifiesto que ya esté esperando a este archivo.

Ejemplo:

Ventana de terminal
curl -X POST https://app.uspeech.io/api/files/ \
-H "Authorization: Api-Key $USPEECH_KEY" \
-F "project=312" \
-F "file_type=audio" \
-F "file=@./call_001.mp3" \
-F "call_datetime=2026-06-15T09:12:00Z" \
-F "agent_id=A-06" \
-F "agent_name=Ana Diaz" \
-F "direction=inbound" \
-F "caller_number=+34600111222" \
-F "campaign=Retencion"

Todo recurso de archivo —de POST /api/files/, GET /api/files/{id}/ y GET /api/files/?project={id}/— incluye un objeto call_metadata. Es null en los archivos que no tienen registro de llamada, es decir, en todos los archivos de un proyecto que no sea de llamadas.

{
"id": 9871,
"original_filename": "call_001.mp3",
"status": "transcribed",
"call_metadata": {
"call_datetime": "2026-06-15T09:12:00Z",
"call_datetime_source": "api",
"agent_id": "A-06",
"agent_name": "Ana Diaz",
"agent_email": "ana.diaz@example.com",
"agent_source": "api",
"direction": "inbound",
"ended_by": "customer",
"caller_number": "+34600111222",
"campaign": "Retencion"
}
}

Los dos campos _source indican de dónde procede cada valor, lo que resulta útil al reconciliar con su propio sistema:

CampoValoresSignificado
call_datetime_sourceapi, manifest, upload_timeupload_time significa que nunca se aportó una fecha real de la llamada — se está usando la hora de subida del archivo
agent_sourceapi, manifest, llm, ""llm significa que el nombre del agente se extrajo de la conversación y no lo aportó usted; "" significa que no hay ningún agente vinculado

Actualiza los metadatos de llamada de un archivo ya subido. Solo se modifican los campos que envíe, así que puede cambiar un valor sin repetir el resto.

Content-Type: application/json (o multipart/form-data)

Campos del cuerpo: los mismos ocho del endpoint de subida.

Cómo borrar un valor: envíe una cadena vacía. {"campaign": ""} elimina la campaña; enviar agent_id y agent_name vacíos desvincula al agente. Esto se diferencia del manifiesto CSV, donde las celdas en blanco se omiten en lugar de interpretarse como una orden de borrado.

Envía agent_email junto con agent_id. Los campos de agente que envíes deciden a qué agente pertenece la llamada:

CuerpoResultado
{"agent_id": "A-06", "agent_email": "ana.diaz@example.com"}Establece el correo en el agente A-06, para todas sus llamadas
{"agent_id": "A-06", "agent_email": ""}Deja el correo del agente como está
{"agent_email": "ana.diaz@example.com"}Mueve esta llamada al agente con ese correo, y crea un agente nuevo si no existe
{"agent_email": ""}Desvincula al agente de esta llamada, igual que borrar agent_id y agent_name

call_datetime es la excepción: no se puede borrar, porque una llamada siempre necesita una hora. Envíe un valor nuevo para cambiarla, u omítala para dejarla intacta; null se rechaza con 400. Si la borra desde la interfaz, se restablece la hora de subida del archivo.

Actualizar los metadatos no vuelve a ejecutar el análisis. Las puntuaciones, los temas, el sentimiento y los resultados de rúbrica quedan intactos.

Respuesta (200 OK): el recurso del archivo actualizado, con el nuevo call_metadata.

Errores:

EstadoCuándo
400El proyecto no es de llamadas, el archivo no es una grabación ni una transcripción (solo audio, srt y vtt llevan metadatos de llamada), o algún valor no es válido (p. ej. call_datetime: null, un direction o un ended_by desconocido, un agent_email mal formado)
404El archivo no existe o no es visible para quien hace la petición

Ejemplo — cambiar la campaña y borrar la dirección:

Ventana de terminal
curl -X PATCH https://app.uspeech.io/api/files/9871/ \
-H "Authorization: Api-Key $USPEECH_KEY" \
-H "Content-Type: application/json" \
-d '{"campaign": "Recuperacion", "direction": ""}'

Sube un manifiesto CSV con metadatos de muchas llamadas a la vez. Las filas se asocian a los archivos del proyecto por nombre de archivo, y las que aún no coinciden con ninguno se guardan en el proyecto y se aplican a los archivos subidos más tarde.

{id} es el ID numérico del proyecto — consulta Proyectos si necesitas obtenerlo.

Autenticación: clave de API o sesión.

Content-Type: multipart/form-data

Campos del formulario:

CampoObligatorioDescripción
filesíEl manifiesto CSV

Columnas del CSV (se requiere fila de encabezado): filename y call_datetime son obligatorias; agent_id, agent_name, agent_email, direction, ended_by, caller_number y campaign son opcionales. Un agent_email que no sea una dirección válida se descarta y el resto de la fila se aplica igualmente. ended_by también acepta cliente, client y caller para el cliente, y agente, asesor y asesora para el agente, con cualquier combinación de mayúsculas; cualquier otro valor se descarta.

filename,call_datetime,agent_id,agent_name,agent_email,direction,ended_by,caller_number,campaign
call_001.mp3,2026-06-15 09:12:00,A-06,Ana Diaz,ana.diaz@example.com,inbound,customer,+34600111222,Retencion
call_002.mp3,2026-06-15 09:41:00,A-10,Luis Gomez,luis.gomez@example.com,outbound,agent,+34600333444,Recuperacion

Formatos de fecha y hora aceptados: ISO 8601, YYYY-MM-DD HH:MM[:SS] y DD/MM/YYYY HH:MM[:SS]. Los valores sin zona horaria se interpretan en la zona horaria del servidor.

Asociación: primero por nombre exacto, luego por el nombre sin extensión (sin distinguir mayúsculas), de modo que call_001.wav en el manifiesto coincide con un call_001.mp3 ya subido. Se asocian tanto archivos de audio como transcripciones (SRT/VTT).

Respuesta (200 OK):

{
"matched": 118,
"unmatched": ["call_119.mp3", "call_120.mp3"],
"errors": ["Row 42 (call_041.mp3): invalid call_datetime '15-06-2026'"]
}
  • matched — filas aplicadas a un archivo que ya existe
  • unmatched — filas guardadas para archivos que aún no se han subido
  • errors — filas omitidas, con el motivo

Errores:

EstadoCuándo
400El proyecto no es de llamadas, no se envió file, o el CSV no tenía filas válidas (la respuesta incluye errors)
404El proyecto no existe o no es visible para quien hace la petición

Ejemplo:

Ventana de terminal
curl -X POST https://app.uspeech.io/api/projects/312/call-manifest/ \
-H "Authorization: Api-Key $USPEECH_KEY" \
-F "file=@./llamadas_junio.csv"

Cuando las llamadas se hayan analizado, los metadatos que adjuntó aquí se convierten en las dimensiones de agrupación y filtrado del informe: agente, dirección, campaña y fecha de la llamada. Consulte la API de Informes de Llamadas para leer esos resultados.