Activación de llamadas salientes del AI Voice Agent a través de HubSpot

Esta guía te explica cómo configurar un flujo de trabajo de HubSpot que active automáticamente una llamada saliente de AI Voice Agent. Para mostrar cómo funciona, usaremos el siguiente caso práctico: activar una llamada siete días antes de la cita de un cliente. El agente de IA confirmará la asistencia, responderá preguntas básicas sobre la cita y registrará cualquier preferencia de cambio de fecha o cancelación.

Cómo funciona

Independientemente del caso práctico, este es el proceso básico para activar la automatización:

El registro cumple los criterios de inscripción mediante el valor de una propiedad de HubSpot → se inscribe en el flujo de trabajo → el flujo de trabajo envía la carga útil de contexto a AI Voice Agent → AI Voice Agent inicia una llamada saliente al registro

Esta base puede adaptarse prácticamente a cualquier caso práctico.

Centrándonos en nuestro caso práctico de recordatorio de citas, este es un flujo de llamadas habitual una vez que el registro ha pasado por el flujo de trabajo y se ha activado la llamada:

• El agente saluda al cliente por su nombre y confirma la fecha y la hora de su cita.
• Le pregunta si aún desea seguir adelante.
• Si responde SÍ: confirma cualquier dato relevante (ubicación, con quién se reunirá) y finaliza la llamada.
• Si desea CAMBIAR LA FECHA: el agente le pregunta qué nueva fecha prefiere y le indica que alguien se pondrá en contacto para confirmarla.*
• Si desea CANCELAR: el agente toma nota y le indica que el equipo se pondrá en contacto.
• Si hace una pregunta que el agente no puede responder: le indica que un miembro del equipo le devolverá la llamada.

* NOTA:
Las acciones de IA de HubSpot para meetingAvailability y bookMeeting estarán disponibles próximamente, lo que permitirá a los agentes cambiar automáticamente la fecha de las reuniones sin intervención humana.

Requisitos previos

Esta guía presupone que ya cuentas con lo siguiente:

• Has creado un AI Voice Agent saliente configurado para el caso práctico de recordatorio de citas en el Panel de control de Aircall.
• Tienes una propiedad de contacto de HubSpot que almacena la fecha de la cita.

Personalización para tu caso práctico 

Antes de empezar, ten en cuenta lo siguiente:

• Campos obligatorios: El número de teléfono del contacto y la fecha de la cita son los datos mínimos necesarios para activar una llamada. Todos los demás campos son opcionales; incluye únicamente los que tu agente de IA utilice realmente durante la conversación.
• Campos opcionales: Puedes añadir o eliminar campos de contexto (por ejemplo, ubicación, representante asignado o tipo de cita) en función de la información que tu agente necesite para gestionar la llamada de forma eficaz.
• Plazo: este flujo de trabajo se basa en recordatorios enviados con 7 días de antelación. Puedes ajustarlo al número de días que mejor se adapte a tus operaciones. 
• Otros tipos de registros: Esta guía se basa en registros de contactos de HubSpot, pero el mismo enfoque puede adaptarse para funcionar con otros objetos. Solo tienes que sustituir el tipo de registro y las propiedades asociadas en el activador del flujo de trabajo y la acción de código.
• Nombres de propiedades: Sustituye cada marcador de posición, como [your_appointment_date_property], por el nombre interno real de la propiedad de HubSpot que utilizas para almacenar esos datos.

Paso 1: recopila tus credenciales

Vas a trabajar con dos herramientas —HubSpot y Aircall—, así que, antes de empezar, asegúrate de tener acceso a ambas y de haber iniciado sesión. Deberás obtener las siguientes credenciales del Panel de control de Aircall: 

• ID de AI Voice Agent
• Token de autenticación básica 

Deberás pegar estos datos en el código del paso 2. Tenerlos a mano antes de empezar a crear el flujo te ahorrará tiempo. 

Tu AI Voice Agent tiene una URL de Webhook única que funciona como identificador. Puedes copiarla del Panel de control de Aircall y usarla en tu flujo de trabajo. 

Ve a AI Voice Agent → Flujo de trabajo de llamadas salientes → URL de Webhook → Copiar

Tu token de autenticación básica se utiliza para autenticar las solicitudes de HubSpot a la API de Aircall y verificar que la llamada se haya activado mediante tu flujo de trabajo. Se genera a partir de tu ID de API y tu token de API, que puedes encontrar en el Panel de control de Aircall accediendo a Integraciones → Claves API. 

Cuando tengas ambos valores, combínalos con el formato API_ID:API_TOKEN y codifica el resultado en Base64. Esta cadena codificada es tu token de autenticación básica.

Paso 2: crea una acción de código personalizado en HubSpot

En HubSpot, ve a Automatización > Flujos de trabajo y crea un nuevo flujo de trabajo basado en contactos. Asígnale un nombre descriptivo, como Recordatorio de cita — Llamada saliente de Aircall.

