Ausgehende Anrufe mit dem AI Voice Agent über HubSpot auslösen

In diesem Leitfaden erfahren Sie, wie Sie einen HubSpot-Arbeitsablauf einrichten, der automatisch einen ausgehenden Anruf durch einen AI Voice Agent auslöst. Dazu verwenden wir den folgenden Anwendungsfall: Ein Anruf wird sieben Tage vor einem Kundentermin ausgelöst. Der AI Voice Agent bestätigt die Teilnahme, beantwortet grundlegende Fragen zum Termin und erfasst Wünsche zur Terminverschiebung oder Stornierung.

Funktionsweise

Unabhängig vom Anwendungsfall wird die Automatisierung im Wesentlichen folgendermaßen ausgelöst:

Datensatz erfüllt anhand eines HubSpot-Eigenschaftswerts die Aufnahmekriterien → wird in den Arbeitsablauf aufgenommen → Arbeitsablauf sendet Kontextdaten an den AI Voice Agent → AI Voice Agent startet ausgehenden Anruf an den Datensatz

Diese Grundlage lässt sich an praktisch jeden Anwendungsfall anpassen.

Für unseren Anwendungsfall einer Terminerinnerung sieht ein typischer Anrufablauf, nachdem der Datensatz den Arbeitsablauf durchlaufen und der Anruf ausgelöst wurde, folgendermaßen aus:

• Der Agent begrüßt den Kunden mit Namen und bestätigt Datum und Uhrzeit des Termins.
• Er fragt, ob der Termin weiterhin wahrgenommen werden soll.
• Falls JA: Er bestätigt alle relevanten Details (Ort, Gesprächspartner) und beendet den Anruf.
• Bei einer gewünschten TERMINVERSCHIEBUNG: Der Agent fragt nach dem bevorzugten neuen Datum und weist darauf hin, dass sich jemand zur Bestätigung melden wird.*
• Bei einer gewünschten STORNIERUNG: 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 AI Actions für meetingAvailability und bookMeeting sind demnächst verfügbar. Damit können Agenten Termine automatisch und ohne menschliches Eingreifen verschieben.

Voraussetzungen

Dieser Leitfaden setzt Folgendes voraus:

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

Anpassung an Ihren Anwendungsfall 

Beachten Sie vor Beginn Folgendes:

• Pflichtfelder: Die Rufnummer des Kontakts und das Termindatum sind die Mindestangaben, die zum Auslösen eines Anrufs erforderlich sind. Alle anderen Felder sind optional. Fügen Sie nur Angaben hinzu, die Ihr KI-Agent während des Gesprächs tatsächlich verwendet.
• Optionale Felder: Je nachdem, welche Informationen Ihr Agent zur effektiven Bearbeitung des Anrufs benötigt, können Sie Kontextfelder hinzufügen oder entfernen (z. B. Ort, zuständiger Mitarbeiter, Terminart).
• Zeitrahmen: Dieser Arbeitsablauf basiert auf Erinnerungen 7 Tage vor dem Termin. Sie können die Anzahl der Tage an Ihre betrieblichen Abläufe anpassen. 
• Andere Datensatztypen: Dieser Leitfaden basiert auf HubSpot-Kontaktdatensätzen. Derselbe Ansatz kann jedoch für andere Objekte angepasst werden. Tauschen Sie dazu einfach den Datensatztyp und die zugehörigen Eigenschaften im Arbeitsablaufauslöser und in der Codeaktion aus.
• Eigenschaftsnamen: Ersetzen Sie jeden Platzhalter wie [your_appointment_date_property] durch den tatsächlichen internen Namen der HubSpot-Eigenschaft, in der Sie diese Daten speichern.

Schritt 1: Zugangsdaten zusammenstellen

Sie arbeiten mit zwei Tools – HubSpot und Aircall. Stellen Sie daher vor Beginn sicher, dass Sie Zugriff auf beide haben und dort angemeldet sind. Sie benötigen die folgenden Zugangsdaten aus dem Aircall Dashboard: 

• AI Voice Agent-ID
• Basic-Auth-Token 

Sie müssen diese in Schritt 2 in den Code einfügen. Wenn Sie sie vor der Einrichtung bereithalten, sparen Sie Zeit. 

Ihr AI Voice Agent besitzt eine eindeutige Webhook-URL, die als Kennung dient. Sie können sie im Aircall Dashboard kopieren und in Ihrem Arbeitsablauf verwenden. 

