Auslösen ausgehender AI Voice Agent-Anrufe über HubSpot

Diese Anleitung zeigt, wie Sie einen HubSpot-Arbeitsablauf einrichten, der automatisch einen ausgehenden AI Voice Agent-Anruf auslöst. Zur Veranschaulichung verwenden wir folgenden Anwendungsfall: Auslösen eines Anrufs sieben Tage vor einem Kundentermin. Der AI-Agent bestätigt die Teilnahme, beantwortet grundlegende Fragen zum Termin und erfasst etwaige Wünsche zur Verschiebung oder Stornierung.

So funktioniert es

Unabhängig vom Anwendungsfall ist dies der Kern der Auslösung der Automatisierung:

Datensatz erfüllt die Einschreibungskriterien über den HubSpot-Eigenschaftswert → wird in den Arbeitsablauf aufgenommen → Arbeitsablauf sendet Kontext-Payload an den AI Voice Agent → AI Voice Agent startet ausgehenden Anruf an den Datensatz

Diese Grundlage kann an praktisch jeden Anwendungsfall angepasst werden.

Mit Fokus auf unseren Anwendungsfall für Terminerinnerungen folgt hier ein typischer Anrufablauf, nachdem der Datensatz den Arbeitsablauf durchlaufen hat und der Anruf ausgelöst wurde:

• Der Agent begrüßt den Kunden namentlich und bestätigt Datum und Uhrzeit des Termins.
• Er fragt, ob der Termin weiterhin wahrgenommen werden soll.
• Bei JA: Er bestätigt alle relevanten Details (Ort, Ansprechpartner) und beendet den Anruf.
• Wenn eine VERSCHIEBUNG gewünscht wird: Der Agent fragt nach dem bevorzugten neuen Datum und weist darauf hin, dass sich jemand zur Bestätigung melden wird.*
• Wenn eine STORNIERUNG gewünscht wird: Der Agent vermerkt dies und weist darauf hin, dass sich das Team melden wird.
• Wenn eine Frage gestellt wird, die der Agent nicht beantworten kann: Er teilt mit, dass ein Teammitglied zurückrufen wird.

* HINWEIS:
HubSpot API-Aktionen für meetingAvailability und bookMeeting kommen bald und ermöglichen es Agenten, Meetings automatisch ohne menschliches Eingreifen zu verschieben.

Annahmen

Diese Anleitung setzt voraus, dass Folgendes bereits vorhanden ist:

• Sie haben im Aircall Dashboard bereits einen ausgehenden AI Voice Agent erstellt, der für den Anwendungsfall Terminerinnerung konfiguriert ist.
• Sie haben eine HubSpot-Kontakteigenschaft, in der das Termindatum gespeichert wird.

An Ihren Anwendungsfall anpassen 

Berücksichtigen Sie vor dem Start Folgendes:

• Erforderliche Felder: Die Telefonnummer des Kontakts und das Termindatum sind das Minimum, das zum Auslösen eines Anrufs benötigt wird. Alle anderen Felder sind optional. Nehmen Sie nur das auf, was Ihr AI-Agent im Gespräch tatsächlich verwendet.
• Optionale Felder: Sie können Kontextfelder hinzufügen oder entfernen (z. B. Ort, zugewiesener Ansprechpartner, Terminart), je nachdem, welche Informationen Ihr Agent benötigt, um den Anruf effektiv zu bearbeiten.
• Zeitrahmen: Dieser Arbeitsablauf basiert auf Erinnerungen 7 Tage vorher. Sie können dies auf die Anzahl von Tagen anpassen, die zu Ihren Abläufen passt. 
• Andere Datensatztypen: Diese Anleitung basiert auf HubSpot-Kontaktdatensätzen, derselbe Ansatz kann aber auch für andere Objekte angepasst werden. Tauschen Sie dazu einfach den Datensatztyp und die zugehörigen Eigenschaften im Auslöser des Arbeitsablaufs und in der Code-Aktion aus.
• Eigenschaftsnamen: Ersetzen Sie jeden Platzhalter wie [your_appointment_date_property] durch den tatsächlichen internen Namen der HubSpot-Eigenschaft, die Sie zum Speichern dieser Daten verwenden.

Schritt 1: Zugangsdaten sammeln

Sie arbeiten mit zwei Tools - HubSpot und Aircall - daher sollten Sie vor dem Start sicherstellen, dass Sie auf beide zugreifen können und in beiden angemeldet sind. Sie müssen die folgenden Zugangsdaten aus dem Aircall Dashboard abrufen: 

• AI Voice Agent-ID
• Basic Auth-Token 

Diese müssen Sie in Schritt 2 in den Code einfügen. Es spart Zeit, sie vor dem Aufbau bereitzuhalten. 

Ihr AI Voice Agent hat eine eindeutige Webhook-URL, die als Kennung dient. Diese ist im Aircall Dashboard verfügbar, damit Sie sie kopieren und in Ihrem Arbeitsablauf verwenden können. 

Zu AI Voice Agent → Outbound call workflow → Webhook URL → Copy navigieren