Configura el activador de inscripción

Utiliza un activador basado en una programación y vinculado a la propiedad de fecha de la cita:

El activador basado en la fecha controla cuándo se realiza la llamada, pero no hará nada a menos que los contactos estén realmente inscritos en el flujo de trabajo. El método más sencillo y aplicable de forma general es inscribir a los contactos cuando se conozca la fecha de su cita, es decir, cuando la propiedad pase de estar vacía a tener un valor.

Para configurarlo, añade una condición al activador de inscripción: 

Propiedad del contacto → [tu propiedad de fecha de cita] → es conocida. 

De este modo, cuando se establezca la fecha de una cita para un contacto (independientemente de cómo se haya añadido), este se inscribirá y el flujo de trabajo se encargará del resto cuando falten 7 días para la fecha de la cita almacenada en la propiedad.

Mantén activada la reinscripción. Si un contacto cambia la fecha de su cita y esta se actualiza, volverá a inscribirse y recibirá una llamada de recordatorio para la nueva fecha, que es el comportamiento previsto.

Haz clic en Guardar. El activador ya está completo.

Añadir una acción de código personalizado 

Dentro del flujo de trabajo, añade una acción y selecciona Código personalizado. Elige Node.js 18.x como lenguaje.

En «Propiedad que se incluirá en el código», añade las propiedades de HubSpot que quieras transferir al AI Voice Agent. La siguiente tabla muestra los campos recomendados, con qué se corresponden en el código y qué propiedad debes usar:

Añade o elimina filas según el contexto que necesite tu agente de IA. Incluye únicamente los campos a los que el agente hará referencia durante la llamada.

Pegar el código

Sustituye el código predeterminado por el siguiente. 

Ten en cuenta lo siguiente: 

• Las filas event.inputFields del código deben corresponderse con los campos de entrada que acabas de configurar en «Propiedad que se incluirá en el código». Asegúrate de que también coincidan con las filas de la carga útil de contexto que aparecen más adelante en el código.
• Actualiza el marcador de posición basicAuth con tu token de autenticación básica. 
• Actualiza la URL de agente del marcador de posición con el ID o la URL de Webhook de tu agente.

const axios = require('axios');

exports.main = async (event, callback) => {
  const firstname       = event.inputFields['firstname'];
  const lastname        = event.inputFields['lastname'];
  const phone           = event.inputFields['phone'];
  const appt_date       = event.inputFields['appointment_date'];
  const appt_time       = event.inputFields['appointment_time'];
  const appt_address    = event.inputFields['appointment_address'];
  const legal_rep       = event.inputFields['legal_representative'];
  
  const basicAuth = 'YOUR_AIRCALL_BASIC_AUTH_TOKEN';
  const agentUrl  = 'https://api.aircall.io/v1/outbound-calls/agents/YOUR_AGENT_ID';
  try {
    const response = await axios.post(
      agentUrl,
      {
        contact_phone: phone,
        idempotency_key: `appt-reminder-${event.object.objectId}`,
        context: {
          first_name:           firstname,
          last_name:            lastname,
          appointment_date:     appt_date,
          appointment_time:     appt_time,
          appointment_address:  appt_address,
          legal_representative: legal_rep
        },
        expiration_seconds: 3600
      },
      {
        headers: {
          Authorization: `Basic ${basicAuth}`,
          'Content-Type': 'application/json'
        }
      }
    );
    callback({ outputFields: { status: response.status, message: 'Call triggered' } });
  } catch (error) {
    const status = error.response?.status || 500;
    const body   = JSON.stringify(error.response?.data) || 'No response';
    callback({ outputFields: { status, message: `${error.message} | ${body}` } });
  }
};

Importante: El agente solo utilizará la información transferida en la carga útil de contexto. Si falta un campo o está vacío, no hará referencia a él. Nunca transfieras un campo con datos de prueba o de marcador de posición en un flujo de trabajo activo.

La configuración de tu flujo de trabajo ya está completa.

Paso 3: Pruebas antes de la puesta en marcha

Antes de activar el flujo de trabajo para todos los contactos, sigue estos pasos:

• Inscribe un contacto de prueba interno con un número de móvil real y una fecha de cita ficticia establecida para mañana.
• Activa manualmente el flujo de trabajo mediante la acción Probar de HubSpot.
• Escucha la llamada y comprueba que el agente lee correctamente el nombre, la fecha, la hora y cualquier otro campo que hayas incluido.
• Prueba la ruta de reprogramación respondiendo que quieres cambiar la fecha.

Cuando tengas la certeza de que funciona según lo previsto, puedes activar el flujo de trabajo.

Consejo: Utiliza la vista del historial del flujo de trabajo de HubSpot para comprobar si cada acción de código se ha completado correctamente o ha fallado, y qué código de estado ha devuelto Aircall. Un estado 200 indica que la llamada se ha activado correctamente.