Smart-Telefonassistent: API-Integrationen einrichten

Mit API-Integrationen können Sie Ihren Smart-Telefonassistenten direkt mit externen Systemen verbinden – zum Beispiel mit CRM, Helpdesk, Kalendern oder eigenen Fachanwendungen. So kann der Assistent während eines laufenden Gesprächs Daten abfragen (z. B. Kundendaten, Ticketstatus) oder Aktionen ausführen (z. B. Ticket erstellen, Lead anlegen).

Was sind API-Integrationen beim Smart-Telefonassistenten?

Die API-Funktionalität ermöglicht es dem Smart-Telefonassistenten, während eines Anrufs mit externen Systemen über REST-Schnittstellen zu kommunizieren.

Der Assistent kann zum Beispiel:

• Kundendaten aus einem CRM abrufen (z. B. Salesforce, HubSpot, Pipedrive)
• Tickets in einem Helpdesk-System anlegen oder deren Status prüfen (z. B. Zendesk, Freshdesk)
• Termine oder Ressourcen in Kalender-Tools verwalten (z. B. Google Calendar, Outlook, Cal.com)
• Leads in Marketing- oder Newsletter-Systemen erstellen (z. B. HubSpot, Mailchimp)

Der KI-Assistent wird damit von einem reinen „Auskunftsbot“ zu einem aktiven Prozess-Baustein in Ihren Geschäftsabläufen.

Typische Einsatzszenarien und Beispiele

Die folgende Tabelle zeigt gängige Anwendungsfälle und den Nutzen der API-Integration im Alltag:

Voraussetzungen und technische Anforderungen

Damit Sie API-Integrationen nutzen können, sollten folgende Punkte erfüllt sein:

• Tarif / Produkt
  Ihr Vertrag enthält den Smart-Telefonassistenten inklusive API-Funktionalität.

• Zugriff auf Zielsystem(e)

  • Aktives Konto im Zielsystem (z. B. CRM, Ticket-Tool, Kalender).
  • Berechtigungen zum Erzeugen und Nutzen von API-Keys oder Tokens.

• Technische Grundlagen

  • Verständnis von REST-APIs und HTTP-Methoden (GET, POST, PUT, DELETE).
  • Grundkenntnisse in JSON (Request-Body, Responses).
  • Kenntnisse zu Authentifizierungsverfahren (API-Key, Bearer-Token, Basic Auth).

• Erreichbarer API-Endpunkt

  • Das Zielsystem stellt eine öffentliche REST-API bereit.
  • Die Endpunkte sind von außen erreichbar (keine reinen Intranet-APIs ohne Tunnel/VPN).

Technische Funktionsweise im Überblick

Der Smart-Telefonassistent fungiert bei API-Integrationen als HTTP-Client:

1. Der Assistent führt ein Gespräch mit dem Anrufer und sammelt benötigte Informationen (z. B. Kundennummer, E-Mail, Ticket-ID).
2. Diese Informationen werden gegen ein zuvor definiertes JSON Schema („Parameters“) geprüft und strukturiert.
3. Anschließend wird ein HTTP-Request gemäß einer HAR-Definition („Request Definition“) im JSON-Format aufgebaut.
4. Der Assistent sendet die Anfrage an die externe API, wartet auf die Antwort und nutzt das Ergebnis, um im Gespräch weiter zu agieren (z. B. „Ich habe Ihr Ticket gefunden, der Status ist …“).

Zentrale Bestandteile der Konfiguration:

• Tool Name & Beschreibung

  • Der Tool Name identifiziert die Integration.
  • In der Beschreibung geben Sie an, in welchen Situationen das Tool genutzt werden soll (z. B. „nutze dieses Tool, wenn der Anrufer nach einem Ticket-Status fragt“).

• Parameters (JSON Schema)

  • Definiert, welche Eingabewerte der Assistent vom Anrufer erfragen muss (z. B. customerId, date, ticketId).
  • Stellt sicher, dass nur vollständige und valide Daten an die API gesendet werden.

• Request Definition (HAR JSON)

  • Enthält die URL, HTTP-Methode, Header (inkl. Authentifizierung) und Body.
  • Platzhalter für die vom Assistenten abgefragten Parameter werden hier injiziert.