Navigieren Sie zu AI Voice Agent → Arbeitsablauf für ausgehende Anrufe → Webhook-URL → Kopieren

Ihr Basic-Auth-Token dient zur Authentifizierung von Anfragen von HubSpot an die Aircall API. Damit wird bestätigt, dass der Anruf durch Ihren Arbeitsablauf ausgelöst wurde. Er wird anhand Ihrer Aircall API-ID und Ihres API-Tokens generiert. Sie finden diese im Aircall Dashboard unter Integrationen → API-Schlüssel. 

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

Schritt 2: Benutzerdefinierte Codeaktion in HubSpot erstellen

Navigieren Sie in HubSpot zu Automatisierung > Arbeitsabläufe und erstellen Sie einen neuen kontaktbasierten Arbeitsablauf. Geben Sie ihm einen aussagekräftigen Namen, beispielsweise Terminerinnerung — ausgehender Aircall-Anruf.

Aufnahmeauslö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. Er bewirkt jedoch nichts, wenn Kontakte nicht tatsächlich in den Arbeitsablauf aufgenommen werden. Der einfachste und allgemein anwendbare Ansatz besteht darin, Kontakte aufzunehmen, sobald ihr Termindatum bekannt ist – also wenn die Eigenschaft von leer zu einem vorhandenen Wert wechselt.

Fügen Sie dem Aufnahmeauslöser zum Einrichten eine Bedingung hinzu: 

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

Wenn für einen Kontakt ein Termindatum festgelegt wird, wird er auf diese Weise unabhängig von der Herkunft des Datums aufgenommen. Der Arbeitsablauf übernimmt den Rest, sobald das in der Eigenschaft gespeicherte Termindatum in 7 Tagen erreicht wird.

Lassen Sie die erneute Aufnahme 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. Dies entspricht dem beabsichtigten Verhalten.

Klicken Sie auf Speichern. Damit ist Ihr Auslöser vollständig eingerichtet.

Benutzerdefinierte Code-Aktion hinzufügen 

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

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, ihre Zuordnung im Code und Hinweise dazu, welche Eigenschaft verwendet werden sollte:

Fügen Sie je nach Kontext, den Ihr KI-Agent benötigt, Zeilen hinzu oder entfernen Sie sie. Nehmen Sie nur Felder auf, auf die der Agent während des Anrufs tatsächlich Bezug nimmt.

Code einfügen

Ersetzen Sie den Standardcode durch den folgenden Code. 

Beachten Sie: 

• Die event.inputFields-Zeilen im Code müssen den Eingabefeldern entsprechen, die Sie oben unter „In Code einzuschließende Eigenschaft“ konfiguriert haben. Stellen Sie sicher, dass sie auch mit den weiter unten im Code enthaltenen Zeilen der Kontext-Nutzlast übereinstimmen.
• Ersetzen Sie den Platzhalter basicAuth durch Ihr Basic-Auth-Token. 
• Ersetzen Sie den Platzhalter für die Agenten-URL durch Ihre Agenten-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: Der Agent verwendet ausschließlich die Angaben, die in der Kontext-Nutzlast übergeben werden. Wenn ein Feld fehlt oder leer ist, nimmt er darauf keinen Bezug. Übergeben Sie in einem aktiven Arbeitsablauf niemals ein Feld mit Platzhalter- oder Testdaten.

Die Konfiguration Ihres Arbeitsablaufs ist jetzt abgeschlossen.

Schritt 3: Tests vor der Inbetriebnahme

Führen Sie die folgenden Schritte aus, bevor Sie den Arbeitsablauf für alle Kontakte aktivieren:

• Nehmen Sie einen internen Testkontakt mit einer echten Mobilfunknummer und einem fiktiven Termindatum für morgen auf.
• Lösen Sie den Arbeitsablauf manuell über die Aktion Testen in HubSpot aus.
• Hören Sie sich den Anruf an und prüfen Sie, ob der Agent den richtigen Namen, das richtige Datum, die richtige Uhrzeit und alle weiteren von Ihnen aufgenommenen Felder vorliest.
• Testen Sie den Ablauf für die Terminverschiebung, indem Sie antworten, dass Sie das Datum ändern möchten.

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

Tipp: Prüfen Sie in der Verlaufsansicht des HubSpot-Arbeitsablaufs, ob die einzelnen Code-Aktionen erfolgreich waren oder fehlgeschlagen sind und welchen Statuscode Aircall zurückgegeben hat. Der Status 200 bedeutet, dass der Anruf erfolgreich ausgelöst wurde.