Integrationen hinzufügen/bearbeiten

Auf der Seite API-Integrationen können Sie neue Integrationen konfigurieren oder bestehende ändern. Integrationen verbinden Ihren KI-Agenten mit externen Diensten und Datenquellen, indem sie während der Konversationen definierte Endpunkte aufrufen.

Note

Die Seite API-Integrationen dient ausschließlich dem Verwalten, Testen und Protokollieren Ihrer Integrationen. Um eine Integration in einem Dialog zu nutzen, müssen Sie ein Integrationsmodul verwenden und es mit Ihrem Dialogfluss verbinden. Siehe 2️⃣ Integrationen verwenden

1. Manuell hinzufügen

Um eine neue Integration manuell hinzuzufügen, klicken Sie auf die Schaltfläche ➕ Hinzufügen in der linken unteren Ecke:

Ein Formular mit vier Registerkarten wird angezeigt:

Registerkarte Einstellungen

Auf der Registerkarte Einstellungen konfigurieren Sie das Kernverhalten Ihrer API-Integration – einschließlich der Anfragemethode, der Endpunkt-URL, der Header und optionaler JavaScript-Hooks für die Vor- und Nachverarbeitung.

Felder und Optionen

• Name & Beschreibung
  Dienen der Identifizierung der Integration in Ihrer Liste. Haben keinen Einfluss auf das Verhalten.
• Methode
  Wählen Sie die HTTP-Methode: GET, POST, PUT, PATCH oder DELETE.
• URL
  Die Endpunkt-URL, die Ihr Agent aufrufen wird.

💡

Sie können $context-Variablen (Bot-Speicher) direkt in der URL verwenden. Wenn ein Kunde beispielsweise eine Bestellnummer angibt, können Sie darauf so verweisen: https://api.yourdomain.com/orders/$user_order

(Vorausgesetzt, $user_order wurde zuvor im Dialogfluss des KI-Agenten erfasst.)

• Timeout
  Wie lange (in Millisekunden) der Agent auf eine Antwort warten soll, bevor der Aufruf fehlschlägt und der Dialogfluss ohne Ergebnis fortgesetzt wird. Wir empfehlen immer, diesen Fallback im Dialogfluss für den Fehlerfall zu konfigurieren – Sie können den Dialog etwa an einen Operator weiterleiten usw.

Note

Voicebots erfordern schnelle Antworten. Vermeiden Sie langsame APIs oder verwenden Sie stattdessen asynchrone Aufrufe (siehe die Seite Integrationen verwenden für weitere Details). Bei einem Chatbot spielt eine Verzögerung von ein bis zwei Sekunden keine Rolle.

• Header
  Fügen Sie alle benutzerdefinierten Header hinzu, die von der API benötigt werden (z. B. Authorization, Content-Type). Sie können $context-Variablen verwenden, genau wie im Feld URL.

• Vorverarbeitung (JavaScript)

Dieser optionale Abschnitt ermöglicht es Ihnen, Kontextwerte zu manipulieren, bevor die Anfrage gesendet wird.
Sie haben über das context-Objekt (context.$my_variable) vollen Zugriff auf den aktuellen Kontext und können ein Objekt zurückgeben, um Werte hinzuzufügen oder zu aktualisieren.

Anwendungsbeispiele:

• Benutzereingaben zusammenführen oder bereinigen, bevor sie in einer Anfrage verwendet werden
• Datumsangaben oder IDs formatieren

• Anfrage-Payloads oder Header dynamisch aufbauen usw.

• Nachverarbeitung (JavaScript)

Wird ausgeführt, nachdem die API-Antwort empfangen und den $context-Variablen zugeordnet wurde (in der Registerkarte Zuordnung). Sie können auf beide über das context-Objekt (context.$mapped_variable) zugreifen.

Verwenden Sie dies, um:

• Abgeleitete Variablen zu erstellen
• Werte in Formate zu konvertieren, die Ihr Bot benötigt
• Einfache Geschäftslogik auszuführen

Info

Sowohl der Vorverarbeitungs- als auch der Nachverarbeitungsblock verwenden JavaScript und laufen in derselben Umgebung wie Lambda-Module in Dialogen. Weitere Informationen finden Sie in der Dokumentation zum Lambda-Modul.

---

Registerkarte Test

Die Registerkarte Test ermöglicht es Ihnen, eine echte Anfrage an Ihren konfigurierten Endpunkt zu simulieren, sodass Sie überprüfen können, ob alles korrekt funktioniert, bevor Sie die Integration bereitstellen oder in einem Live-Dialogfluss verwenden.

Das ist besonders nützlich für:

• Das Debuggen der Anfrageformatierung
• Das Validieren der Struktur der Antwortdaten
• Das Prüfen, ob sich Ihre Vorverarbeitung, Header oder zugeordneten Kontextwerte wie erwartet verhalten

Testdaten bereitstellen

Die meisten API-Anfragen beruhen auf $context-Werten wie einer Bestellnummer, E-Mail-Adresse oder Kunden-ID. Um eine gültige Testanfrage zu senden, müssen Sie diese Werte zuerst bereitstellen.