API-Tool hinzufügen

1. Melden Sie sich im Kunden-Login an und öffnen Sie den Smart-Telefonassistenten.
2. Navigieren Sie zum Bereich API-Integrationen.
3. Klicken Sie auf + Integration hinzufügen.
4. Vergeben Sie einen Tool-Namen (z. B. „CRM Kundendaten“ oder „Ticket-Erstellung Helpdesk“).
5. Wählen Sie aus, ob Sie:
   • die Definition mithilfe eines externen KI-Tools erstellen (Option A), oder
   • die Definition manuell im Expertenmodus anlegen (Option B).

Option A: LLM-gestützte Einrichtung

In dieser Option unterstützt Sie ein externes KI-Tool (LLM) beim Erzeugen des HAR-JSON für die Request-Definition. 

Um Zeit bei der Erstellung der HAR-Syntax zu sparen, können Sie den bereitgestellten Prompt nutzen, um den Code mit einem externen Large Language Model (LLM) wie ChatGPT oder Claude generieren zu lassen.

Schritt 1: Prompt für externes LLM kopieren

1. Öffnen Sie im Bereich API-Integrationen das neu angelegte Tool.
2. Klicken Sie auf Prompt für externes LLM kopieren.
3. Der Assistent stellt Ihnen einen vordefinierten Prompt bereit, der erklärt, welche API Sie ansprechen möchten (URL, Endpunkt, Methode etc.).

Schritt 2: HAR-JSON mit externer KI erzeugen

1. Öffnen Sie ein externes KI-Tool Ihrer Wahl (z. B. ein generatives KI-System).
2. Fügen Sie den kopierten Prompt ein.
3. Ergänzen Sie im Dialog mit der KI alle notwendigen Details zur Ziel-API (Endpunkte, Parameter, Authentifizierung).
4. Lassen Sie sich vom Tool ein HAR-Objekt im JSON-Format erzeugen, das den gewünschten HTTP-Request beschreibt.

Schritt 3: HAR-Definition einfügen

1. Kopieren Sie den vom externen KI-Tool erzeugten JSON-Block.
2. Wechseln Sie zurück in den Bereich API-Integrationen beim Smart-Telefonassistenten.
3. Fügen Sie den JSON-Block in das Feld Request Definition (HAR) ein.
4. Ersetzen Sie ggf. Platzhalter für API-Keys / Tokens durch die echten Werte direkt im HAR-JSON (z. B. im Header Authorization: Bearer <Ihr Token>).
5. Klicken Sie auf Übernehmen und danach oben auf Änderungen speichern.

Option B: Experten-Modus (manuelle Definition)

Diese Option richtet sich an Entwickler, die den benötigten Code bereits vorliegen haben oder manuell definieren möchten.

1. Klicken Sie oben rechts im Pop-up-Fenster auf Experten-Modus. Ein weiteres Pop-up-Fenster öffnet sich.
2. Füllen Sie die erforderlichen Felder aus:
   • Name: Kurz, eindeutig, z. B. crm_customer_lookup, ticket_create, calendar_create_event.
   • Beschreibung: Beschreiben Sie, wann dieses Tool verwendet werden soll, z. B.:
     „Nutze dieses Tool, wenn der Anrufer nach dem Status seines Tickets fragt und eine Ticket-ID angibt.“
   • Parameter: Legen Sie dort fest, welche Variablen der Assistent vor dem Request abfragen und validieren soll. Eingabe im JSON-Format. Achten Sie auf: korrekte Datentypen (string, number, boolean …), sinnvolle Pflichtfelder (required), ggf. weitere Einschränkungen (z. B. Pattern für IDs)
   • Anfrage: Im Feld Request Definition (HAR) ein vollständiges HAR-Objekt für den API-Call im JSON-Format einfügen und für Werte aus dem Gespräch Platzhalter wie {{ variableName }} verwenden.
3. Klicken Sie auf Übernehmen und anschließend oben auf Änderungen speichern.

Diese Beschreibung hilft dem übergeordneten KI-Modell, das richtige Tool zum richtigen Zeitpunkt einzusetzen.

Integration testen und Fehler beheben

