Cómo conectar agentes de voz con IA a tu CRM: HubSpot, Salesforce y Pipedrive (con el código de webhook)

Cómo conectar agentes de voz con IA a tu CRM: HubSpot, Salesforce y Pipedrive (con el código de webhook)

En un proyecto con Vapi que entregamos a principios de este año, la ruta agente de voz → nuestra API interna de búsqueda → lectura de contacto en HubSpot registró 410 ms en p50 y 1.240 ms en p95. Ese número es el motivo de que este artículo exista. La integración de un agente de voz con un CRM vive o muere según un reloj que controla el interlocutor. Si lo cablearas como si fuera una sincronización de Zapier, el agente quedaría en silencio a mitad de frase mientras el webhook avanza a paso de tortuga. La solución no son más llamadas a la API. Son dos patrones, un timeout y una frase de respaldo. Los tres están aquí, con código que puedes desplegar.

La mayoría de guías sobre este tema explican el concepto y luego te venden su producto. Ninguna incluye el handler. Aquí vamos al revés.

Puntos clave

• Los agentes de voz se conectan a un CRM de dos formas: function calling para lecturas en vivo durante la llamada, webhooks para escrituras tras colgar.
• Las lecturas durante una llamada necesitan un presupuesto de 5 segundos más una frase de respaldo hablada para que el interlocutor nunca escuche silencio muerto.
• Mapea los datos de la llamada a campos del CRM con una clave de idempotencia para que los webhooks reintentados no creen registros duplicados.
• Pipedrive no tiene webhook para cambios en campos personalizados: hay que hacer polling a dealFields según un calendario.

Qué significa realmente "integración de agente de voz con CRM" (2 métodos, no uno)

La integración de agente de voz con CRM conecta un agente de voz a tu CRM de dos formas distintas: function calling para lecturas de datos en vivo mientras el interlocutor está al teléfono, y webhooks para escribir el resultado de la llamada tras colgar. La lectura en vivo personaliza la conversación; la escritura post-llamada registra lo que ocurrió. Corren en relojes distintos y fallan de formas distintas.

El modelo mental en una frase: el function calling es el agente de voz haciéndole una pregunta al CRM a mitad de frase; un webhook es el agente archivando su informe después de colgar.

Function calling: leer datos en vivo

El function calling es la forma en que un LLM pausa la generación de texto, llama a una herramienta externa que has definido y pliega el resultado en lo que dice a continuación. Para un agente de voz, esa herramienta es "buscar a este interlocutor en el CRM". El modelo decide que necesita el dato, tu servidor lo obtiene, y el agente saluda al interlocutor por su nombre con el nivel de plan que tiene. Si quieres ver la mecánica en profundidad, nuestra guía de function calling desglosa el esquema de definición de herramientas. El inconveniente: esto ocurre en vivo, así que compite contra la paciencia del interlocutor.

Webhooks: escribir datos después

Un webhook es una petición POST que recibe tu servidor cuando algo termina. Para los agentes de voz, el principal es el evento de fin de llamada: la plataforma te envía el transcript, el resumen, la disposición y la URL de grabación en el momento en que la llamada termina. Tú tomas ese payload y lo escribes en el CRM como una Actividad, y luego mueves la etapa del trato. Aquí no hay presión de tiempo. El interlocutor se ha ido. Puedes reintentar, poner en cola y reconciliar.

La mayoría de las integraciones en producción usan ambas. Leer en vivo, escribir después.

La arquitectura: qué ocurre en una llamada entrante, de principio a fin

Una integración de agente de voz con CRM sigue un ciclo de vida fijo de cinco pasos en cada llamada entrante. La llamada llega, el agente lee el registro del interlocutor en vivo mediante una function call, se produce la conversación, se dispara un webhook de fin de llamada, y tu handler escribe el resultado en el CRM y notifica a un humano si hace falta. Cada ejemplo de código en este artículo cuelga de uno de esos cinco pasos.

El flujo, paso a paso:

