Integración de transcripciones con Notion: receta con API (2026)

The Working Paths

Hoy no existe una integración nativa de Notion para ConvertAudioToText en el marketplace de Notion. Lo que sí hay es una vía limpia a través de la API: registras un endpoint de webhook con la API de CATT, recibes un evento job.completed cuando termina una transcripción, recuperas la transcripción desde la URL devuelta y la escribes en una base de datos de Notion. Unas 120 líneas de Node.js, una tarde de configuración, y cada grabación de tu equipo se convierte en contenido de Notion totalmente buscable.

Tres patrones cubren la mayoría de los escenarios de equipo. Esta guía desarrolla por completo el patrón de fila de base de datos, con notas sobre los otros.

Una fila de base de datos por transcripción. Una base de datos "Transcripciones" con columnas para fecha, ponente, proyecto, resumen y un enlace al resultado. Ideal para equipos que filtran y ordenan entre muchas grabaciones.

Añadido a páginas de proyecto existentes. Cada transcripción añade bloques a una página de proyecto o reunión ya existente. Ideal para equipos donde las transcripciones forman parte de unas notas de proyecto más amplias.

Una página por ponente o entrevistado. Mantén un mapeo de ponente a ID de página y enruta las transcripciones en consecuencia. Útil para periodistas con fuentes recurrentes y equipos de ventas que hacen seguimiento de cuentas clave.

Paso 1: Crear la base de datos en Notion

En Notion, crea una base de datos de página completa con estas propiedades:

Copia el ID de la base de datos desde la URL. Es la cadena hexadecimal de 32 caracteres que sigue a la última barra y precede a cualquier parámetro de consulta ?v=.

Paso 2: Crear una integración de Notion

1. Ve a notion.so/my-integrations y haz clic en "New integration".
2. Ponle un nombre (por ejemplo, "Transcription Integration"), selecciona tu espacio de trabajo, elige el tipo Internal y envía el formulario.
3. Copia el Internal Integration Token. Desde septiembre de 2024, los tokens nuevos empiezan con ntn_ en lugar del prefijo antiguo secret_. Ambos formatos funcionan igual en las llamadas a la API.
4. Abre tu base de datos Transcripts en Notion, haz clic en el menú "...", ve a "Add connections" y selecciona tu integración.

La integración solo tiene acceso a las bases de datos que compartas explícitamente con ella.

Paso 3: Registra un webhook con CATT

Los webhooks en ConvertAudioToText requieren el plan Business. Registra tu endpoint:

curl -X POST https://api.convertaudiototext.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/catt",
    "events": ["job.completed", "job.failed"]
  }'

La respuesta incluye un campo secret. Guárdalo como CATT_WEBHOOK_SECRET en tu entorno. No podrás recuperar este valor después de crearlo.

Para la alternativa de polling (sin necesidad de webhook), consulta webhook vs polling para transcripciones.

Paso 4: El manejador del webhook

El payload de job.completed incluye un campo result_url que apunta a la transcripción completa. El manejador verifica la firma, comprueba el tipo de evento, obtiene la transcripción y luego escribe en Notion.

import express from 'express';
import { Client as NotionClient } from '@notionhq/client';
import crypto from 'crypto';

const app = express();
const notion = new NotionClient({ auth: process.env.NOTION_TOKEN });
const NOTION_DB_ID = process.env.NOTION_DATABASE_ID;

app.post(
  '/webhooks/catt',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const sigHeader = req.header('X-Webhook-Signature'); // "sha256=<hex>"
    const [, sig] = (sigHeader || '').split('=');
    const expected = crypto
      .createHmac('sha256', process.env.CATT_WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');

    if (!sig || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
      return res.status(401).send('Bad signature');
    }

    const event = JSON.parse(req.body.toString());
    if (event.event !== 'job.completed') return res.sendStatus(200);

    // Fetch the full transcript from the result URL
    const result = await fetch(event.data.result_url, {
      headers: { Authorization: `Bearer ${process.env.CATT_API_KEY}` }
    }).then(r => r.json());

    await createNotionPage({
      jobId: event.data.job_id,
      language: event.data.language,
      durationSeconds: event.data.duration,
      completedAt: event.data.completed_at,
      resultUrl: event.data.result_url,
      transcript: result.transcript,
      summary: result.summary,
      utterances: result.utterances,
      filename: result.filename,
    });

    res.sendStatus(200);
  }
);

