Eigene API-Aktionen: deine API aus dem Chat aufrufen
Lass deinen intoCHAT-Agenten im Chat deine HTTP-API aufrufen: Anfrage und Authentifizierung, cURL-Import, Eingaben aus dem Gespräch und Test.
Mit einer eigenen API-Aktion ruft der Agent während des Gesprächs einen HTTP-Endpunkt auf, etwa um aktuellen Lagerbestand oder Preise abzufragen, und antwortet auf Basis der Antwort. Aktionen legst du im Tab Actions (Aktionen) deines Agenten an. Soll der Agent einen Link anbieten, statt eine API aufzurufen, siehe Eigene Buttons.
Aktion anlegen
Klicke auf Add Action oder auf Import a request, um mit einem cURL-Befehl zu starten. Der Editor hat vier Schritte, gespeichert wird einmal am Ende mit Create action. Ein Test ist freiwillig, aber empfehlenswert.
1. The request (die Anfrage)
- Method: GET, POST, PUT, PATCH oder DELETE.
- HTTPS URL: der Endpunkt. Ein Query-String in der URL wird in den Tab Parameters verschoben.
- Parameters, Headers und Body nehmen Schlüssel-Wert-Paare auf. Body gibt es bei allen Methoden außer GET, er wird als JSON gesendet.
- Collect data inputs for action (optional): Werte, die der Agent aus dem Gespräch füllt. Jede Eingabe hat einen Name (Buchstaben, Ziffern und Unterstriche), einen Type (Text, Number oder Boolean), eine Description sowie die Optionen Required und Array. Bis zu 25 Eingaben pro Aktion.
Verwende eine Eingabe überall in der Anfrage als {{name}}, im URL-Pfad, in einem Parameter, einem Header oder im Body:
GET https://api.example.com/products/{{productId}}/stock
Der Agent findet den Wert im Gespräch oder fragt den Besucher danach. Eine Eingabe mit Required verhindert, dass der Agent die Aktion aufruft, bevor er den Wert hat. Variablen, die benutzt, aber nicht als Eingabe angelegt sind, fallen aus der Anfrage heraus; der Editor warnt dich und bietet Add them an.
Platzhalter für verifizierte Besucher
Hast du die Identitätsprüfung eingerichtet, kann eine server-seitige Aktion in URL, Parametern, Headern und Body außerdem {{user.id}}, {{user.email}}, {{user.name}} und {{user.metadata.<key>}} verwenden:
GET https://api.example.com/customers/{{user.id}}/orders
Das sind keine Eingaben: intoCHAT füllt sie auf seinen Servern mit dem Besucher, den deine Website angemeldet und verifiziert hat, und lässt sie für alle anderen und bei Send test request leer. Die KI sieht sie nie und kann sie nicht wählen. Andere {{user.…}}-Platzhalter lassen sich nicht speichern. Siehe Platzhalter in server-seitigen Aktionen.
Platzhalter für Kontakte
Eine server-seitige Aktion kann auch den Kontakt des Besuchers lesen: {{contact.email}}, {{contact.name}}, {{contact.phone}}, {{contact.external_id}} und {{contact.<attribute>}}, etwa {{contact.plan}}:
GET https://api.example.com/accounts/{{contact.external_id}}?plan={{contact.plan}}
Bei einem verifizierten Besucher ist das der Kontakt mit seiner User-ID, bei allen anderen der Kontakt des Leads, der im Gespräch gespeichert wurde, außer dieser Kontakt hat eine External ID. intoCHAT füllt sie auf seinen Servern aus, und die KI sieht sie nie. Anders als bei {{user.*}} wird nichts leer gesendet: Gibt es keinen Kontakt oder fehlt ein Wert, läuft die Aktion nicht, und der Agent erfährt, dass er das hier nicht erledigen kann. Unbekannte Platzhalter wie {{contact.Plan}} lassen sich nicht speichern, Send test request kann sie nicht ausfüllen, und client-seitige Aktionen bekommen sie nie. Siehe Kontakte in Aktionen nutzen.
Authentifizierung
| Option | Was gesendet wird |
|---|---|
| No authentication | Nichts |
| Bearer token / access token | Ein Header Authorization: Bearer mit deinem Token |
| API key in a header | Dein Schlüssel in dem Header, den du angibst, etwa X-API-Key |
| API key in the URL | Dein Schlüssel als Query-Parameter mit dem Namen, den du angibst, etwa api_key |
| Username and password | HTTP-Basic-Authentifizierung |
| Custom — I'll set the headers myself | Was du im Tab Headers einträgst |
Anfrage importieren
Füge das cURL-Beispiel aus der Dokumentation deiner API ein oder nutze „Copy as cURL“ für eine Anfrage in den Netzwerk-Tools deines Browsers. Methode, URL, Query-Parameter, Header und Body werden ausgefüllt, die Zugangsdaten landen in der Auswahl Authentication. Der Import ersetzt die Anfrage, Name und Beschreibung bleiben erhalten. Multipart-Uploads (-F) werden übersprungen, ein formularcodierter Body wird als JSON-Felder übernommen.
2. Try it (testen)
Gib Testwerte für die Eingaben ein und klicke auf Send test request. Die Anfrage wird genau so gebaut, wie der Agent sie baut. Die Response Preview zeigt Status, Antwort und die aufgerufene URL.
3. When the AI should use it (wann die KI sie nutzt)
- Action Name: bis zu 60 Zeichen.
- When to use: was die Aktion tut, welche Daten sie liefert und Beispielfragen, bei denen sie greifen soll. Das Modell liest die ersten 1.024 Zeichen.
- Server-side action läuft auf den Servern von intoCHAT und ist die Voreinstellung. Client-side action läuft im Browser des Besuchers, siehe Client-seitige Aktionen.
- Enable this action: schaltet eine Aktion ab, ohne sie zu löschen.
- Only inside procedures (nur bei server-seitigen Aktionen): Der Agent kann die Aktion nur aufrufen, wenn ein Schritt eines Ablaufs sie aufruft, nie von sich aus. Ein Aufruf zu jedem anderen Zeitpunkt wird abgelehnt, und es wird nichts gesendet. Nutze das für Aktionen, die etwas verändern, etwa eine Erstattung. Die Aktion zeigt dann in der Liste ein Badge Procedure only.
- Requires team approval (nur bei server-seitigen Aktionen, Pro und Enterprise): Ruft der Agent die Aktion auf, wird noch nichts gesendet. Der Aufruf wartet mit seinen Eingaben auf der Seite Approvals, bis jemand, der diesen Agenten bearbeiten darf, ihn freigibt (dann läuft er mit genau diesen Eingaben) oder ablehnt, und der Besucher erfährt das Ergebnis im Chat. Wähle, wann eine unentschiedene Anfrage verfällt: nach 1 Stunde, 4 Stunden, 24 Stunden oder 3 Tagen. Die Aktion zeigt in der Liste ein Badge Needs approval. Siehe Freigabe von Aktionen durch das Team.
4. What the AI can see (was die KI sieht)
Full data access gibt die ganze Antwort an das Modell weiter. Limited data access gibt nur die Felder weiter, die du unter Visible anhakst; führe zuerst einen Test aus, damit die Feldliste erscheint. Ist die Antwort eine Liste, kommen die Felder aus dem ersten Eintrag und der Filter gilt für alle Einträge. Solange kein Feld angehakt ist, wird die ganze Antwort weitergegeben.
Grenzen und Sicherheit
- Bis zu 25 Aktionen pro Agent, einschließlich eigener Buttons und der Aktionen aus Shop verbinden.
- Chat-Formulare, Abläufe, die Terminbuchung mit Cal.com oder Calendly und die Websuche zählen nicht zu diesem Limit.
- Eine Aktion, die ein Schritt eines Ablaufs aufruft, lässt sich nicht löschen und nicht in eine client-seitige Aktion oder einen Button ändern, solange du sie nicht aus dem Ablauf nimmst. Die Meldung nennt die Abläufe.
- Eine API-Aktion oder ein Button, der wie ein eingebautes Werkzeug heißt, etwa „search web“ oder „show booking slots“, wird im Hintergrund mit einer Nummer umbenannt (
search_web_2), damit Websuche und Terminbuchung weiter funktionieren. Eine client-seitige Aktion behält ihren genauen Namen, weil der Handler deiner Seite unter diesem Namen registriert ist: Nenne keinesearch_web, sonst kann der Agent die Websuche nicht nutzen, solange diese Aktion eingeschaltet ist. - Die URL muss auf einen öffentlichen Host zeigen. Localhost, private Netze, Link-Local-Adressen und Cloud-Metadaten-Endpunkte werden abgelehnt, auch wenn ein Hostname auf eine solche Adresse auflöst. Der Editor zeigt dann „URL points to a blocked or internal host“.
- Weiterleitungen werden nicht verfolgt. Zeigt der Test „This address redirects somewhere else“, klicke auf Use this address.
- Jeder Aufruf bricht nach 30 Sekunden ab.
- Antworten über 40.000 Zeichen werden abgeschnitten. Mit Limited data access bleiben sie klein.
- Server-seitige Aktionen senden deine Zugangsdaten von den Servern von intoCHAT, nie über den Browser des Besuchers.