1. Llega la llamada entrante. La plataforma (Vapi, Retell, o tu propia pila de agente de voz) responde e identifica al interlocutor por número de teléfono.
2. Búsqueda en vivo (function call). El agente llama a tu herramienta de búsqueda, que consulta el CRM y devuelve el contacto, la etapa del trato y el contexto reciente.
3. Conversación. El agente habla, llamando opcionalmente a más herramientas (consultar citas disponibles, buscar un pedido).
4. Webhook de fin de llamada. La llamada termina, la plataforma envía un informe de fin de llamada a tu servidor vía POST.
5. Escritura en CRM + traspaso. Tu handler registra la Actividad, define la disposición, mueve el trato y crea una tarea para el representante humano con todo el contexto.

El diagrama de portada mapea esto exactamente: una flecha entrante, una bifurcación en "lectura en vivo" y "escritura post-llamada", tres tarjetas de destino de CRM y un nodo de traspaso. Tenlo presente. Todo lo que viene a continuación es rellenar esas cajas.

Leer datos del CRM durante la llamada (y por qué tienes un presupuesto de 5 segundos)

Sí, un agente de voz puede obtener datos del CRM durante una llamada. Usa una function call que llega a tu endpoint de búsqueda y devuelve el resultado antes de la siguiente frase del agente. La restricción es el tiempo. Según la documentación de server events de Vapi, las function tool calls corren contra un timeout, y en una llamada en vivo tu techo real es la paciencia del interlocutor, no la del API. Presupuesta cinco segundos y ten un respaldo.

Aquí está la parte que nadie en los resultados de búsqueda mide. En nuestra ruta Vapi → API interna de búsqueda → lectura de contacto en HubSpot, registramos 410 ms en p50 y 1.240 ms en p95 de ida y vuelta a lo largo de varios miles de llamadas. La mayoría de lecturas son rápidas. Pero la cola del p95 (backoff por límite de tasa de HubSpot, un lambda frío, una consulta de asociación lenta) es donde las llamadas se quedan en silencio. Por eso pusimos el timeout de la herramienta function call en 5 segundos: cómodamente por encima del p95, cómodamente por debajo del punto en que un humano dice "¿hola? ¿hay alguien ahí?".

Y aquí está la regla que importa: si la búsqueda en tu CRM tarda más de lo que soporta el interlocutor, el agente debería decir algo. Nunca hay que guardar silencio. El silencio muerto es la forma más rápida de perder una llamada. En nuestros proyectos el agente pronuncia una frase de respaldo en el instante en que la herramienta agota el tiempo: "Dame un momento, ahora mismo lo consulto." El interlocutor escucha una pausa que suena humana, no un bot roto.

Esta es la definición de la herramienta function call que usamos para una búsqueda en vivo en el CRM:

{
  "type": "function",
  "function": {
    "name": "lookup_crm_contact",
    "description": "Look up the caller in the CRM by phone number before greeting them. Returns name, plan, and open deal stage.",
    "parameters": {
      "type": "object",
      "properties": {
        "phone": {
          "type": "string",
          "description": "Caller phone number in E.164 format"
        }
      },
      "required": ["phone"]
    }
  },
  "server": {
    "url": "https://api.yourdomain.com/voice/crm-lookup",
    "timeoutSeconds": 5
  }
}

Dos cosas hacen que esto sea seguro para una llamada de voz. El techo timeoutSeconds: 5 evita que el agente espere indefinidamente. Y server.url apunta a tu endpoint, no al CRM directamente, por lo que tú controlas el caché, los reintentos y la forma de lo que vuelve. En nuestra experiencia, poner una API interna entre el agente y el CRM es la única decisión que más diferencia hace; es donde viven la lógica de respaldo y el mapeo de campos.

Escribir después de la llamada: registrar la Actividad, el resumen y la disposición

Para registrar una llamada de agente de voz con IA en un CRM, recibes el webhook de fin de llamada de la plataforma, extraes el transcript, el resumen y la disposición, luego haces un POST de una Actividad de llamada al CRM y estableces el estado del lead. Aquí no hay presupuesto de latencia (el interlocutor se fue), así que es aquí donde haces las escrituras pesadas, los reintentos y los movimientos de etapa del trato que nunca arriesgarías durante la llamada.

