Activar llamadas salientes de 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 ilustrarlo, usaremos el siguiente caso de uso: activar una llamada siete días antes de una cita de un cliente. El agente de IA confirmará la asistencia, responderá preguntas básicas sobre la cita y registrará cualquier preferencia de reprogramación o cancelación.

Cómo funciona

Independientemente del caso de uso, este es el núcleo de cómo se activa 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 el payload de contexto a AI Voice Agent → AI Voice Agent inicia la llamada saliente al registro

Esta base puede adaptarse a prácticamente cualquier caso de uso.

Centrados en nuestro caso de uso de recordatorio de citas, este es un flujo de llamada típico 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.
• Pregunta si sigue estando conforme con seguir adelante.
• Si SÍ: confirma cualquier detalle relevante (ubicación, con quién se reunirá) y finaliza la llamada.
• Si quiere REPROGRAMAR: el agente pregunta por la nueva fecha que prefiere y le informa de que alguien hará seguimiento para confirmarla.*
• Si quiere CANCELAR: el agente toma nota de ello e informa de 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:
HubSpot Acciones de API para meetingAvailability y bookMeeting llegarán pronto, lo que permitirá a los agentes reprogramar reuniones automáticamente sin intervención humana.

Suposiciones

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

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

Personalizar para tu caso de uso 

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 el mínimo necesario para activar una llamada. Todos los demás campos son opcionales; incluye solo lo que tu agente de IA realmente utilice durante la conversación.
• Campos opcionales: Puedes añadir o eliminar campos de contexto (p. ej., ubicación, representante asignado, tipo de cita) según la información que tu agente necesite para gestionar la llamada de forma eficaz.
• Plazo: este flujo de trabajo se basa en recordatorios 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 está pensada en torno a registros de Contactos de HubSpot, pero el mismo enfoque puede adaptarse para funcionar con otros objetos; simplemente cambia el tipo de registro y las propiedades asociadas en el activador del flujo de trabajo y en 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: Reúne 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. Tendrás que recuperar las siguientes credenciales del Aircall Dashboard: 

• ID de AI Voice Agent
• Token de Basic Auth 

Tendrás que pegarlas en el código del Paso 2, y ahorra tiempo tenerlas a mano antes de empezar a crear la configuración. 

Tu AI Voice Agent tiene una URL de Webhook única que funciona como identificador. Está disponible en el Aircall Dashboard para que la copies y la utilices en tu flujo de trabajo. 

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

Tu token de Basic Auth se utiliza para autenticar solicitudes de HubSpot a la API de Aircall, verificando que la llamada fue activada por tu flujo de trabajo. Se genera a partir de tu ID de API de Aircall y de tu token de API, que puedes encontrar en el Aircall Dashboard yendo a:

Integrations & API → Claves API. 

Una vez que tengas ambos valores, combínalos con el formato API_ID:API_TOKEN y codifica el resultado en Base64. Esa cadena codificada es tu token de Basic Auth.

Paso 2: Crea una acción de código personalizada en HubSpot

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

Configura el activador de inscripción

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

El activador basado en 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 enfoque más sencillo y aplicable de forma más universal 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 de contacto → [your appointment date property] → es conocida. 

De este modo, siempre que se establezca una fecha de cita en un contacto (independientemente de cómo haya llegado ahí), se inscribirá y el flujo de trabajo gestionará el resto cuando falten 7 días para la fecha de la cita almacenada en la propiedad.

Deja activada la reinscripción. Si un contacto reprograma y se actualiza la fecha de su cita, se volverá a inscribir y recibirá una llamada de recordatorio para la nueva fecha, que es el comportamiento previsto.

Haz clic en guardar y tu activador ya estará completo.

Añade una acción de código personalizada 

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 pasar a AI Voice Agent. La tabla siguiente muestra los campos recomendados, con qué se corresponden en el código y orientación sobre qué propiedad usar:

Añade o elimina filas según el contexto que necesite tu agente de IA. Incluye solo los campos a los que el agente vaya a hacer referencia realmente durante la llamada.

Pega el código

Sustituye el código predeterminado por el siguiente. 

Ten en cuenta lo siguiente: 

• Las filas event.inputFields del código deben corresponder a los campos de entrada que acabas de configurar arriba en «Propiedad que se incluirá en el código». Asegúrate de que también coincidan con las filas del payload de contexto más abajo en el código.
• Actualiza el marcador de posición basicAuth con tu token de Basic Auth 
• Actualiza el marcador de posición de la URL del agente con tu ID de agente/URL de Webhook

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: The agent will only use what is passed in the context payload. If a field is missing or blank, it will not reference it. Never pass a field with placeholder or test data in a live workflow.

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

Paso 3: Pruebas antes de la puesta en marcha

Antes de habilitar 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 usando la acción Probar en HubSpot.
• Escucha la llamada y verifica que el agente lea 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 estés conforme con el funcionamiento esperado, puedes activar el flujo de trabajo.

Consejo: Usa la vista del historial del flujo de trabajo de HubSpot para comprobar si cada acción de código se realizó correctamente o falló, y qué código de estado devolvió Aircall. Un estado 200 significa que la llamada se activó correctamente.