Automatice llamadas telefónicas desde su propio sistema

Lista los agentes de su organización.

Filtros

Cada agente incluye

agent_id (el que usará al lanzar), name, description, is_active, el área de negocio a la que pertenece y su fecha de creación.

Trae un agente puntual. Devuelve los mismos campos que el listado.

Si el agente no existe, responde 404.

Lista las campañas disponibles, de la más reciente a la más antigua.

Filtros

Cada campaña incluye

Lista los números disponibles para su organización: tanto los propios como los de uso general. Los inactivos no aparecen.

De cada número obtiene su phone_number_id, el número en formato internacional, un nombre amigable y si tiene SMS habilitado.

No admite filtros ni paginación: devuelve todos.

Lista los departamentos de su organización. Empiece por aquí: necesita un department_id para consultar la taxonomía.

También puede tomar el department_id directamente de una campaña.

Devuelve las etiquetas de clasificación disponibles para un departamento.

Parámetros

Qué contiene cada etiqueta

Las etiquetas vienen organizadas en familias: las de no contacto agrupan los casos en que no se habló con nadie, las de contacto efectivo los casos en que sí. Esa agrupación es la que conviene usar para decidir qué reintentar.

Crea un lote y empieza a llamar, en una sola petición. Responde 201.

Lo mínimo que necesita

{
  "name": "Cobranza julio - primera pasada",
  "agent_id": "a3f1...",
  "campaign_id": "7b2c...",
  "contacts": [
    {
      "phone": "+59891828169",
      "name": "María Pérez",
      "variables": { "monto_deuda": "4520" }
    }
  ]
}

Campos obligatorios

Cada contacto

Cuándo llamar

date y el par start_date/end_date son excluyentes: use uno u otro, nunca los dos.

Opciones de la llamada

Reintentos

El bloque retry controla qué pasa cuando una llamada no logra su objetivo. Si lo omite, se aplica un único intento por contacto.

{
  "retry": {
    "max_attempts": 3,          // intentos por contacto (0 a 50)
    "delay_minutes": 30,        // espera entre intentos (0 a 1440)
    "taxonomy": {
      "enabled": true,
      "retry_eligible_labels": ["no_contesta", "buzon_voz"],
      "batch_at_list_end": false
    }
  }
}

Qué recibe

El id del lote creado — guárdelo, es el que usará para consultar resultados —, su estado, el total de contactos importados y un mensaje de confirmación. También incluye callable_contacts, skipped_contacts y, si aplica, el array skipped con los contactos cargados pero no marcados (teléfono inválido → estado de cola Skipped). Si el mismo teléfono aparece más de una vez, se carga solo la primera ocurrencia (first-wins) y la respuesta incluye duplicate_contacts y duplicates (ocurrencias ignoradas, no importadas; distintos de skipped). Los índices de skipped[] y duplicates[] son 0-based respecto al array contacts del request.

Indicador de capacidad — capacity_warning

La respuesta incluye capacity_warning siempre que se pueda calcular — es informativo, no bloqueante: el lote se lanza igual, incluso cuando el estado es insufficient. Estima cuántos contactos se pueden procesar en la ventana de fechas/horario elegida, usando los canales que se proyecta tendrá disponibles su organización (según su cupo asignado), una duración de llamada típica y un factor de ocupación de los canales — no una tasa fija por canal.

{
  "capacity_warning": {
    "status": "insufficient",
    "message": "~7543 contactos procesables en la ventana estimada (22 canal(es), 1 día(s) válido(s)) · Insuficiente para 27097 contacto(s) marcable(s)",
    "estimated_capacity": 7543,
    "ratio": 0.278,
    "total_hours": 10,
    "valid_days": 1,
    "channels_expected": 22,
    "occupancy_factor_assumed": 0.4
  }
}

Errores frecuentes

{
  "id": "campaign-uuid-here",
  "status": "Queued",
  "submitted_contacts": 30000,
  "callable_contacts": 29500,
  "skipped_contacts": 350,
  "message": "Lote encolado para import asíncrono. 29850 contacto(s) a procesar. Consulte el progreso en import_status_url.",
  "import_status_url": "/api/v1/external/batches/campaign-uuid-here/import-status",
  "capacity_warning": null
}

submitted_contacts es el conteo crudo del request (antes de partición/dedupe) — no lo compare con total_contacts del 201, que es post-import. callable_contacts/skipped_contacts ya vienen calculados (post partición/dedupe) porque se resuelven en la misma petición. Use import_status_url para seguir el progreso.