Los campos del evento que siempre están presentes en job.completed son: event, timestamp, data.job_id, data.status, data.created_at, data.language, data.duration, data.completed_at, data.result_url. El texto completo de la transcripción, el resumen y las intervenciones provienen de la consulta al resultado, no del propio evento.

Resumen más transcripción: los dos bloques que tu base de datos de Notion necesita

Paso 5: Escribir la página en Notion

async function createNotionPage(data) {
  const transcriptBlocks = buildTranscriptBlocks(data.utterances || []);

const page = await notion.pages.create({
    parent: { database_id: NOTION_DB_ID },
    properties: {
      Title: {
        title: [{ text: { content: data.filename || `Transcript ${data.completedAt?.slice(0, 10)}` } }]
      },
      Date: { date: { start: data.completedAt?.slice(0, 10) || new Date().toISOString().slice(0, 10) } },
      Language: { select: { name: data.language || 'auto' } },
      Duration: { number: data.durationSeconds },
      'Result URL': { url: data.resultUrl },
      Summary: {
        rich_text: [{ text: { content: (data.summary || '').slice(0, 2000) } }]
      }
    }
  });

  // Añadir bloques de transcripción en lotes de 100 (límite de la API de Notion)
  if (transcriptBlocks.length > 0) {
    await appendBlocksInBatches(page.id, transcriptBlocks);
  }
}

function buildTranscriptBlocks(utterances) {
  const blocks = [];

  blocks.push({
    object: 'block',
    type: 'heading_2',
    heading_2: { rich_text: [{ text: { content: 'Transcript' } }] }
  });

  for (const u of utterances) {
    // El contenido de rich_text en Notion está limitado a 2.000 caracteres por bloque
    const label = u.speaker ? `[${u.speaker}] ` : '';
    const text = (label + (u.text || '')).slice(0, 2000);
    blocks.push({
      object: 'block',
      type: 'paragraph',
      paragraph: { rich_text: [{ text: { content: text } }] }
    });
  }

  return blocks;
}

async function appendBlocksInBatches(pageId, blocks) {
  for (let i = 0; i < blocks.length; i += 100) {
    const batch = blocks.slice(i, i + 100);
    await notion.blocks.children.append({ block_id: pageId, children: batch });
    if (i + 100 < blocks.length) {
      await new Promise(r => setTimeout(r, 400)); // mantenerse dentro de la media de 3 peticiones por segundo
    }
  }
}

El límite de 100 bloques por petición es una restricción estricta de la API de Notion. La pausa de 400ms te mantiene dentro de la media de 3 peticiones por segundo. Para grabaciones muy largas (más de 100 intervenciones), esto significa que la escritura tarda unos segundos; es aceptable para un paso de post-procesado asíncrono.

Variación: Añadir a una página de proyecto existente

Si las transcripciones deben ir dentro de páginas de proyecto en lugar de una base de datos independiente, usa blocks.children.append con el ID de una página existente:

async function appendToProjectPage(projectPageId, data) {
  const divider = { object: 'block', type: 'divider', divider: {} };
  const heading = {
    object: 'block',
    type: 'heading_3',
    heading_3: {
      rich_text: [{ text: { content: `Meeting transcript ${data.completedAt?.slice(0, 10)}` } }]
    }
  };
  const transcriptBlocks = buildTranscriptBlocks(data.utterances || []);
  await appendBlocksInBatches(projectPageId, [divider, heading, ...transcriptBlocks]);
}

Rutas sin código

Si prefieres no escribir un servidor, hoy tienes dos opciones que funcionan.

Zapier. El flujo sería: un disparador webhook (que captura el evento job.completed de CATT), luego un paso de código para obtener la URL del resultado y, por último, una acción de "Crear elemento en base de datos" en Notion. Los zaps de varios pasos requieren un plan de pago en Zapier. Zapier se configura más rápido que el código personalizado, pero es más difícil de depurar cuando las escrituras en Notion fallan en silencio.

n8n. Existe una plantilla de flujo de trabajo publicada para n8n que encadena la transcripción con Whisper y la vuelca en una página de Notion. La versión autoalojada de n8n es gratuita, con ejecuciones ilimitadas, y te permite mantener las grabaciones fuera de nubes de terceros. Make.com también tiene un módulo de Notion que funciona igual. Consulta automatizar transcripciones con Zapier para ver un recorrido paso a paso sin código.

