Benutzerdefinierte Aktionen

In diesem Leitfaden lernst du:

Deinen Agenten mit beliebigen externen APIs zu verbinden
Authentifizierung zu konfigurieren (Bearer, Basic, API Key)
Parameter zu definieren, die der Agent vom Anrufer einsammelt
Tool-Ausführung zu testen und zu debuggen

Wie benutzerdefinierte Aktionen funktionieren

Benutzerdefinierte Aktionen lassen deine KI-Agenten während des Gesprächs mit externen Systemen integrieren. Deine Agenten können Kundendaten abrufen, CRM-Datensätze aktualisieren, Lagerbestand prüfen, Tickets erstellen und Business-Logik ausführen - alles in Echtzeit, während sie mit Kunden sprechen. So funktioniert es:

API-Endpunkt konfigurieren - HTTP-Methode, URL, Authentifizierung, Header und Request Body einrichten
Variablen definieren - Festlegen, welche Informationen der Agent vor dem API-Aufruf einsammeln muss
Agent nutzt es - Während des Gesprächs sammelt der Agent die Variablen ein und ruft deine API auf
API antwortet - Dein System gibt Daten zurück, mit denen der Agent das Gespräch fortsetzt

Benutzerdefinierte Aktionen laufen synchron während des Gesprächs. Für Operationen, die keine sofortige Antwort brauchen, etwa Logging, Insights-Auswertung oder Post-Call-Verarbeitung, nutze stattdessen Webhooks.

Beispielablauf

Customer: "What's the status of my order?"

Agent: (collects order number from customer)

[Agent calls API]
-> GET https://api.company.com/orders/12345
<- { "status": "shipped", "tracking": "1Z999AA10123456789" }

Agent: "Your order has shipped! Your tracking number is
       1Z999AA10123456789 and it should arrive by Friday."

Security: Verify customer identity before exposing sensitive data. Authentifiziere Kunden immer, bevor du APIs aufrufst, die persönliche Informationen, Bestelldetails oder Account-Daten zurückgeben.

Eine benutzerdefinierte Aktion erstellen

Zu Tools navigieren

Gehe im Agent-Editor zu Tools > Hinzufügen > Benutzerdefinierte Aktion.

Basisinfos konfigurieren

Name: Beschreibender Name, zum Beispiel “Lookup Order Status”
Beschreibung: Wann dieses Tool verwendet werden soll (10-200 Zeichen). Das hilft der KI, den Aufruf zu entscheiden.

Endpoint konfigurieren

Wähle die HTTP-Methode und gib die Endpoint-URL ein. Siehe Endpoint Configuration unten.

Authentifizierung einrichten

Wähle eine Authentifizierungsmethode. Siehe Authentication Methods unten.

Header und Body hinzufügen

Konfiguriere benutzerdefinierte Header, Query-Parameter und den Request Body im Parameters-Tab.

Variablen definieren

Füge Variablen hinzu, die der Agent aus dem Gespräch einsammeln soll. Siehe Variables unten.

Tool testen

Speichere und teste die Action über Agent testen mit einem browserbasierten Gespräch, Telefonanruf oder einer Chat-Session.

Endpoint-Konfiguration

HTTP-Methode

Methode	Anwendungsfall
GET	Daten abrufen (Order-Status, Kundeninfos)
POST	Datensätze erstellen (Tickets, Leads, Bestellungen)
PUT	Ganze Datensätze ersetzen
PATCH	Bestimmte Felder aktualisieren
DELETE	Datensätze entfernen

Endpoint-URL

Gib die volle API-URL ein. Die Plattform setzt automatisch https:// davor, wenn du das Protokoll weglässt.

https://api.company.com/customers

Die Endpoint-URL selbst ist statisch. Verwende Query-Parameter oder den JSON-Request-Body für {{variable_name}}-Substitutionen.

Authentifizierungsmethoden

Keine

Keine Authentifizierung erforderlich. Für öffentliche APIs oder interne Endpunkte in privaten Netzwerken.

Bearer Token

Am häufigsten für moderne APIs. Sendet den Header Authorization: Bearer {your_token}.Use for: OAuth-2.0-Access-Tokens, JWT-Authentifizierung, moderne REST APIs.

Basic Auth

Username/Passwort-Authentifizierung. Sendet den Header Authorization: Basic {base64(username:password)}.Use for: Legacy-APIs, einfache Authentifizierungsschemata.

Header

Benutzerdefinierte Header-basierte Authentifizierung, z. B. X-API-Key: {your_api_key}.Use for: API-Key-Authentifizierung, benutzerdefinierte Schemata.

Body

Credentials im Request Body gesendet, z. B. {"api_key": "{your_key}"}.Use for: Nicht-standardisierte Authentifizierung, Login-Endpunkte.

