Campañas¶

Endpoints para iniciar, controlar, programar y listar campañas de llamadas.

Base URL: https://api.neuronstudio.ai

Autenticación: API Key (X-API-Key) o JWT (Authorization: Bearer). Las mutaciones (start, start-upload, stop, pause, resume, schedule, delete) requieren scope full; una key con scope read recibe 403.

No existe modo sandbox / dry-run. Un start exitoso dispara llamadas reales de inmediato. Para probar sin impacto, usa una lista de 1 contacto con tu propio número, fuera de horario productivo.

Cómo detectar éxito: cualquier código 2xx. Los códigos exactos de éxito pueden variar entre endpoints y cambiar entre versiones de la API (por ejemplo, un endpoint que acepta trabajo asincrónico puede responder 200, 201 o 202). No compares el código por igualdad exacta (if status == 200). Verifica el rango: if 200 <= status < 300, o usa el helper de tu cliente HTTP (resp.ok en JavaScript, resp.raise_for_status() en requests). Los códigos de éxito que aparecen en los ejemplos de abajo son ilustrativos, no un contrato.

Índice¶

Columnas CSV requeridas por tipo de campaña¶

La lista de leads se entrega como CSV. Las columnas requeridas dependen del campaign_type:

Reglas del CSV:

• to_number: teléfono en formato E.164 (+525512345678 — empieza con +, incluye código de país, sin espacios ni guiones).
• lead_id: identificador único por lead.
• client_name: nombre del cliente.
• debt: monto de deuda (solo collections).
• Las columnas extra (ej. Fecha_Limite_Pago) se preservan y se pasan al motor de llamadas.
• Tamaño máximo del CSV: 10 MB.
• Las filas sin to_number o sin lead_id se saltan.
• Puedes descargar la plantilla con GET /api/csv-template?type=<tipo>.

POST /api/campaign/start¶

Inicia una campaña con el CSV embebido como texto en el body JSON.

Body (JSON)¶

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s -X POST "$API_BASE_URL/api/campaign/start" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cobranza Enero",
    "csv_content": "to_number,lead_id,client_name,debt\n+525512345678,L001,Juan,5000",
    "agent_id": "agent_abc123",
    "campaign_type": "collections",
    "customer_email": "ops@cliente.com"
  }'

Ejemplo de response (éxito — 2xx)¶

{
  "success": true,
  "campaign_id": 123,
  "total_leads": 150,
  "agent_id": "agent_abc123",
  "campaign_type": "collections",
  "message": "Campaign 'Cobranza Enero' started"
}

Trata cualquier 2xx como éxito y lee el body; no compares el código por igualdad exacta.

Guarda el campaign_id: lo necesitas para monitorear, controlar y consultar resultados. La campaña empieza a llamar de inmediato.

Códigos de error¶

POST /api/campaign/start-upload¶

Igual que start, pero subiendo un archivo .csv vía multipart/form-data en lugar de pegar el texto. Validación y comportamiento idénticos.

Campos del formulario (multipart/form-data)¶

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s -X POST "$API_BASE_URL/api/campaign/start-upload" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef" \
  -F "file=@leads.csv" \
  -F "name=Cobranza Enero" \
  -F "agent_id=agent_abc123" \
  -F "campaign_type=collections"

Con Python:

import requests

API_BASE_URL = "https://api.neuronstudio.ai"
headers = {"X-API-Key": "nrn_live_0123456789abcdef0123456789abcdef"}

with open("leads.csv", "rb") as f:
    resp = requests.post(
        f"{API_BASE_URL}/api/campaign/start-upload",
        headers=headers,
        files={"file": ("leads.csv", f, "text/csv")},
        data={"name": "Cobranza Enero", "agent_id": "agent_abc123"},
    )
print(resp.json())

Ejemplo de response (éxito — 2xx)¶

Idéntica a start (mismo criterio: cualquier 2xx es éxito):