El payload de fin de llamada (Vapi lo llama el evento end-of-call-report, según su documentación de server events) lleva el transcript, un resumen generado, el resultado de la llamada, la URL de grabación y la duración de la llamada. Tu trabajo es mapear eso en una Actividad del CRM y avanzar el registro.

Aquí hay un handler en Node/TypeScript listo para usar que recibe el informe y escribe un engagement de llamada en HubSpot, luego avanza la etapa del trato. El endpoint POST /crm/v3/objects/calls y el patrón de asociación al contacto vienen directamente de la guía de la API de llamadas de HubSpot:

import express from "express";

const app = express();
app.use(express.json());

const HUBSPOT_TOKEN = process.env.HUBSPOT_TOKEN!;
const seen = new Set<string>(); // swap for Redis/DB in production

app.post("/voice/end-of-call", async (req, res) => {
  const report = req.body.message; // Vapi end-of-call-report
  if (report?.type !== "end-of-call-report") return res.sendStatus(200);

  const key = report.call.id; // idempotency key (see field-mapping section)
  if (seen.has(key)) return res.sendStatus(200);
  seen.add(key);

  const { contactId, dealId } = report.call.metadata; // set when call started

  // 1. Write the call Activity (engagement)
  await fetch("https://api.hubapi.com/crm/v3/objects/calls", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${HUBSPOT_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      properties: {
        hs_call_title: "AI Voice Agent Call",
        hs_call_body: report.summary,
        hs_call_duration: String(report.durationMs ?? 0),
        hs_call_recording_url: report.recordingUrl ?? "",
        hs_call_status: "COMPLETED",
        hs_timestamp: Date.now(),
      },
      associations: [
        {
          to: { id: contactId },
          types: [{ associationCategory: "HUBSPOT_DEFINED", associationTypeId: 194 }],
        },
      ],
    }),
  });

  // 2. Move the deal stage based on disposition
  if (dealId && report.analysis?.disposition === "qualified") {
    await fetch(`https://api.hubapi.com/crm/v3/objects/deals/${dealId}`, {
      method: "PATCH",
      headers: {
        Authorization: `Bearer ${HUBSPOT_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ properties: { dealstage: "qualifiedtobuy" } }),
    });
  }

  res.sendStatus(200);
});

app.listen(3000);

Eso es lo que prometía el título: un handler desplegable, no una descripción de uno. ¿No quieres escribir y alojar esto a mano? Una alternativa sin código como n8n puede recibir el mismo webhook y escribir en el CRM con nodos visuales, a costa de algo de control sobre los reintentos y el manejo de errores.

Mapear datos de la llamada a campos del CRM (sin crear duplicados)

El mapeo de campos conecta cada dato de la llamada con un objeto y campo específico del CRM: la intención del interlocutor a una propiedad del trato, la disposición al estado del lead, el resumen al cuerpo de la Actividad. Dos problemas de producción aparecen aquí: formatear los datos para que suenen bien cuando el agente los lee en voz alta, y usar una clave de idempotencia para que un webhook reintentado no cree un segundo registro para la misma llamada.

En nuestros proyectos mantenemos el mapeo en un objeto de configuración para que personas sin perfil técnico puedan editarlo sin tocar el handler. Esta es la forma de uno real:

Primer problema: formato adaptado al habla. Un agente de voz que lee JSON en bruto a un interlocutor suena roto. Formatea los datos del CRM en una frase antes de que lleguen al TTS. No devuelvas {"plan":"pro","renewed":"2026-03"} al modelo. Devuelve "tiene el plan Pro, renovado el pasado marzo" para que el agente lo diga de forma natural.

Segundo problema: idempotencia. Las plataformas de voz reintentan los webhooks. Si tu handler no es idempotente, la misma llamada se registra dos veces y obtienes registros duplicados. Usa el ID de llamada como clave:

const key = report.call.id;
if (await store.has(key)) return res.sendStatus(200); // already processed
await store.add(key);
// ...do the CRM write

En producción, ese store es Redis o una fila en una base de datos con una restricción única sobre el ID de llamada, no un Set en memoria. El Set de arriba funciona para una demo; pierde la memoria cada vez que el servidor se reinicia.

Antes de las secciones por CRM, aquí está cómo difieren las tres plataformas en los aspectos que realmente importan para la voz:

Integración con HubSpot (Vapi → HubSpot, paso a paso)

Para una integración Vapi → HubSpot, mapeas la lectura en vivo a una búsqueda de Contacto y la escritura post-llamada a un engagement de llamada asociado a ese Contacto y su Trato. El modelo de objetos de HubSpot es Contacto, Trato y engagement (la Actividad), y el endpoint POST /crm/v3/objects/calls es tu destino de escritura. Este es el patrón de integración vapi hubspot que la mayoría busca.

La lectura en vivo es una function call a tu endpoint de búsqueda, que consulta GET /crm/v3/objects/contacts/search por número de teléfono y devuelve el Contacto y cualquier Trato abierto. La escritura post-llamada es el handler de la sección anterior: crea un engagement de llamada y lo asocia al Contacto mediante el tipo de asociación 194, luego hace un PATCH del dealstage del Trato.

El detalle que se suele perder: las asociaciones de HubSpot son tipadas. Una asociación de llamada a contacto usa un associationTypeId específico, y la llamada no aparecerá en la línea de tiempo del contacto si lo omites. La guía de la API de llamadas de HubSpot lista los IDs. Para la autenticación, un token de app privada es el camino más rápido para un solo workspace; usa OAuth si vas a desplegar esto en varias cuentas de HubSpot.

Integración con Salesforce (objetos, autenticación, lectura/escritura en tiempo real)

Una integración de agente de voz con Salesforce lee desde Contact o Lead durante la llamada y escribe un Task (el objeto Actividad) después. El trato vive en Opportunity. El patrón es idéntico al de HubSpot (lectura en vivo por function call, escritura post-llamada), pero los nombres de los objetos y el flujo de autenticación difieren. Usarás la REST API o la Composite API para la escritura.

Para la lectura en vivo, tu endpoint de búsqueda consulta Salesforce con una petición SOQL como SELECT Id, Name, Account.Name FROM Contact WHERE Phone = '...' y devuelve el resultado al agente. Para la escritura post-llamada, creas un Task con WhoId apuntando al Contact/Lead y WhatId apuntando a la Opportunity, según la guía de la REST API de Salesforce:

await fetch(
  `${INSTANCE_URL}/services/data/v60.0/sobjects/Task`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${sfToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      Subject: "AI Voice Agent Call",
      Description: report.summary,
      Status: "Completed",
      WhoId: contactId,      // Contact or Lead
      WhatId: opportunityId, // Opportunity
      CallDurationInSeconds: Math.round((report.durationMs ?? 0) / 1000),
    }),
  }
);

El problema específico de la voz: los tokens OAuth de Salesforce caducan, y no quieres que una renovación de token compita con tu presupuesto de 5 segundos de lectura en vivo. Renueva los tokens según un calendario en segundo plano, guarda el access token en caché y mantenlo caliente para que la búsqueda en vivo nunca pague el coste de la renovación durante una llamada.

Integración con Pipedrive (la que todos se saltan)

La integración con Pipedrive funciona a través de Persons, Deals y Activities, y tiene una trampa real: no hay webhook para cambios en campos personalizados. Si tu agente de voz escribe un campo personalizado y necesitas reaccionar a ese cambio en otro lugar, no puedes suscribirte. Pipedrive no te enviará un webhook cuando cambie un campo personalizado; tienes que hacer polling a dealFields según un calendario. Casi nadie cubre esto, que es exactamente por qué las integraciones de agente de voz con Pipedrive fallan de formas sutiles.

El ciclo de vida de la voz encaja limpiamente: la lectura en vivo consulta GET /persons/search por teléfono, la escritura post-llamada crea una Activity (POST /activities) vinculada a la Person y al Deal, y la cualificación mueve el Deal a la siguiente etapa. Nada fuera de lo común.

La trampa son los campos personalizados. En Pipedrive, los campos personalizados se referencian mediante una clave hash de 40 caracteres, no un nombre legible, así que tu configuración de mapeo tiene que almacenar algo como dcf558aba6... en vez de plan_tier. Y según la documentación de DealFields de Pipedrive, no hay evento de cambio para ellos. Si un sistema a continuación necesita saber cuándo el agente actualizó un campo personalizado, haces polling a GET /dealFields y comparas con tu último snapshot en un cron. No es elegante. Es simplemente como funciona Pipedrive, y enterarse a las 2 de la madrugada en producción es peor que leerlo aquí.

El traspaso de cualificación de leads: mover el trato e informar al representante humano

El traspaso es donde el agente de voz mueve la etapa del trato al cualificar, crea una tarea para el representante humano y pasa el transcript y el resumen para que el representante llegue ya sabiendo el contexto. Bien hecho, el humano recoge un lead cualificado y caliente con notas adjuntas, no un nombre frío y un número de teléfono.

Mecánicamente son tres escrituras, todas en el handler post-llamada: hacer PATCH del trato a la etapa cualificada, hacer POST de una Activity/Task asignada al representante con una fecha de vencimiento, y meter el resumen de la llamada en el cuerpo de la tarea. El representante abre su CRM, ve "cualificado por IA: quiere demo del Pro, presupuesto confirmado, prefiere el jueves", y llama de vuelta preparado.

Aquí también se nota la elección de plataforma. Si todavía estás decidiendo en qué motor construir, nuestra comparativa de qué plataforma gestiona mejor la integración con CRM analiza cómo Vapi, Retell y Bland exponen los metadatos de la llamada y los eventos de webhook, y esa diferencia define directamente lo limpio que puede ser tu traspaso.

Construirlo tú mismo frente a delegarlo (horas reales)

Construir una integración de agente de voz con CRM de calidad de producción supone aproximadamente entre 20 y 40 horas por CRM, y las horas no se van a donde esperarías. El happy path de lectura y escritura es cosa de un día. El resto va en gestión de tokens de autenticación, mapeo de campos, manejo de respaldos, idempotencia y pruebas contra los límites de tasa y las peculiaridades del CRM. ¿Cuánto tarda esto en realidad? Aquí está el desglose honesto.

En nuestros proyectos, el tiempo se reparte aproximadamente así: 3-5 horas en autenticación y renovación de tokens, 4-6 en mapeo de campos y la capa de formato adaptado al habla, 4-8 en manejo de respaldos y timeouts, 3-5 en idempotencia y deduplicación, y el resto en pruebas contra tráfico de llamadas real. El primer CRM es donde aprendes el patrón; el segundo y el tercero van más rápido, pero cada uno tiene su propia trampa, como el webhook de campo personalizado que falta en Pipedrive.

¿Construirlo o comprarlo? Si tienes un desarrollador que puede alojar un endpoint de webhook y estás integrando un CRM, constrúyelo. Este artículo es tu plano. Si necesitas tres CRMs, autenticación multi-tenant y alguien disponible cuando HubSpot te limite la tasa a las 9 de la mañana, el cálculo cambia. Analizamos esa decisión en detalle en nuestra guía de construir vs comprar, y el desglose de precios muestra cuánto añade el trabajo de integración a un proyecto.

Si prefieres no mantener nada de esto, nosotros lo hacemos por clientes. Techsy despliega agentes de voz en producción conectados a tu CRM: las lecturas por function call, las escrituras por webhook post-llamada, el manejo de respaldos, todo. Sin presión en ningún caso; el código de arriba es tuyo para ejecutar de todas formas.

Preguntas frecuentes

¿Cómo se integra un agente de voz con IA con un CRM?

Conectas el agente al CRM de dos formas: function calling para lecturas en vivo durante la llamada, y un webhook para la escritura post-llamada. El agente busca al interlocutor en vivo a través de tu endpoint, luego un webhook de fin de llamada dispara tu handler, que registra una Actividad y actualiza la etapa del trato en el CRM.

¿Puede un agente de voz obtener datos del CRM durante una llamada?

Sí. El agente usa function calling para llegar a tu endpoint de búsqueda, que consulta el CRM y devuelve los datos del contacto y del trato antes de la siguiente frase del agente. Configura un timeout de herramienta de 5 segundos y una frase de respaldo hablada, porque en una llamada en vivo compites contra la paciencia del interlocutor, no la del API.

¿Cómo se registran las llamadas de un agente de voz con IA en un CRM?

Recibes el webhook de fin de llamada de la plataforma, que lleva el transcript, el resumen, la disposición y la URL de grabación. Tu handler extrae esos datos, hace un POST de una Actividad o engagement de llamada al CRM asociado al contacto, y establece el estado del lead. No hay presión de latencia aquí, ya que el interlocutor ya ha colgado.

¿Cuál es la diferencia entre un webhook y el function calling para agentes de voz?

El function calling es una lectura en vivo durante la llamada: el agente le hace una pregunta al CRM a mitad de la conversación y usa la respuesta de inmediato. Un webhook es una escritura post-llamada: la plataforma envía el resultado de la llamada a tu servidor después de que termina. El function calling compite contra el reloj; los webhooks no.

¿Se integra Vapi con HubSpot, Salesforce y Pipedrive?

Vapi no incluye conectores nativos para los tres, pero se integra con cualquiera de ellos a través de sus herramientas de function call (lecturas en vivo) y webhooks de server URL (escrituras post-llamada). Apuntas esos a tu propio endpoint, que habla con HubSpot, Salesforce o Pipedrive a través de sus REST APIs. El patrón es idéntico en los tres CRMs.

¿Cómo se mapean los datos de la llamada a campos personalizados del CRM?

Mantén un objeto de configuración que mapee cada campo de datos de la llamada a un objeto y campo del CRM. Para HubSpot y Salesforce, los campos personalizados usan nombres internos legibles. Pipedrive referencia los campos personalizados mediante una clave hash de 40 caracteres, así que tu configuración almacena el hash, no un nombre amigable. Formatea los valores para que suenen bien antes de que el agente los lea en voz alta.

¿Puede un agente de voz actualizar mi CRM en tiempo real durante la llamada?

Puede leer en tiempo real, pero la mayoría de implementaciones en producción difieren las escrituras a después de la llamada. Las lecturas en vivo necesitan ser rápidas y son seguras. Las escrituras en vivo arriesgan latencia y actualizaciones parciales si la llamada se cae a mitad de la escritura. El patrón estándar es leer en vivo y escribir en el webhook de fin de llamada, lo que protege la experiencia del interlocutor.

¿Cómo se evita que un agente de voz cree registros duplicados en el CRM?

Usa una clave de idempotencia; el ID de llamada es perfecto. Antes de que tu handler escriba nada, comprueba si ya has procesado ese ID de llamada; si es así, devuelve 200 y omite el procesamiento. Almacena la clave en Redis o una base de datos con una restricción única, no en memoria, para que sobreviva los reinicios. Los webhooks reintentan, así que esto no es opcional.

¿Se integra Retell con Pipedrive?

Retell se integra con Pipedrive a través del mismo patrón de function call y webhook que cualquier CRM, incluso donde no aparece un conector nativo. Cablea los eventos de llamada de Retell a tu endpoint, que usa las APIs de Activities y Deals de Pipedrive. Ojo con la limitación de los campos personalizados: Pipedrive no tiene webhook para cambios en campos personalizados, así que haces polling a dealFields en su lugar.

¿Cuánto tiempo lleva construir una integración de agente de voz con CRM?

Aproximadamente entre 20 y 40 horas por CRM para una implementación de calidad de producción. El happy path es rápido; el tiempo se va en autenticación y renovación de tokens, mapeo de campos, manejo de respaldos y timeouts, idempotencia y pruebas contra tráfico de llamadas real. El primer CRM es el más lento porque es donde aprendes el patrón. Cada CRM adicional tiene sus propias peculiaridades.