Über benutzerdefinierte API-Integrationen kann Ihr Chatbot Live-Informationen aus Ihrem ERP, Warenlager, CRM oder einem anderen Dienst abrufen. Sie können auch Änderungen vornehmen, beispielsweise einen Termin erstellen. Eine Integration speichert die Basis-URL; jede Operation definiert eine aufrufbare Anfrage. Anschließend weisen Sie ausgewählte Operationen einem Chatbot als KI-Aktionen (AI actions) zu.
Bevor Sie beginnen
Prüfen Sie, ob Ihr Konto benutzerdefinierte API-Integrationen (Custom API integrations) enthält. Sie benötigen die URL des Endpunkts, die HTTP-Methode, Parameternamen und -typen, Authentifizierungsanforderungen sowie eine Beispielantwort. Der Endpunkt muss von den ChatLab-Servern aus erreichbar sein; localhost auf Ihrem Computer ist kein produktiver Endpunkt.
Verwenden Sie HTTPS sowie einen Testdienst oder Testdatensätze für die Einrichtung. Eine Testanfrage ruft den Endpunkt tatsächlich auf, sodass ein POST, PATCH oder DELETE externe Daten ändern kann. Stellen Sie nach Möglichkeit sicher, dass Vorgänge sicher wiederholt werden können.
1. Integration erstellen
- Öffnen Sie Custom Integrations (Eigene Integrationen) in der Hauptnavigation.
- Klicken Sie auf + Define API Integration (+ API-Integration definieren).
- Geben Sie API name (API-Name) und API Base URL (API-Basis-URL) ein, zum Beispiel
https://api.example.com. - Klicken Sie auf Create API Integration (API-Integration erstellen).
- Klicken Sie in der Listenansicht auf View (Anzeigen) und dann auf + Define API Operation (+ API-Operation definieren).
2. Definieren Sie die Operation
Geben Sie der Operation ein wiedererkennbares Label und einen maschinenlesbaren Operationsnamen (Operation name), wie etwa getProductDetails. Verwenden Sie für den Operationsnamen nur Buchstaben und Zahlen, keine Leerzeichen oder Unterstriche. Beschreiben Sie, was die Operation tut und wann der Chatbot sie verwenden soll.
Geben Sie den relativen URI ein, zum Beispiel /v1/products/@productId@. Die Basis-URL und der URI bilden die Anfrageadresse.
Einige vorhandene Screenshots zeigen ältere Beispielnamen oder Platzhalter mit geschweiften Klammern. Folgen Sie der unten stehenden aktuellen Syntax: Operationsnamen wie getProductDetails und Parameterplatzhalter umgeben von @.
Pfad- und Query-Parameter
Klicken Sie auf Pfadvariable hinzufügen (Add path variable), um productId zu definieren. Legen Sie den Datentyp und die Wertequelle fest und binden Sie dann @productId@ in den URI ein. Pfadvariablen sind Pflichtfelder, und jede definierte Pfadvariable muss im URI vorkommen, bevor Sie speichern oder testen können.
Verwenden Sie Query-Parameter hinzufügen (Add query parameter) für Parameter wie limit oder language, die nach dem Fragezeichen der URL stehen. Geben Sie den von Ihrer API erwarteten Namen, den Typ, die Beschreibung und die Wertequelle ein.
Zu den verfügbaren Wertequellen gehören:
- Vom Benutzer oder Chatbot bereitgestellt (Provided by user or chatbot): Das Modell liefert einen Wert aus der Unterhaltung. Erläutern Sie das erwartete Format und kennzeichnen Sie erforderliche Werte entsprechend.
- Konstante (Constant): Ein in der Operation konfigurierter Wert, wie etwa eine feste Konto-ID oder eingeschränkte API-Zugangsdaten.
- Zufallswert (Random value): Ein automatisch generierter Wert.
- Client-Kontext (Client context): Ein von der Host-Website übergebener Wert, sofern für Ihr Konto verfügbar. Siehe Chat API.
Zu den skalaren Typen gehören String, Integer, Double und Boolean. Body-Parameter unterstützen zudem String- und Integer-Arrays.
3. Konfigurieren Sie Methode und Body
Wählen Sie GET, POST, PUT, PATCH oder DELETE passend zu Ihrem Endpunkt. Für andere Methoden als GET bietet der Editor Anfrageinhalte im Format raw oder form-data an.
Für einen Raw-JSON-Body definieren Sie die Body-Parameter und fügen Sie deren @name@-Platzhalter in die Vorlage ein. Fügen Sie den entsprechenden Content-Type-Header hinzu, den Ihr Endpunkt erfordert. Beispiel mit den Parametern name (String) und tags (String-Array):
{
"name": "@name@",
"tags": @tags@
}
Dies ist eine Vorlage und erst nach der Ersetzung gültiges JSON. Array-Platzhalter dürfen nicht in Anführungszeichen gesetzt werden. Jeder definierte Body-Parameter muss in der Vorlage verwendet werden, wenn der Raw-Body-Editor aktiv ist. Überprüfen Sie die gerenderte Anfrage beim Testen, insbesondere bei Text mit Anführungszeichen oder Sonderzeichen.
4. Authentifizierungs-Header hinzufügen
Verwenden Sie Add header (Header hinzufügen), um die von der API erwarteten Header zu definieren. Verwenden Sie für ein Bearer-Token den Headernamen Authorization, die Wertequelle Constant (Konstante) und den Wert Bearer YOUR_RESTRICTED_TOKEN.
Halten Sie Geheimnisse aus Prompts und URLs fern. Vermeiden Sie Vorgänge, die Anmeldetokens an das Modell zurückgeben und sich auf Anweisungen verlassen, um diese zu verbergen. Bevorzugen Sie einen serverseitigen Integrationsendpunkt, der seine eigene Authentifizierung verwaltet und nur den zulässigen Vorgang bereitstellt.
5. Anfrage speichern und testen
- Klicken Sie im Operations-Editor auf Save changes (Änderungen speichern). Anders als in den regulären Chatbot-Einstellungen gibt es in diesem Editor eine explizite Schaltfläche zum Speichern.
- Klicken Sie auf Test API Operation (API-Operation testen). Die Schaltfläche ist deaktiviert, solange Änderungen nicht gespeichert sind.
- Geben Sie repräsentative Parameterwerte ein. Verwenden Sie für Array-Testeingaben kommagetrennte Werte.
- Führen Sie den Test nur mit Daten aus, zu deren Lesen oder Ändern Sie berechtigt sind.
- Prüfen Sie den Statuscode, den Response-Body, die Request-URL, Header, Body und alle in den Ergebnissen angezeigten Warnungen.
- Beheben Sie Fehler, speichern Sie und wiederholen Sie den Vorgang bei Bedarf.
Geben Sie keine Testergebnisse weiter, die Anmeldedaten enthalten. Geben Sie nach Möglichkeit fokussierte, paginierte Daten zurück: Große Antworten können abgeschnitten werden, bevor sie das Modell erreichen.
6. Die Operation an einen Chatbot anhängen
Öffnen Sie Ihren Chatbot und navigieren Sie zu Settings > Actions (Einstellungen > Aktionen). Nutzen Sie die Plus-Schaltfläche, um eine Aktion hinzuzufügen, suchen Sie Ihre Operation unter benutzerdefinierten APIs und verknüpfen oder aktivieren Sie sie. Das bloße Erstellen einer Integration auf Kontoebene macht nicht automatisch jede Operation für jeden Chatbot verfügbar.
Überprüfen Sie die Anweisungen der Aktion und die verfügbaren Sicherheitseinstellungen, und warten Sie dann auf den Gespeichert-Status. Unter KI-Aktionen finden Sie Details zum Aktions-Editor.
7. Erklären, wann es verwendet werden soll
Öffnen Sie Settings > Role & Behavior (Einstellungen > Rolle & Verhalten).
Wenn Sie benutzerdefinierte Rollenanweisungen verwenden, wählen Sie Custom Role Definition (Benutzerdefinierte Rollendefinition) und fügen Sie eine präzise Regel hinzu, zum Beispiel: "Wenn der Besucher fragt, ob ein Produkt vorrätig ist, rufen Sie getProductDetails mit der entsprechenden Produkt-ID auf. Melden Sie die zurückgegebene Verfügbarkeit zurück. Wenn die Abfrage fehlschlägt, erklären Sie, dass die Verfügbarkeit nicht geprüft werden konnte."
Behalten Sie die anderen nützlichen Anweisungen des Chatbots bei. Warten Sie auf den Status "Gespeichert" und nutzen Sie anschließend die Vorschau unter Overview (Übersicht), um realistische Fragen, fehlende Parameter, Fehler und nicht autorisierte Anfragen zu testen. Testunterhaltungen in der Vorschau können echte Vorgänge ausführen.
Der KI-Aufruf ist weder garantiert noch zwingend einmalig. Testen Sie mit dem Modell, das für Ihren Chatbot ausgewählt ist; gehen Sie nicht davon aus, dass ein Modellname allein die korrekte Tool-Nutzung garantiert.
Sicherheit und Fehlerbehebung
Ihr Endpunkt muss Anfragen authentifizieren und den Zugriff jedes Nutzers autorisieren, bevor vertrauliche Informationen zurückgegeben oder Änderungen vorgenommen werden. Eine vom Browser übermittelte Client-ID, E-Mail-Adresse, Bestellnummer oder ein Kontextfeld ist kein ausreichender Identitätsnachweis. Wenn Sie ein benutzerspezifisches Token über den Client-Kontext übergeben, muss Ihr Server dieses validieren.
Geben Sie nur die Felder zurück, die der Chatbot benötigt, wie etwa den Bestellstatus anstelle eines vollständigen Kundenprofils. Prompt-Anweisungen können die Formulierung steuern, können jedoch nicht garantieren, dass vertrauliche Daten, die an das Modell zurückgegeben werden, verborgen bleiben.
Wenn die Anfrage im Test-Editor erfolgreich ist, jedoch nicht in einer Unterhaltung, prüfen Sie die verknüpfte Aktion, ihren Aktivierungsstatus, die Anweisungen, erforderliche Parameter und den verfügbaren Kontext. Wenn beides fehlschlägt, überprüfen Sie die URL, die HTTP-Methode, die Authentifizierung, den gerenderten Body sowie die Protokolle Ihres Endpunkts. Vermeiden Sie es, einen Schreibvorgang wiederholt auszuführen, bevor Sie wissen, ob die vorherige Anfrage erfolgreich war.