Sie können dies auf zwei Arten tun:

• Manuelle Eingabe (2)

Fügen Sie $context-Variablen einzeln zusammen mit Beispielwerten hinzu.

• Aus einer bestehenden Diskussion laden (1)

Geben Sie die Diskussions-ID eines bestehenden Chats, Anrufs oder E-Mail-Threads an (zu finden in den Administrationsansichten Chat / Anrufe / E-Mails oder am Ende der URL einer ausgewählten Diskussion).

• Das System lädt automatisch alle Kontextwerte aus dieser Diskussion.
• Ideal zum Debuggen und Nachstellen des Live-Verhaltens des Agenten.

Sobald Ihr Kontext geladen ist, klicken Sie auf die Schaltfläche Anfrage senden, um die Anfrage zu senden. Sie sehen dann:

• (1) Ihre zugeordneten Kontextwerte (falls in der Registerkarte Zuordnung konfiguriert)
• (2) Den Anfrage-Payload
• (3) Die rohe API-Antwort

---

Registerkarte Zuordnung

Die Registerkarte Zuordnung ermöglicht es Ihnen zu wählen, welche Werte der API-Antwort in $context-Variablen gespeichert werden sollen, damit Ihr Agent sie in Antworten oder Bedingungen verwenden kann.

In der Regel benötigen Sie nicht die vollständige API-Antwort. Sie möchten nur bestimmte Daten wie Bestellstatus, Lieferzeit oder Kundenname, um Ihren Bot intelligenter und dynamischer zu machen.

Note

Bevor Sie etwas zuordnen können, müssen Sie in der Registerkarte Test eine Testanfrage senden. Sobald eine Antwort empfangen wurde, erscheint sie in der Registerkarte Zuordnung, und Sie können auswählen, welche Felder zugeordnet werden sollen.

Zugeordnete Werte:

• Werden in $context (dem Speicher Ihres KI-Agenten) gespeichert
• Können in Bot-Antworten verwendet werden
• Können in Bedingungen verwendet werden (z. B. das Stornieren einer Bestellung nur zulassen, wenn ihr Status „In Bearbeitung“ ist)
• Können mit Nachverarbeitungs-Logik oder einem Lambda-Modul weiter bearbeitet werden

So richten Sie die Zuordnung ein

Zuordnung nach Statuscode (1)

Sie können abhängig vom HTTP-Antwortstatus (z. B. 200, 404) unterschiedliche Zuordnungen definieren.
Wenn Sie diese Detailtiefe nicht benötigen, verwenden Sie einfach die Standard-Zuordnung für alle Antworten oder lassen Sie sie unverändert.

Antwortvorschau (2)

Dies ist die Struktur der API-Antwort, die während Ihres letzten Tests zurückgegeben wurde.
Klicken Sie auf das ➕-Symbol neben einem beliebigen Wert, um ihn einer $context-Variablen zuzuordnen.
Anstelle einer Zuordnung können Sie mit der Schaltfläche Ø auch prüfen, ob ein Wert leer ist, wodurch ein boolesches $context-Flag (true oder false) erstellt wird.

Ausgabe + Präfix (3)

Die Liste auf der rechten Seite zeigt Ihre aktuellen Zuordnungsregeln.

Sie können ein Präfix festlegen (z. B. $response, $order, $apiResult), das jedem Kontextnamen vorangestellt wird.

💡

Verwenden Sie ein klares und eindeutiges Präfix, um Kontextwerte bei der Nutzung mehrerer APIs übersichtlich zu halten.

Dynamische Ports (4)

Jedes Integrationsmodul (die „Box“, die Sie verwenden, wenn Sie Ihre Integration mit Ihrem Dialogfluss verbinden) enthält zwei Standardausgänge:

• Success: Anfrage wurde innerhalb des festgelegten Timeout-Zeitraums erfolgreich abgeschlossen
• Failure: Anfrage ist fehlgeschlagen oder hat das Timeout überschritten

Sie können auch benutzerdefinierte Ausgänge (Ports) erstellen, wie z. B.:

• Order not found → wenn $get_order_state nicht existiert
• Order delivered → wenn $get_order_state gleich "delivered" ist

Note

Die Bedingungen in den dynamischen Ports werden von oben nach unten ausgewertet. Im folgenden Beispiel würde die zweite Bedingung Order delivered daher nie ausgelöst, denn wenn der Kontext $get_order_state gleich "delivered" ist, bedeutet das auch, dass er existiert, und der erste Port wird ausgelöst.

• Order found → Kontext $get_order_state existiert (irgendein Wert ist ihm zugeordnet)
• Order delivered → $get_order_state ist gleich "delivered"

---

Registerkarte Protokoll

Die Registerkarte Protokoll bietet einen vollständigen Verlauf aller über diesen Endpunkt getätigten Anfragen, egal ob es sich um Testanfragen oder um während Live-Dialogen ausgelöste Anfragen handelte.

2. cURL importieren

Sie können eine Anfrage auch im cURL-Format importieren. Sie müssen dennoch die Zuordnung und, falls erforderlich, die Vor-/Nachverarbeitung manuell festlegen.