Progreso del import asíncrono de un lote (ver arriba). Responde 404 si el lote no existe, 403 si existe pero es de otra organización.

{
  "campaign_id": "campaign-uuid-here",
  "status": "processing",
  "submitted_contacts": 30000,
  "importable_contacts_count": 29850,
  "processed_contacts": 18000,
  "error_detail": null,
  "note": null
}

Lista sus lotes, con su estado y su avance de análisis.

Filtros

El bloque analysis

Cada lote trae cuántas llamadas ya tienen su análisis terminado (analyzed), cuántas hay en total (total) y un indicador ready que es true cuando todas están listas.

Trae un lote puntual, con los mismos campos del listado. Responde 404 si no existe.

Detiene un lote en curso. Las llamadas ya iniciadas terminan; no se marcan nuevas.

Solo funciona sobre lotes activos. Si el lote ya estaba pausado, responde 400 indicando su estado actual.

Reanuda un lote pausado, o activa uno en borrador.

Acepta opcionalmente max_concurrent_calls para ajustar cuántas llamadas simultáneas permitir al reanudar.

Solo funciona sobre lotes pausados o en borrador. Si el lote ya está activo, responde 400.

Lista los resultados de un lote. Por defecto trae solo las llamadas cuyo análisis ya terminó.

Filtros

Qué trae cada resultado

El bloque analysis

Cuando la llamada fue efectiva, aquí llegan los datos concretos que el agente logró recoger — una fecha de pago comprometida, un monto, un motivo — dentro de extracted_data, junto con un nivel de confianza y un estado que indica si el análisis se realizó o se omitió por no haber conversación que analizar.

Resumen agregado de un lote, sin traer las llamadas una por una.

Devuelve el total de llamadas, cuántas se completaron, cuántas fallaron, la duración promedio y el desglose por clasificación.

Parámetros

El detalle completo de una llamada, con los mismos campos del listado.

Marca un resultado como ya importado a su sistema.

{ "client_processed": true }

Devuelve el resultado actualizado.

Marca hasta 500 resultados de una vez. Es la forma recomendada de cerrar una sincronización.

{
  "result_ids": ["9f8e...", "1a2b..."],
  "client_processed": true
}

Qué recibe

La operación no es todo o nada: los que se pueden marcar se marcan, y los demás se le informan por separado.

Sube un archivo. Envío tipo formulario con el campo file.

Responde 201 con los datos del archivo y su enlace de descarga. Si el archivo no cumple alguna regla, responde 400 explicando el motivo.

Sube varios archivos en una sola petición. Envío tipo formulario con el campo files repetido una vez por archivo.

curl -X POST \
  "https://api.octocall.ai/api/v1/external/results/{result_id}/attachments/bulk" \
  -H "Authorization: Bearer sk_live_su_clave" \
  -F "files=@./expediente/comprobante.png" \
  -F "files=@./expediente/recibo.pdf" \
  -F "files=@./expediente/cedula.jpg"

Éxito parcial

Responde 200 aunque algunos archivos sean rechazados. Nunca es todo o nada: los válidos se guardan y los demás se le informan con su motivo, en la misma respuesta.

{
  "uploaded": [
    {
      "id": "9f8e...",
      "filename": "comprobante.png",
      "content_type": "image/png",
      "size_bytes": 245678,
      "url": "https://..."
    }
  ],
  "failed": [
    {
      "filename": "contrato.docx",
      "error": "El contenido del archivo no coincide con un tipo permitido."
    }
  ],
  "total_after": 1
}

total_after es cuántos adjuntos tiene la llamada después de esta petición, contando los que ya tenía.

Límites de la petición

Genera un enlace de descarga nuevo para un archivo que ya subió.

Úselo cuando el enlace que tenía haya caducado. Evita tener que volver a pedir el detalle completo de la llamada solo para refrescar una dirección.

Devuelve los mismos datos del archivo, con un enlace recién emitido.

Crea una clave nueva.

{
  "name": "Integración ERP - producción",
  "scopes": ["read", "write"],
  "expires_at": "2027-01-01T00:00:00"
}

Solo name es obligatorio. Si indica una fecha de expiración, debe ser futura.

Lista las claves de su organización. Por seguridad nunca devuelve la clave completa, solo su prefijo para poder identificarla.

De cada una obtiene su nombre, si sigue activa, cuándo expira y cuándo se usó por última vez — útil para detectar credenciales olvidadas.

La respuesta viene en data con el total en count.

Revoca una clave. Deja de funcionar de inmediato.

La clave no se borra: queda registrada como inactiva para conservar el historial de uso.