{
  "success": true,
  "campaign_id": 123,
  "total_leads": 150,
  "agent_id": "agent_abc123",
  "campaign_type": "collections",
  "message": "Campaign 'Cobranza Enero' started"
}

Códigos de error¶

Mismas semánticas que start (400 / 401 / 403 / 409 / 422 / 429). El 400 incluye el caso de archivo vacío, ilegible o mayor a 10 MB.

GET /api/campaign/status¶

Estado en tiempo real de la campaña activa de tu organización.

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s "$API_BASE_URL/api/campaign/status" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef"

Ejemplo de response (200)¶

{
  "success": true,
  "status": {
    "state": "running",
    "campaign_id": 123,
    "active_calls": 3,
    "queue_size": 45
  },
  "campaign": {
    "id": 123,
    "name": "Cobranza Enero",
    "total_leads": 150,
    "leads_called": 105,
    "leads_pending": 45,
    "status": "running"
  },
  "global_status": {
    "total_active_calls": 15,
    "available_slots": 35
  }
}

Cuando no hay campaña activa, status.state es "idle" y campaign es null.

Códigos de error¶

POST /api/campaign/stop¶

Detiene la campaña activa de forma permanente. No se puede reanudar; los resultados generados hasta ese momento quedan guardados.

Body (JSON)¶

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s -X POST "$API_BASE_URL/api/campaign/stop" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": 123 }'

Ejemplo de response (200)¶

{ "success": true, "message": "Campaign stopped", "campaign_id": 123 }

Códigos de error¶

POST /api/campaign/pause¶

Pausa la campaña activa. Las llamadas en curso terminan normalmente, no se inician nuevas y la cola se preserva. Se puede reanudar con resume.

Body (JSON)¶

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s -X POST "$API_BASE_URL/api/campaign/pause" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": 123 }'

Ejemplo de response (200)¶

{ "success": true, "message": "Campaign paused", "campaign_id": 123 }

Códigos de error¶

POST /api/campaign/resume¶

Reanuda una campaña pausada.

Body (JSON)¶

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s -X POST "$API_BASE_URL/api/campaign/resume" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": 123 }'

Ejemplo de response (200)¶

{ "success": true, "message": "Campaign resumed", "campaign_id": 123 }

Códigos de error¶

POST /api/campaign/schedule¶

Programa una campaña para que arranque en una fecha/hora futura.

Body (JSON)¶

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s -X POST "$API_BASE_URL/api/campaign/schedule" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cobranza Febrero",
    "csv_content": "to_number,lead_id,client_name,debt\n+525512345678,L001,Juan,5000",
    "scheduled_at": "2026-02-20T09:00:00Z",
    "agent_id": "agent_abc123",
    "campaign_type": "collections"
  }'

Ejemplo de response (201)¶

{
  "success": true,
  "campaign_id": 124,
  "scheduled_at": "2026-02-20T09:00:00+00:00",
  "total_leads": 150
}

Estos cuatro campos son todo lo que devuelve el endpoint: no hay campaign_type ni message en la respuesta. El scheduled_at que te devolvemos es el que mandaste, normalizado a ISO 8601 con offset numérico (+00:00), no con sufijo Z; si lo enviaste sin zona horaria, se interpreta como UTC.

Códigos de error¶

GET /api/campaign/scheduled¶

Lista las campañas programadas (aún no iniciadas) de tu organización.

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s "$API_BASE_URL/api/campaign/scheduled" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef"

Ejemplo de response (200)¶

⚠️ Este endpoint devuelve un array JSON directo, no un objeto envolvente. No hay campo success ni campo scheduled: el cuerpo es la lista. Si tu cliente hace resp.json()["scheduled"] va a fallar. Usa resp.json() tal cual y recórrelo. Cuando no hay campañas programadas, el cuerpo es [].

