Enviar Análisis de Llamadas

Aprende cómo enviar grabaciones de llamadas a la API de CallCov para análisis con IA. Esta guía cubre la carga de archivos de audio, envío de metadatos y mejores prácticas para la integración.

Resumen

CallCov proporciona dos métodos para enviar llamadas:

1. Carga de Archivos - Sube archivos de audio directamente (recomendado para la mayoría de casos)
2. Envío por URL - Proporciona URLs a archivos de audio almacenados en otro lugar

Ambos métodos devuelven un ID de análisis para rastrear el estado del procesamiento.

Endpoint

POST /api/v1/calls/analyze

Autenticación: Requerida (Clave de API)

Método 1: Carga de Archivos

Sube archivos de audio directamente a CallCov para análisis.

Formatos de Audio Soportados

Formato	Extensión	Tamaño Máx	Recomendado
WAV	.wav	100 MB	✅ Sí
MP3	.mp3	50 MB	✅ Sí
M4A	.m4a	50 MB	✅ Sí
FLAC	.flac	100 MB	Soportado
OGG	.ogg	50 MB	Soportado

Mejor Calidad

Para mejores resultados, usa formatos WAV o FLAC con:

• Frecuencia de muestreo: 16 kHz o superior
• Profundidad de bits: 16-bit mínimo
• Canales: Mono o estéreo (canales separados preferidos para múltiples hablantes)

Carga Básica de Archivos

import requests

API_KEY = "your_api_key_here"
API_URL = "https://api.callcov.com/api/v1"

# Preparar el archivo y metadatos
files = {
  "audio_file": open("call_recording.wav", "rb")
}

data = {
  "agent_id": "AGENT_001",
  "contact_id": "CONTACT_12345",
  "call_direction": "inbound",
  "call_timestamp": "2024-01-15T10:30:00Z"
}

headers = {"X-API-Key": API_KEY}

# Enviar para análisis
response = requests.post(
  f"{API_URL}/calls/analyze",
  headers=headers,
  files=files,
  data=data
)

result = response.json()
print(f"ID de Análisis: {result['analysis_id']}")
print(f"Estado: {result['status']}")

Parámetros de Solicitud

Parámetro	Tipo	Requerido	Descripción
audio_file	Archivo	Sí	El archivo de audio a analizar
agent_id	String	Sí	Identificador único del agente
contact_id	String	Sí	Identificador único del contacto/cliente
call_direction	String	No	inbound o outbound
call_timestamp	String	No	Timestamp ISO 8601 de cuándo ocurrió la llamada
metadata	Object	No	Metadatos personalizados adicionales (string JSON)

Respuesta

{
  "analysis_id": "anl_1a2b3c4d5e",
  "status": "processing",
  "created_at": "2024-01-15T10:30:05Z",
  "estimated_completion": "2024-01-15T10:32:00Z",
  "webhook_url": "https://your-app.com/webhooks/callcov"
}

Método 2: Envío por URL

Envía una URL a un archivo de audio hospedado en otro lugar. CallCov descargará y procesará el archivo.

import requests

API_KEY = "your_api_key_here"
API_URL = "https://api.callcov.com/api/v1"

# Enviar URL de audio
payload = {
  "audio_url": "https://your-storage.com/recordings/call_12345.wav",
  "agent_id": "AGENT_001",
  "contact_id": "CONTACT_12345",
  "call_direction": "outbound",
  "call_timestamp": "2024-01-15T14:20:00Z"
}

headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json"
}

response = requests.post(
  f"{API_URL}/calls/analyze",
  headers=headers,
  json=payload
)

result = response.json()
print(f"ID de Análisis: {result['analysis_id']}")

Requisitos de URL