Fireflies.ai tiene una integración nativa con Notion (sin necesidad de Zapier) que envía resúmenes de reuniones, elementos de acción y un enlace a la transcripción a una base de datos de Notion después de cada llamada grabada. Es la opción adecuada si lo que necesitas principalmente son bots para reuniones, más que subidas de archivos.

Nota sobre la versión de la API de Notion (2026)

La versión 2026-03-11 de la API de Notion introdujo tres cambios importantes que conviene conocer si estás actualizando integraciones existentes:

• El parámetro after en append-block-children se sustituye por position.
• El campo archived se reemplaza por in_trash.
• El tipo de bloque transcription pasa a llamarse meeting_notes.

Si estás escribiendo código nuevo hoy, instala @notionhq/client en la versión 5.12.0 o posterior y define notionVersion: "2026-03-11" al construir el cliente si quieres el comportamiento más reciente. Los formatos de token antiguos (prefijo secret_) siguen funcionando.

Patrones de producción

Equipos de periodismo. Cada entrevista grabada acaba en una base de datos de Notion con búsqueda. Los filtros por propiedad de tema, fuente y fecha permiten a los reporteros extraer todas las citas de una fuente en segundos. Para el flujo completo de entrevistas, consulta cómo transcribir una grabación de entrevista.

Equipos de éxito de cliente. Cada llamada con un cliente se guarda en una página de Notion por cliente. Preparar la revisión trimestral de negocio pasa de horas reescuchando a 15 minutos de lectura.

Producción de podcasts. Cada episodio tiene su página de Notion con transcripción, resumen y la URL del resultado para edición. El productor entrega el material al equipo de redes sin compartir el archivo de audio original. Consulta mejor transcripción para podcasts para comparativas de precisión entre herramientas habituales.

Si solo necesitas una transcripción limpia sin un servidor de webhooks, ConvertAudioToText gestiona la subida y genera una salida con etiquetas de hablante que puedes copiar, pegar o exportar directamente a cualquier página de Notion.

Para construir la capa de actas de reunión sobre la transcripción en bruto, crear actas de reunión a partir de audio cubre los patrones de salida estructurada que encajan de forma natural con las propiedades de las bases de datos de Notion.

Preguntas frecuentes

¿ConvertAudioToText tiene una integración nativa con Notion?

Todavía no. No hay una conexión de un clic en el marketplace de integraciones de Notion. El camino que funciona es registrar un endpoint de webhook (plan Business) que reciba un evento job.completed, luego obtener la transcripción mediante result_url y escribirla en Notion usando la API de Notion.

¿Qué límites de la API de Notion debería tener en cuenta?

La API de Notion permite una media de 3 solicitudes por segundo por integración. Cada llamada a append-block-children acepta como máximo 100 bloques. El contenido de texto enriquecido por bloque está limitado a 2.000 caracteres. Para transcripciones largas, agrupa los bloques en lotes de 100 con una pequeña pausa entre llamadas.

¿Necesito un plan de pago de Notion para usar la API?

No. La API de Notion es gratuita en todos los planes de Notion, incluido el nivel gratuito. Solo necesitas un plan de pago para funciones de Notion como compartir con invitados más allá de ciertos límites. Los límites de tasa de la API son los mismos en todos los planes.

¿Cuál es el camino sin código para enviar transcripciones a Notion?

Dos buenas opciones: Zapier (se necesita el nivel de pago para zaps de varios pasos) te permite capturar un webhook y crear una página de Notion sin código. n8n Cloud tiene una plantilla de Whisper a Notion, y la versión autoalojada funciona gratis. Ambos caminos sirven para flujos simples de transcripción a página; el código personalizado es mejor para bloques con etiquetas de orador, procesamiento por lotes y archivos largos.

Fuentes

• API de Notion: Límites de solicitudes - verificado el 02/07/2026
• API de Notion: Añadir bloques hijos - verificado el 02/07/2026
• Guía de actualización de la API de Notion del 11/03/2026 - verificado el 02/07/2026
• Guía de integración de Fireflies con Notion - verificado el 02/07/2026
• Marketplace de integraciones de Notion - verificado el 02/07/2026 (no aparecen conectores nativos de transcripción)
• @notionhq/client en npm - la versión 5.12.0 es compatible con la versión de API 2026-03-11