Ihr Basic Auth-Token wird verwendet, um Anfragen von HubSpot an die Aircall API zu authentifizieren und zu verifizieren, dass der Anruf durch Ihren Arbeitsablauf ausgelöst wurde. Es wird aus Ihrer Aircall-API-ID und Ihrem API-Token erzeugt, die Sie im Aircall Dashboard hier finden:

Integrations & API → API-Schlüssel. 

Sobald Sie beide Werte haben, kombinieren Sie sie im Format API_ID:API_TOKEN und kodieren das Ergebnis in Base64. Diese kodierte Zeichenfolge ist Ihr Basic Auth-Token.

Schritt 2: Eine benutzerdefinierte Code-Aktion in HubSpot erstellen

In HubSpot zu Automatisierung > Workflows navigieren und einen neuen kontaktbasierten Workflow erstellen. Geben Sie ihm einen aussagekräftigen Namen wie Appointment Reminder — Aircall Outbound Call.

Den Einschreibungsauslöser festlegen

Verwenden Sie einen zeitplanbasierten Auslöser, der mit Ihrer Eigenschaft für das Termindatum verknüpft ist:

Der datumsbasierte Auslöser steuert, wann der Anruf ausgelöst wird, bewirkt aber nichts, wenn Kontakte nicht tatsächlich in den Arbeitsablauf aufgenommen werden. Der einfachste und universellste Ansatz ist, Kontakte aufzunehmen, wenn ihr Termindatum bekannt wird — also wenn sich die Eigenschaft von leer zu einem Wert ändert.

Fügen Sie dafür dem Einschreibungsauslöser eine Bedingung hinzu: 

Kontakteigenschaft → [your appointment date property] → ist bekannt. 

So werden Kontakte immer dann aufgenommen, wenn bei einem Kontakt ein Termindatum festgelegt wird (unabhängig davon, wie es dort eingetragen wurde), und der Arbeitsablauf übernimmt den Rest, wenn es 7 Tage vor dem in der Eigenschaft gespeicherten Termindatum ist.

Lassen Sie die erneute Einschreibung aktiviert. Wenn ein Kontakt seinen Termin verschiebt und das Termindatum aktualisiert wird, wird er erneut aufgenommen und erhält einen Erinnerungsanruf für das neue Datum. Dieses Verhalten ist beabsichtigt.

Auf Speichern klicken, damit ist Ihr Auslöser vollständig eingerichtet.

Eine benutzerdefinierte Code-Aktion hinzufügen 

Fügen Sie im Workflow eine Aktion hinzu und wählen Sie Benutzerdefinierter Code. Wählen Sie Node.js 18.x als Sprache.

Fügen Sie unter „In Code einzuschließende Eigenschaft“ die HubSpot-Eigenschaften hinzu, die Sie an den AI Voice Agent übergeben möchten. Die folgende Tabelle zeigt die empfohlenen Felder, wie sie im Code zugeordnet werden, und Hinweise dazu, welche Eigenschaft verwendet werden sollte:

Fügen Sie je nach Kontextbedarf Ihres AI-Agenten Zeilen hinzu oder entfernen Sie diese. Nehmen Sie nur Felder auf, auf die der Agent im Anruf tatsächlich Bezug nimmt.

Den Code einfügen

Ersetzen Sie den Standardcode durch den folgenden. 

Hinweis: 

• Die Zeilen event.inputFields im Code müssen den Eingabefeldern entsprechen, die Sie oben unter „In Code einzuschließende Eigenschaft“ konfiguriert haben. Achten Sie darauf, dass sie auch mit den Zeilen der Kontext-Payload weiter unten im Code übereinstimmen.
• Ersetzen Sie den Platzhalter basicAuth durch Ihr Basic Auth-Token 
• Ersetzen Sie den Platzhalter agent URL durch Ihre Agent-ID/Webhook-URL

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}` } });
  }
};

Achtung: 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.

Ihre Workflow-Konfiguration ist jetzt vollständig.

Schritt 3: Testen vor dem Go-Live

Vor dem Aktivieren des Workflows für alle Kontakte gehen Sie wie folgt vor:

• Einen internen Testkontakt mit einer echten Mobilnummer und einem fiktiven Termindatum für morgen aufnehmen.
• Den Workflow manuell mit der Aktion Test in HubSpot auslösen.
• Den Anruf anhören und prüfen, ob der Agent den richtigen Namen, das richtige Datum, die richtige Uhrzeit und alle weiteren aufgenommenen Felder korrekt wiedergibt.
• Den Pfad für die Terminverschiebung testen, indem Sie antworten, dass Sie das Datum ändern möchten.

Wenn alles wie erwartet funktioniert, können Sie den Workflow aktivieren.

Tipp: Verwenden Sie die Workflow-Verlaufsansicht von HubSpot, um zu prüfen, ob jede Code-Aktion erfolgreich war oder fehlgeschlagen ist und welchen Statuscode Aircall zurückgegeben hat. Ein Status 200 bedeutet, dass der Anruf erfolgreich ausgelöst wurde.