API Request (During-Call)

Mit During-Call API Requests kann dein Agent während eines laufenden Gesprächs HTTP-Anfragen an externe Systeme senden. Damit verbindest du deinen Agenten mit CRMs, Ticketsystemen, Datenbanken oder beliebigen Backends — in Echtzeit.

Typische Anwendungsfälle:

• Support-Ticket automatisch anlegen, während der Anrufer noch am Telefon ist
• Kundenstatus oder Auftragsinformationen aus einem CRM abrufen
• Terminbestätigung per SMS über einen externen Service auslösen
• Lead-Daten direkt in ein CRM oder eine Datenbank schreiben

So funktioniert es

1. Du konfigurierst einen API Request im Tab Fähigkeiten deines Agenten
2. Du beschreibst dem Modell in der Beschreibung, wann und warum es dieses Tool aufrufen soll
3. Während des Gesprächs erkennt der Agent den richtigen Moment und sendet den Request
4. Die Antwort des externen Systems wird dem Agenten zurückgegeben
5. Der Agent verwendet die Antwort im Gespräch (z. B. „Ihr Ticket wurde erstellt")

Der Anrufer merkt davon nichts — für ihn läuft das Gespräch nahtlos weiter.

Konfiguration

Jeder API Request besteht aus folgenden Feldern:

Parameter (JSON-Schema)

Im Feld Parameter definierst du als JSON-Schema, welche Daten der Agent aus dem Gespräch extrahieren und mitsenden soll. Das Modell füllt diese Felder automatisch basierend auf dem Gesprächsverlauf.

Beispiel: Support-Ticket erstellen

{
  "type": "object",
  "properties": {
    "caller_name": {
      "type": "string",
      "description": "Vollständiger Name des Anrufers"
    },
    "company": {
      "type": "string",
      "description": "Firmenname des Anrufers, falls genannt"
    },
    "issue_summary": {
      "type": "string",
      "description": "Zusammenfassung des Problems in 1–2 Sätzen"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "description": "Dringlichkeit: low, medium oder high"
    },
    "callback_number": {
      "type": "string",
      "description": "Rückrufnummer des Anrufers"
    }
  },
  "required": ["caller_name", "issue_summary", "priority"]
}

Das Modell erkennt während des Gesprächs automatisch die passenden Werte: Wenn der Anrufer sagt „Hier ist Herr Müller von der Firma Weber, unser Server ist seit heute Morgen nicht erreichbar", füllt das Modell caller_name, company und issue_summary selbstständig.

Weitere Beispiele

Kundenstatus abfragen (GET):

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "Kundennummer des Anrufers"
    }
  },
  "required": ["customer_id"]
}

Lead-Daten an CRM senden (POST):

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "description": "Name" },
    "email": { "type": "string", "description": "E-Mail" },
    "phone": { "type": "string", "description": "Telefonnummer" },
    "interest": { "type": "string", "description": "Wofür interessiert sich der Anrufer" }
  },
  "required": ["name", "phone"]
}

Beschreibung für das Modell

Das Feld Beschreibung ist entscheidend. Hier erklärst du dem Modell in natürlicher Sprache, wann es das Tool aufrufen soll. Je präziser die Beschreibung, desto zuverlässiger der Aufruf.

Rufe dieses Tool auf, nachdem der Anrufer sein Problem
geschildert hat und du die wichtigsten Informationen
(Name, Problem, Dringlichkeit) gesammelt hast.

Rufe es NICHT auf, bevor du das Anliegen vollständig
verstanden hast.

Wenn der Request erfolgreich ist, bestätige dem Anrufer:
"Ich habe ein Ticket für Sie erstellt. Unser Team
meldet sich zeitnah bei Ihnen."

Wenn der Request fehlschlägt, sage:
"Leider konnte ich das Ticket gerade nicht anlegen.
Ich nehme Ihr Anliegen aber auf und leite es manuell weiter."

Zusätzlich solltest du das Tool-Verhalten im System-Prompt referenzieren, z. B.:

### Wenn der Kunde ein technisches Problem meldet:
1. Höre das Problem vollständig an.
2. Fasse es in eigenen Worten zusammen.
3. Erfrage Name und Rückrufnummer.
4. Erstelle das Support-Ticket über das Tool.
5. Bestätige: "Ich habe ein Ticket für Sie erstellt."

Integration mit n8n

Die häufigste Methode für API Requests ist über n8n — eine Open-Source Workflow-Automationsplattform. n8n empfängt den Request, verarbeitet die Daten und gibt eine Antwort zurück.

Ablauf

1. Erstelle in n8n einen Webhook-Node (Methode: POST) — er generiert eine URL
2. Trage diese URL in ScaleTalk im Feld URL ein
3. Wenn der Agent den Request auslöst, sendet ScaleTalk die Daten an n8n
4. n8n verarbeitet die Daten (z. B. Ticket anlegen, CRM updaten)
5. n8n sendet eine Antwort zurück, die der Agent im Gespräch verwendet

n8n Workflow einrichten

Schritt 1: Webhook-Node anlegen

Erstelle einen neuen Workflow und füge als ersten Node einen Webhook hinzu. Wähle die Methode POST und kopiere die generierte Production URL.

Schritt 2: Daten verarbeiten

Ein typischer Workflow sieht so aus:

Webhook → Daten aufbereiten → Ticket erstellen → Respond to Webhook

Schritt 3: Antwort zurücksenden

Der letzte Node muss ein Respond to Webhook-Node sein. Die Antwort wird dem Agenten zurückgegeben:

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

Der Agent kann diese Antwort im Gespräch verwenden: „Ich habe Ticket TK-20260218-042 für Sie erstellt."

Headers und Authentifizierung

Im Feld Headers konfigurierst du HTTP-Header als Schlüssel-Wert-Paare:

Praxisbeispiel: Support-Ticket per n8n

Ein vollständiges Beispiel für einen Agenten, der während des Gesprächs automatisch ein Support-Ticket erstellt:

Parameter: Siehe das JSON-Schema im Abschnitt oben (caller_name, company, issue_summary, priority, callback_number).

Beschreibung:

Verwende dieses Tool, um ein Support-Ticket anzulegen.
Rufe es auf, NACHDEM du das Anliegen vollständig verstanden
und die wichtigsten Daten gesammelt hast.

Wenn erfolgreich: Bestätige dem Anrufer, dass ein Ticket
erstellt wurde und sich jemand meldet.

Wenn fehlgeschlagen: Sage, dass du das Anliegen manuell
weiterleitest.

Tipps und Fehlerbehebung

Best Practices

• Timeout angemessen wählen: 10 Sekunden für die meisten Fälle, bei langsamen APIs auf 20–30 Sekunden erhöhen
• Immer Fehlerfall definieren: Ohne Fehlerfall bleibt der Agent stumm bei API-Problemen
• Wenige, präzise Parameter: Je weniger Parameter, desto zuverlässiger die Extraktion
• Beschreibungen im Schema: Jedes Feld braucht eine description — ohne sie weiß das Modell nicht, was es einfüllen soll
• Im System-Prompt referenzieren: Sage im Gesprächsablauf explizit, wann das Tool aufgerufen werden soll

Häufige Probleme

Im Prompt referenzieren

Neben der Tool-Konfiguration und der Beschreibung im Tool selbst solltest du auch im System-Prompt definieren, wann der Agent den API Request aufrufen soll. Erwähne dabei den genauen Tool-Namen (z. B. create_ticket oder „Auftragsstatus").

Beispiel:

### Wenn der Kunde ein technisches Problem meldet:
1. Höre das Problem vollständig an.
2. Fasse es in eigenen Worten zusammen.
3. Erfrage Name und Rückrufnummer.
4. Erstelle das Support-Ticket über den API Request "create_ticket".
5. Bestätige: "Ich habe ein Ticket für Sie erstellt.
   Unser Team meldet sich zeitnah bei Ihnen."
6. Wenn der API Request fehlschlägt:
   "Leider konnte ich das Ticket gerade nicht anlegen.
   Ich leite Ihr Anliegen manuell weiter."

Mehr Informationen dazu findest du im Prompting-Guide.