Für Bearer-, Basic-Passwort-, Header-Wert- und Body-Wert-Authentifizierung wähle oder erstelle ein gespeichertes Credential aus Secrets. Bestehende Credentials bleiben beim Bearbeiten erhalten; wähle nur dann ein neues, wenn du sie ersetzen willst.

Parameter-Konfiguration

Profi

Headers

Füge benutzerdefinierte HTTP-Header als Key-Value-Paare hinzu. Beispiel: Content-Type: application/json

Query Parameters (GET requests)

Füge URL-Query-Parameter als Key-Value-Paare hinzu. Template-Variablen werden in Query-Parameter-Werten unterstützt. Beispiel:

order_id={{order_id}}
include=tracking

Request Body (POST/PUT/PATCH)

Schreibe deinen JSON-Request-Body im Editor. Nutze {{variable_name}}-Syntax, um Werte aus dem Gespräch einzufügen.

{
  "customer_id": "{{customer_id}}",
  "status": "contacted",
  "timestamp": "{{current_datetime}}"
}

Variablen - Parameter-Mapping aus dem Gesprächskontext

Profi Variablen definieren, welche Informationen dein Agent vor dem API-Aufruf aus dem Gespräch einsammeln muss. Jede Variable sagt der KI, welche Information sie vor der Anfrage vom Anrufer sammeln soll.

Variablenfelder

Feld	Beschreibung
Name	Variablenname, zum Beispiel `order_number`, `customer_email`
Typ	Datentyp: string, integer, float, boolean, date, email, phone
Beschreibung	Wofür diese Variable ist (hilft der KI zu verstehen, wann sie die Info einsammeln soll)
Beispiel	Beispielwert (zeigt der KI das erwartete Format)
Erforderlich	Wenn true, muss die KI diese Info vor dem API-Aufruf einsammeln
Standardwert	Wird genutzt, wenn die Variable nicht erforderlich ist und der Kunde sie nicht liefert

Beispiel-Variable

Name: order_number
Typ: string
Beschreibung: Bestellnummer des Kunden, beginnt normalerweise mit ORD-
Beispiel: ORD-12345
Erforderlich: Ja

Die KI weiß dann, dass sie den Kunden vor der Anfrage nach der Bestellnummer fragen muss.

Laufzeitvariablen

Benutzerdefinierte Aktions-Templates nutzen flache {{variable_name}}-Platzhalter in Headern, Query-Parametern und im Request Body. Diese Laufzeitwerte sind verfügbar, wenn sie existieren:

{{agent_number}}
{{agent_uuid}}
{{contact_number}}
{{direction}}
{{medium}}
{{current_datetime}}
{{timezone}}

Werte aus Dynamic Context sind ebenfalls unter ihrem Top-Level-Key verfügbar, etwa {{account_id}} oder {{cal_email}}.

Geschachtelte Prompt-Variablen wie {{contact.email}} sind für die Prompt-Renderung gedacht, nicht für die Substitution in Custom-Action-Payloads. Wenn die Action einen Namen oder eine E-Mail des Anrufers braucht, definiere eine Variable, die der Agent einsammeln soll, oder liefere einen flachen Key über Dynamic Context.

Tools testen

Endpoint unabhängig testen

Nutze Postman oder cURL, um zu prüfen, ob der Endpoint erreichbar ist, die Authentifizierung funktioniert und das Request-Format korrekt ist.

Mit statischen Werten starten

Konfiguriere die Action zuerst mit fest codierten Werten ohne Variablen, um die Grundfunktion zu prüfen.

Variablen hinzufügen

Ersetze die fest codierten Werte durch flache Template-Variablen wie {{order_id}}.

Im Agenten testen

Starte Agent testen und führe ein browserbasiertes Gespräch, einen Telefonanruf oder eine Chat-Session aus. Löse die Action im Gespräch aus und verifiziere:

Der Agent sammelt Variablen korrekt ein
Die API wird mit den richtigen Daten aufgerufen
Der Agent nutzt die Antwort passend

Fehlerszenarien testen

Prüfe das Verhalten des Agenten bei API-Fehlern:

404 (not found)
401 (authentication failed)
500 (server error)
Timeout

Fehlerbehandlung

Konfiguriere deinen Prompt so, dass API-Fehler sauber behandelt werden:

When using the 'Lookup Order Status' tool:

If the tool returns an error:
- 404: "I don't see an order with that number. Could you double-check?"
- 500: "I'm having trouble accessing the system right now."
- Timeout: "The system is taking longer than expected."
- For any error, offer to have someone call them back.

Fehlerbehebung

401 Unauthorized