• La URL debe ser públicamente accesible o incluir autenticación en la URL
• Debe devolver el header Content-Type: audio/*
• Los límites de tamaño de archivo aún aplican
• Se recomiendan URLs HTTPS por seguridad

Verificar Estado del Análisis

Después del envío, consulta el endpoint de estado para verificar el progreso:

import requests
import time

def wait_for_analysis(analysis_id, api_key, max_wait=300):
  """Consultar hasta que el análisis complete o timeout"""
  api_url = "https://api.callcov.com/api/v1"
  headers = {"X-API-Key": api_key}

  start_time = time.time()
  while time.time() - start_time < max_wait:
      response = requests.get(
          f"{api_url}/calls/analyze/{analysis_id}",
          headers=headers
      )

      result = response.json()
      status = result['status']

      if status == 'completed':
          print("¡Análisis completado!")
          return result
      elif status == 'failed':
          print(f"Análisis falló: {result.get('error')}")
          return None

      print(f"Estado: {status} - esperando...")
      time.sleep(5)  # Consultar cada 5 segundos

  print("Timeout esperando el análisis")
  return None

# Uso
analysis_id = "anl_1a2b3c4d5e"
result = wait_for_analysis(analysis_id, "your_api_key_here")
if result:
  print(f"Sentimiento: {result['analysis']['sentiment']}")
  print(f"Resumen: {result['analysis']['summary']}")

Mejor Enfoque: Usa Webhooks

En lugar de consultar, configura un webhook para recibir notificaciones cuando el análisis se complete. Consulta la Guía de Webhooks para más detalles.

Envíos en Lote

Envía múltiples llamadas eficientemente:

import requests
import os
from concurrent.futures import ThreadPoolExecutor, as_completed

API_KEY = "your_api_key_here"
API_URL = "https://api.callcov.com/api/v1"

def submit_call(file_path, agent_id, contact_id):
  """Enviar una sola llamada para análisis"""
  files = {"audio_file": open(file_path, "rb")}
  data = {
      "agent_id": agent_id,
      "contact_id": contact_id
  }
  headers = {"X-API-Key": API_KEY}

  response = requests.post(
      f"{API_URL}/calls/analyze",
      headers=headers,
      files=files,
      data=data
  )

  return response.json()

# Envío en lote con threading
calls_to_submit = [
  ("recording1.wav", "AGENT_001", "CONTACT_001"),
  ("recording2.wav", "AGENT_001", "CONTACT_002"),
  ("recording3.wav", "AGENT_002", "CONTACT_003"),
]

results = []
with ThreadPoolExecutor(max_workers=5) as executor:
  futures = [
      executor.submit(submit_call, file_path, agent_id, contact_id)
      for file_path, agent_id, contact_id in calls_to_submit
  ]

  for future in as_completed(futures):
      try:
          result = future.result()
          results.append(result)
          print(f"Enviado: {result['analysis_id']}")
      except Exception as e:
          print(f"Error: {e}")

print(f"\nEnviadas {len(results)} llamadas para análisis")

Mejores Prácticas

Calidad de Audio

• Frecuencia de muestreo: 16 kHz mínimo, 44.1 kHz recomendado
• Códec: Sin comprimir (WAV, FLAC) para mejores resultados
• Canales: Canales separados para agente y cliente cuando sea posible
• Ruido de fondo: Minimizar para mejor precisión de transcripción

Optimización de Rendimiento

1. Usa webhooks en lugar de consultar para resultados
2. Comprime archivos grandes antes de subir (pero no demasiado - la calidad importa)
3. Envíos en lote durante horas de menor actividad para grandes volúmenes
4. Cachea resultados para evitar reprocesar las mismas llamadas

Manejo de Errores

Siempre implementa lógica de reintento con backoff exponencial:

import time
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

def create_retry_session(retries=3, backoff_factor=0.3):
  """Crear sesión con reintento automático"""
  session = requests.Session()
  retry = Retry(
      total=retries,
      read=retries,
      connect=retries,
      backoff_factor=backoff_factor,
      status_forcelist=(500, 502, 503, 504),
  )
  adapter = HTTPAdapter(max_retries=retry)
  session.mount('http://', adapter)
  session.mount('https://', adapter)
  return session

# Uso
session = create_retry_session()
response = session.post(
  f"{API_URL}/calls/analyze",
  headers=headers,
  files=files,
  data=data
)

Límites de Frecuencia

Los límites de frecuencia de envío varían según el plan:

Plan	Envíos/Minuto	Procesamiento Concurrente
Gratis	5	1
Starter	30	5
Business	150	25
Enterprise	Personalizado	Personalizado

Errores Comunes

400 Bad Request

{
  "error": {
    "code": "invalid_file_format",
    "message": "El archivo de audio debe estar en formato WAV, MP3, M4A, FLAC u OGG"
  }
}

Solución: Verifica el formato del archivo y asegúrate de que sea soportado.

413 Payload Too Large

{
  "error": {
    "code": "file_too_large",
    "message": "El archivo de audio excede el tamaño máximo de 100 MB"
  }
}

Solución: Comprime el audio o divide en segmentos más pequeños.

429 Too Many Requests

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Límite de frecuencia excedido. Intenta nuevamente en 32 segundos."
  }
}

Solución: Implementa limitación de frecuencia y backoff exponencial en tu código.

Próximos Pasos

• Recuperar Resultados de Análisis
• Configurar Webhooks
• Guía de Manejo de Errores
• Mejores Prácticas de Producción

¿Necesitas Ayuda?

• Email: support@callcov.com
• Documentación: docs.callcov.com
• Panel de Control: app.callcov.com