API-Anfrage

Mit einer API-Anfrage holt dein Agent während des Telefonats Daten aus einem anderen System oder trägt sie dort ein: ein Ticket im Helpdesk, ein Lead im CRM, ein Bestellstatus aus dem Warenwirtschaftssystem.

6:53

So funktioniert es

Jede aktivierte API-Anfrage wird dem Sprachmodell als eigenes Werkzeug mit typisierten Parametern angeboten. Der Agent erkennt die Situation, sammelt die fehlenden Angaben im Gespräch, ruft die API auf und arbeitet mit dem, was zurückkommt.

Anrufer  ──▶  Agent erkennt die Situation
              Agent fragt fehlende Angaben ab
              Agent ruft deine API auf   ──▶  dein System
                                              antwortet
              Agent spricht weiter       ◀──

Angelegt wird sie über Kompetenzen → Fähigkeiten → API-Anfrage → + in einem vierstufigen Assistenten.

Schritt 1 — Grundlagen

Alle drei Felder sind Pflicht, sonst geht es nicht weiter.

Die letzten beiden Felder werden zu einer Beschreibung zusammengesetzt, und genau die liest das Sprachmodell. Sie entscheidet darüber, ob das Tool überhaupt aufgerufen wird — also konkret formulieren, keine Romane:

Was macht das Tool?
Legt ein Ticket für ein sonstiges Anliegen an — kein Termin,
keine Weiterleitung.

Wann soll es verwendet werden?
Aufrufen, sobald Name und Anliegen vollständig erfasst sind.

Schritt 2 — API-Konfiguration

Wann soll die API aufgerufen werden?

Der Modus Bei Anrufbeginn ist derselbe Mechanismus wie der Anruferkontext — dort ist er ausführlich beschrieben, inklusive CSV-Variante ohne eigene API. Für diesen Modus empfiehlt sich ein Timeout von 3000 ms, damit der Anrufer nicht auf die Begrüßung wartet.

Endpunkt

Bei längeren Workflows das Timeout hochsetzen — 5 bis 15 Sekunden sind praxisnah. Alles darüber lässt den Anrufer in der Leitung warten.

Schritt 3 — Parameter und Header

Header

Schlüssel-Wert-Paare für Authentifizierung und Format. Leere Zeilen werden beim Speichern verworfen.

Dynamische Parameter (JSON-Schema)

Hier beschreibst du als JSON-Schema, welche Werte der Agent aus dem Gespräch ziehen soll. Das Schema legt die Struktur fest, nicht die Werte — die füllt der Agent zur Laufzeit.

{
  "type": "object",
  "properties": {
    "name":     { "type": "string", "description": "Vollständiger Name des Anrufers" },
    "anliegen": { "type": "string", "description": "Worum es geht, in ein bis zwei Sätzen" },
    "prioritaet": {
      "type": "string",
      "enum": ["niedrig", "mittel", "hoch"],
      "description": "Wie dringend die Sache ist"
    }
  },
  "required": ["name", "anliegen"]
}

Der Dialog bietet fertige Beispiele (Einfache Felder, Mit Auswahloptionen, Support-Ticket), prüft dein JSON live und kann es über JSON formatieren aufräumen.

Fixe Parameter

Konstante Werte, die bei jedem Aufruf mitgehen — API-Keys, Mandanten-IDs, Konfigurationsflags:

{
  "apiKey": "dein-api-key",
  "quelle": "telefon"
}

Was am Ende wirklich gesendet wird

Drei Quellen werden zusammengeführt, von der schwächsten zur stärksten:

Systemvariablen  →  fixe Parameter  →  vom Agenten extrahierte Parameter
  (schwächste)                                   (stärkste)

Bei gleichem Schlüssel gewinnt also immer der Wert aus dem Gespräch. Platzhalter in der URL werden aus demselben zusammengeführten Satz ersetzt.

Systemvariablen

Diese Werte stellt ScaleTalk automatisch bereit — als Parameter und als {{platzhalter}} in der URL:

https://crm.example.com/kunden/{{fromNumber}}/tickets

Leere Systemvariablen werden vor dem Senden entfernt.

Schritt 4 — Prüfen und testen

Der letzte Schritt fasst alles zusammen und bietet einen echten Testaufruf:

1. Auf Test klicken — der Assistent füllt Beispielwerte aus deinem Schema vor
2. Werte anpassen und Test ausführen
3. Statuscode, Antwort und Laufzeit prüfen

Der Test läuft serverseitig über ScaleTalk, nicht aus dem Browser — dadurch gibt es keine CORS-Probleme und der Aufruf entspricht dem echten Betrieb. Aufrufe an localhost und andere lokale Adressen werden blockiert, und das Timeout ist im Test auf 30 Sekunden gedeckelt.

Speichern ist möglich, sobald Name, beide Beschreibungen und die URL gesetzt sind.

Grenzen

Die Anzahl der Header und Parameter innerhalb eines Tools ist nicht begrenzt.

Was der Agent bei Fehlern erfährt

Schreib in den Prompt, was in diesen Fällen passieren soll — sonst improvisiert der Agent.

Integration mit n8n

Die häufigste Variante in der Praxis ist n8n: Die Automationsplattform nimmt den Request entgegen, verarbeitet ihn und antwortet. Kein eigener Server nötig, und fast jedes gängige System ist dort schon angebunden.

Ablauf

1. In n8n einen Webhook-Node anlegen, Methode POST — er erzeugt eine URL
2. Diese URL in ScaleTalk als URL eintragen
3. Der Agent löst den Request aus, ScaleTalk schickt die Daten an n8n
4. n8n verarbeitet sie — Ticket anlegen, CRM aktualisieren, Zeile in Google Sheets schreiben
5. n8n antwortet, der Agent nutzt die Antwort im Gespräch

Workflow einrichten

Ein typischer Ablauf:

Webhook → Daten aufbereiten → Ticket erstellen → Respond to Webhook

Der letzte Node muss Respond to Webhook sein, sonst bekommt der Agent nichts zurück:

{
  "success": true,
  "ticket_id": "TK-20260218-042",
  "message": "Ticket erfolgreich erstellt"
}

Damit sagt der Agent: „Ich habe Ticket TK-20260218-042 für Sie angelegt."

Bei n8n-Webhooks ist in der Regel keine Authentifizierung nötig — die URL selbst ist das Geheimnis. Behandle sie entsprechend.

Im Prompt referenzieren

Die Konfiguration allein löst nichts aus. Im System-Prompt legst du fest, wann das Tool gerufen wird:

### Wenn der Anrufer eine allgemeine Frage oder einen
### Rückrufwunsch zu einem neuen Thema hat:
1. Erfasse Name und Anliegen vollständig.
2. Rufe das Tool "Ticket anlegen" auf.
3. Nenne dem Anrufer die zurückgegebene Ticketnummer.
4. Wenn das Tool fehlschlägt: Sage zu, dass du das Anliegen
   manuell weitergibst, und beende das Gespräch normal.

Wenn etwas nicht klappt

Zum Debuggen hilft ein Request-Inspector wie webhook.site als temporärer Endpunkt — dort siehst du exakt, was ScaleTalk sendet.