Ursache: Ungültige Credentials oder falscher Auth-Typ.Lösung: Prüfe die Credentials, vergleiche den Auth-Typ mit den Anforderungen der API, teste mit Postman und denselben Credentials und prüfe, ob das Token abgelaufen ist.

404 Not Found

Ursache: Falsche URL oder Ressource existiert nicht.Lösung: Prüfe die statische Endpoint-URL, kontrolliere, ob Query-Parameter oder Body-Variablen korrekt eingesetzt werden, und teste zuerst mit statischen Werten.

Agent sammelt Variablen nicht ein

Ursache: Variablen nicht konfiguriert oder Beschreibungen unklar.Lösung: Prüfe, ob Variablen im Variablen-Tab definiert sind, füge klare Beschreibungen und Beispiele hinzu, setze required=true für essenzielle Variablen und referenziere das Tool im Prompt mit genauem Namen.

Variablen werden im Request nicht ersetzt

Ursache: Falsche Syntax oder Variable existiert nicht.Lösung: Verwende exakt {{variable_name}}, prüfe, ob die Variable definiert ist, und vermeide dotted Platzhalter wie {{contact.email}} in Custom-Action-Templates.

Timeout-Fehler

Ursache: API antwortet zu langsam.Lösung: Optimiere die Antwortzeit der API, verwende für langsame Operationen Webhooks und cache häufig genutzte Daten.

Sicherheitsempfehlungen

Nur HTTPS verwenden für alle API-Endpunkte
Credentials absichern - niemals in URLs hardcoden, Schlüssel regelmäßig rotieren
Berechtigungen begrenzen - für Lookup-Aktionen nur Read-only-Schlüssel verwenden
Eingaben validieren - deine API sollte auf Injections prüfen und Datentypen validieren
Identität prüfen - Kunden authentifizieren, bevor sensible Daten angezeigt werden

Praxisbeispiele

CRM Customer Lookup

Method: GET
URL: https://api.salesforce.com/customers
Auth: Bearer token
Variable: customer_id (string, required)
Query parameter: customer_id={{customer_id}}

Support-Ticket erstellen

Method: POST
URL: https://company.zendesk.com/api/v2/tickets
Auth: Basic (email/token)
Variables: issue_description (string), priority_level (string)
Body:

{
  "ticket": {
    "subject": "Call with {{caller_name}}",
    "description": "{{issue_description}}",
    "priority": "{{priority_level}}"
  }
}

Produktbestand prüfen

Method: GET
URL: https://inventory.company.com/products/availability
Auth: Header (X-API-Key)
Variable: sku (string, required, example: “PROD-12345”)
Query parameter: sku={{sku}}

Nächste Schritte

Tools-Übersicht

Mehr über alle Tool-Typen erfahren

Fehlerbehebung benutzerdefinierter Aktionen

Auth-, Payload-, Timeout- und Response-Probleme diagnostizieren

Buchungs-Tools

Cal.com-Terminplanung einrichten

Gesprächsdatenfluss

Verstehen, woher Variablen kommen und was nach der Tool-Ausführung passiert

Template-Syntax

Template-Variablen meistern

MCP-Server

MCP-Server für fortgeschrittene Integrationen verbinden

​Wie benutzerdefinierte Aktionen funktionieren

​Beispielablauf

​Eine benutzerdefinierte Aktion erstellen

​Endpoint-Konfiguration

​HTTP-Methode

​Endpoint-URL

​Authentifizierungsmethoden

​Parameter-Konfiguration

​Headers

​Query Parameters (GET requests)

​Request Body (POST/PUT/PATCH)

​Variablen - Parameter-Mapping aus dem Gesprächskontext

​Variablenfelder

​Beispiel-Variable

​Laufzeitvariablen

​Tools testen

​Fehlerbehandlung

​Fehlerbehebung

​Sicherheitsempfehlungen

​Praxisbeispiele

​Nächste Schritte

Tools-Übersicht

Fehlerbehebung benutzerdefinierter Aktionen

Buchungs-Tools

Gesprächsdatenfluss

Template-Syntax

MCP-Server

Wie benutzerdefinierte Aktionen funktionieren

Beispielablauf

Eine benutzerdefinierte Aktion erstellen

Endpoint-Konfiguration

HTTP-Methode

Endpoint-URL

Authentifizierungsmethoden

Parameter-Konfiguration

Headers

Query Parameters (GET requests)

Request Body (POST/PUT/PATCH)

Variablen - Parameter-Mapping aus dem Gesprächskontext

Variablenfelder

Beispiel-Variable

Laufzeitvariablen

Tools testen

Fehlerbehandlung

Fehlerbehebung

Sicherheitsempfehlungen

Praxisbeispiele

Nächste Schritte