Nach der Konfiguration sollten Sie jede API-Integration gründlich testen:

1. Testanruf durchführen

   • Simulieren Sie typische Gesprächsszenarien, in denen das Tool ausgelöst werden soll (z. B. „Ich möchte den Status meines Tickets mit der ID 12345 wissen“).

2. Antworten prüfen

   • Gibt der Assistent sinnvolle, konsistente Antworten auf Basis der API-Rückmeldung?
   • Werden Fehler (z. B. „Ticket nicht gefunden“, „Kundennummer ungültig“) korrekt und freundlich kommuniziert?

3. Logs / Monitoring nutzen

   • Nutzen Sie, soweit vorhanden, Log- oder Monitoring-Funktionen in Ihrem Zielsystem (CRM, Helpdesk etc.), um zu prüfen, ob Anfragen ankommen und verarbeitet werden.
   • Bei Fehlern: Statuscodes (4xx/5xx), Fehlermeldungen und Request-Payload auswerten.

Typische Fehlerquellen:

• Falsche oder abgelaufene API-Keys / Tokens
• Tippfehler in URLs oder Endpunkten
• Unstimmige Feldnamen zwischen HAR-Definition und JSON Schema
• Fehlende Pflichtparameter oder falsche Datentypen

Sicherheit und Umgang mit API-Schlüsseln

API-Keys und Tokens sind sensible Zugangsdaten, mit denen Dritte auf Ihre Systeme zugreifen könnten.

Beachten Sie daher zwingend:

• Geheime Daten nie in externe KI-Tools oder öffentliche Foren einfügen.
• API-Schlüssel nur in den dafür vorgesehenen Feldern oder direkt in der HAR-Definition des Smart-Telefonassistenten hinterlegen.
• API-Keys regelmäßig rotieren und nicht länger nutzen als nötig.
• Zugriffsrechte im Zielsystem auf das notwendige Minimum beschränken (Least Privilege).
• HTTPS (TLS) für alle Aufrufe nutzen, damit Daten verschlüsselt übertragen werden.

Best Practices für stabile API-Integrationen

• Klein anfangen, gezielt erweitern
  Starten Sie mit einem klar abgegrenzten Anwendungsfall (z. B. Ticket erstellen) und erweitern Sie später um weitere Funktionen (Ticketstatus, Kundendaten, Terminbuchung).

• Fehlerfälle bewusst gestalten
  Definieren Sie, wie der Assistent auf häufige Fehler reagieren soll (z. B. „Ticket nicht gefunden“, „Verbindungsfehler“, „Zeitüberschreitung“).

• Grenzen der API berücksichtigen
  Prüfen Sie Rate Limits, Quotas und erlaubte Aufrufmengen Ihres Zielsystems, um Sperren zu vermeiden.

• Datenqualität sichern
  Validieren Sie Eingaben über das JSON Schema und bitten Sie Anrufer ggf. um Bestätigung („Habe ich Ihre Kundennummer richtig verstanden?“), bevor ein Request abgesetzt wird.

• Regelmäßige Reviews
  Überprüfen Sie Ihre Integrationen regelmäßig:

  • Sind Endpunkte oder Authentifizierungsverfahren im Zielsystem geändert worden?
  • Müssen neue Felder oder Prozesse berücksichtigt werden?

• DSGVO & Datenschutz beachten
  Prüfen Sie, ob die Weitergabe von Gesprächsdaten an externe Systeme datenschutzrechtlich abgedeckt ist (AVV, Datenschutzerklärung, Löschkonzepte).

Weiterführende Artikel

• Original-Rufnummer bei Anrufweiterleitung übermitteln – Technische Hinweise zur Rufumleitung
• Wichtige Ergänzung für Ihre Datenschutzerklärung – Mustertexte und rechtliche Hinweise
• Smart-Telefonassistent mit Einrichtungsassistent einrichten – Grundkonfiguration, Testanruf und Aktivierung
• Stimme, Verhalten und Unternehmenswissen einstellen – Personalisierung und Wissensbasis
• Anliegen, Weiterleitungen & Kontakte konfigurieren – Gesprächslogik und Routing
• Terminbuchung einrichten (Cal.com & Calendly) – Automatische Terminvereinbarung