Construye sobre Neural Summary

Cómo funciona

Envías una grabación con metadatos opcionales. Neural Summary la transcribe, redacta el resumen y genera las salidas de las lentes que pediste. Cuando termina, enviamos un webhook firmado a tu endpoint. Desde ahí llevas el resultado a donde quieras: un CRM, una bandeja de entrada, una base de datos o una automatización en Zapier, Make o n8n.

Inicio rápido

1. Crea una clave de API. Abre Ajustes › Integraciones y copia la clave. Solo se muestra una vez.

# Create an API key in Settings > Integrations. It is shown once.
API_KEY="ns_live_..."

2. Sube un archivo de audio. Para archivos pequeños, multipart es suficiente.

curl -X POST https://neuralsummary.com/integrations/v1/transcriptions \
  -H "Authorization: Bearer $API_KEY" \
  -F "audio=@./call.mp3;type=audio/mpeg" \
  -F 'metadata={"title":"Call with Acme","callMetadata":{"callerName":"Jane Doe","callerEmail":"[email protected]"},"integrationOptions":{"lensTemplates":["followUpEmail"]}}'

3. Recibe el resultado. Suscribe un webhook (recomendado) o consulta la transcripción hasta que esté completa.

curl -H "Authorization: Bearer $API_KEY" \
  https://neuralsummary.com/integrations/v1/transcriptions/<id>

Autenticación

Cada petición a /integrations/v1/* necesita una clave de API, en cualquiera de estas cabeceras:

• Authorization: Bearer ns_live_...
• x-api-key: ns_live_...

Las claves se gestionan en Ajustes › Integraciones. Guardamos un hash bcrypt más los primeros caracteres para mostrarlos, nunca la clave en claro. Revoca cualquier clave desde la misma pantalla y deja de funcionar al instante. Una clave hereda los límites del plan de su propietario, y las subidas por integración cuentan para la misma cuota mensual que la app.

Endpoints

{
  "fileName": "long-call.m4a",
  "contentType": "audio/x-m4a",
  "fileSize": 524288000
}

{
  "storagePath": "uploads/<your-uid>/...long-call.m4a",
  "fileName": "long-call.m4a",
  "fileSize": 524288000,
  "contentType": "audio/x-m4a",
  "title": "Sales call with Acme",
  "callMetadata": { "callerEmail": "[email protected]" },
  "integrationOptions": { "lensTemplates": ["followUpEmail", "salesEmail"] }
}

Plantillas de lentes

Pasa cualquiera de estos ID a integrationOptions.lensTemplates para generarlos junto con el resumen. El resumen se produce siempre. Los ID desconocidos devuelven 400 Bad Request.

Webhooks

Añade un endpoint en Ajustes › Integraciones › Webhooks. Enviamos un POST firmado cuando termina una transcripción procedente de una integración. Suscríbete a uno o a ambos eventos: v1.transcription.completed y v1.transcription.failed.

Payload

{
  "id": "evt_aBcDeFgHiJkLmNoP",
  "event": "v1.transcription.completed",
  "createdAt": "2026-05-16T10:13:45.123Z",
  "data": {
    "transcriptionId": "tr_xyz",
    "title": "Call with Acme",
    "durationSeconds": 312,
    "detectedLanguage": "english",
    "callMetadata": {
      "callerName": "Jane Doe",
      "callerEmail": "[email protected]",
      "callerPhone": "+31612345678",
      "callSource": "ringcentral",
      "externalRef": "call_98765"
    },
    "summary": { "...": "SummaryV2: title, intro, sections, decisions, nextSteps" },
    "generatedAnalysisIds": ["ana_abc", "ana_def"],
    "conversationCategory": "sales-call",
    "completedAt": "2026-05-16T10:13:45.000Z"
  }
}

Verificar la firma

La cabecera X-NeuralSummary-Signature tiene la forma t=<unix-seconds>,v1=<hex>. El HMAC es el SHA-256 de <seconds>.<raw-body> con tu secreto de webhook. Es el mismo formato que usa Stripe. Rechaza todo lo que tenga más de cinco minutos.

const crypto = require('crypto');

// Header format: t=<unix-seconds>,v1=<hex-hmac>
function verify(rawBody, headerValue, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    headerValue.split(',').map((p) => p.split('=')),
  );
  const ts = parseInt(parts.t, 10);
  if (Math.abs(Date.now() / 1000 - ts) > toleranceSeconds) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(parts.v1, 'hex'),
  );
}

Reintentos

Una respuesta distinta de 2xx se reintenta hasta cinco veces con backoff exponencial: 30 s, 1 min, 2 min, 4 min, 8 min. No reintentamos respuestas 4xx, salvo 408 y 429. Las entregas fallidas aparecen en Entregas recientes con un botón de Reenviar en un clic.

Zapier, Make y n8n

No necesitas escribir un manejador de webhooks. Zapier, Make y n8n tienen una acción HTTP genérica que llama a nuestros endpoints, además de un disparador catch-hook que recibe nuestro webhook. Una receta típica convierte una llamada grabada en un borrador de correo de seguimiento:

El esquema es el mismo en cada herramienta: usa el módulo o la acción HTTP para las tres llamadas de subida y el disparador catch-hook para el webhook. Toma data.callMetadata.callerEmail del webhook como destinatario y obtén el contenido de la lente con el endpoint de polling usando data.transcriptionId.

Límites y seguridad

• Se requiere el plan Enterprise (los administradores pueden saltárselo para pruebas).
• Límites por clave: 30 subidas multipart, 60 URL de subida y 120 lecturas por polling por minuto.
• Hasta 5 GB por archivo, igual que el límite de subida de Enterprise.
• Las URL de webhook deben usar HTTPS en producción. Los hosts loopback se rechazan.
• Las claves de API se guardan con hash bcrypt. Los secretos de webhook se muestran bajo demanda; trátalos como una contraseña.