[
  {
    "id": 124,
    "name": "Cobranza Febrero",
    "status": "scheduled",
    "scheduled_at": "2026-02-20T09:00:00+00:00",
    "total_leads": 150,
    "campaign_type": "collections",
    "agent_id": "agent_abc123",
    "created_at": "2026-02-14T18:32:05+00:00"
  }
]

Campos de cada elemento¶

La lista viene ordenada por scheduled_at ascendente (la próxima a arrancar, primero).

Códigos de error¶

DELETE /api/campaign/scheduled/{campaign_id}¶

Cancela una campaña programada antes de que arranque.

Parámetros de path¶

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s -X DELETE "$API_BASE_URL/api/campaign/scheduled/124" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef"

Ejemplo de response (200)¶

{ "success": true, "message": "Scheduled campaign cancelled", "campaign_id": 124 }

Códigos de error¶

GET /api/campaigns¶

Lista las campañas de tu organización. Se puede filtrar por tipo.

Parámetros de query¶

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s "$API_BASE_URL/api/campaigns?type=collections" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef"

Ejemplo de response (200)¶

{
  "success": true,
  "campaigns": [
    {
      "campaign_id": 123,
      "name": "Cobranza Enero",
      "campaign_type": "collections",
      "status": "completed",
      "total_leads": 150
    },
    {
      "campaign_id": 124,
      "name": "Cobranza Febrero",
      "campaign_type": "collections",
      "status": "scheduled",
      "total_leads": 150
    }
  ]
}

Códigos de error¶

GET /api/csv-template¶

Descarga una plantilla CSV con las columnas correctas para un tipo de campaña.

Parámetros de query¶

Ejemplo de request¶

API_BASE_URL="https://api.neuronstudio.ai"

curl -s "$API_BASE_URL/api/csv-template?type=collections" \
  -H "X-API-Key: nrn_live_0123456789abcdef0123456789abcdef" \
  -o plantilla_collections.csv

Ejemplo de response (200)¶

Cuerpo: texto CSV con la fila de cabecera correspondiente al tipo. Por ejemplo, para collections:

to_number,lead_id,client_name,debt
+525512345678,L001,Juan Pérez,5000

Códigos de error¶

GET /api/campaigns/{campaign_id}/skip-log¶

Devuelve a quién no se llamó y por qué, para una campaña dada.

Antes de armar la cola de discado, la plataforma descarta contactos que no corresponde llamar: quien ya se comprometió a pagar, quien tiene una devolución agendada, quien pidió no ser contactado. Cada descarte queda registrado con su motivo.

Es el endpoint que responde la pregunta "subí 5.000 contactos y veo 4.200 llamadas, ¿qué pasó con los otros 800?".

Parámetros de path¶

Parámetros de query¶

Ejemplo de request¶

curl "https://api.neuronstudio.ai/api/campaigns/123/skip-log" \
  -H "X-API-Key: nrn_live_abcdef1234567890abcdef1234567890"

Ejemplo de response (200)¶

{
  "rows": [
    {
      "id": 9012,
      "campaign_id": 123,
      "contact_phone": "+525512345678",
      "contact_id": "3f1c8a2e-1b4d-4c7a-9f21-8e0b5d6a7c93",
      "reason": "promise_future",
      "detail": "Payment promised for 2026-08-25",
      "skipped_at": "2026-08-17T14:02:11+00:00"
    }
  ],
  "counts": {
    "promise_future": 512,
    "callback_pending": 203,
    "refused": 85
  },
  "total_skipped": 800
}

Campos de la respuesta¶

Para reportar, usa counts y total_skipped. rows sirve para auditar casos puntuales.

Campos de cada fila de rows:

Motivos posibles (reason)¶

Códigos de error¶

Un total_skipped en 0 significa que no se descartó a nadie, no que el registro haya fallado. Si tu CSV y tus llamadas no cuadran y el skip-log está vacío, la diferencia está en el CSV: las filas sin to_number o sin lead_id se descartan antes de llegar a este registro.