Zum Hauptinhalt springen

​
Überblick

Dynamischer Kontext ermöglicht es dir, Kundendaten aus deinen externen APIs einmal, vor Beginn jedes Gesprächs abzurufen. Anstatt sich nur auf Kontaktdatensätze zu verlassen, können deine Agenten auf Kontostatus, Bestellhistorie, Support-Tickets und Geschäftskontext aus deinem CRM, Datenbanken und Backend-Systemen zugreifen.
Dynamischer Kontext wird konfiguriert unter Agenteneinstellungen → Operationen → Dynamischer Kontext. Die zurückgegebenen JSON-Daten sind direkt als Variablen verfügbar (z.B. {{ field_name }}) in der Begrüßung und den Anweisungen deines Agenten.
Die Kontext-API wird einmal vor Gesprächsbeginn aufgerufen. Die Daten sind für das Rendern der Begrüßung und während des gesamten Gesprächs verfügbar. Sie werden während des Gesprächs nicht aktualisiert. Halte deinen Endpunkt schnell (<1s Antwortzeit) und gib nur für das Gespräch benötigte Daten zurück.
Schnelle Anforderungen:
  • HTTPS-Endpunkt
  • JSON-Antwort unter 32 KB
  • Antwortzeit unter 1 Sekunde (idealerweise)
  • Authentifizierung über Bearer-Token, API-Schlüssel oder Basic Auth

​
Funktionsweise

Anforderungsablauf:
1

Anruf initiiert

Anruf initiiert (eingehend) oder kurz vor dem Start (ausgehend)
2

Kontext-API aufgerufen

VOR Gesprächsbeginn: System sendet POST-Anfrage an deinen Endpunkt
3

deine Systeme abfragen

deine API fragt CRM/Datenbank nach Kundendaten ab
4

JSON zurückgeben

deine API gibt JSON mit Kontextdaten zurück
5

Kontext verfügbar

Kontextdaten werden als Template-Variablen verfügbar gemacht
6

Begrüßung gerendert

Begrüßung gerendert (verwendet Kontextvariablen, falls in Begrüßung referenziert)
7

Gespräch beginnt

Gespräch beginnt (Kontextvariablen verfügbar, falls in Anweisungen referenziert)Kontext bleibt während des gesamten Gesprächs statisch (keine Aktualisierung)

Eingehende Anrufe

direction: "inbound" mit contact_number des Anrufers. Kundendaten im CRM nachschlagen.

Ausgehende Anrufe

direction: "outbound" mit contact_number, die du anrufst. Kampagnenkontext abrufen.

Web-Widget

medium: "web" mit optionaler external_id. Benutzer in deinem System identifizieren.

​
Konfiguration

1

Zu Dynamischer Kontext navigieren

  1. Öffne deine Agenteneinstellungen
  2. Klicke auf die Navigationsgruppe Operationen (in der linken Seitenleiste)
  3. Wähle Dynamischer Kontext aus den Abschnitten
2

Endpunkt konfigurieren

Endpunkt-URL: https://api.company.com/contextAuthentifizierung: Wähle Bearer-Token, Basic, API-Schlüssel oder KeineDie Anfrage enthält: agent_uuid, direction, agent_number, contact_number (und external_id für Web-Widget)
3

Testen

Verwende Anfrage testen, um zu überprüfen, ob dein Endpunkt korrekt antwortet
4

Speichern

Aktivieren und speichern. Kontext wird vor jedem Gespräch abgerufen.

​
Anforderungs- & Antwortformat

​
Was wir senden (POST-Anfrage)

POST https://api.company.com/context
Authorization: Bearer your_api_token
Content-Type: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...
X-Agent-UUID: 550e8400-e29b-41d4-a716-446655440000
X-Agent-Number: +15551234000
X-Contact-Number: +15551234567
X-Direction: inbound
X-Medium: phone
X-Room-SID: RM_abc123

{
  "agent_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "direction": "inbound",
  "agent_number": "+15551234000",
  "contact_number": "+15551234567"
}
Body-Parameter:
  • agent_uuid (String, immer enthalten) - Die UUID des Agenten, der den Anruf bearbeitet
  • direction (String, immer enthalten) - “inbound” oder “outbound”
  • agent_number (String, optional) - Die Telefonnummer, die der Agent verwendet
  • contact_number (String, optional) - Die Telefonnummer des Kunden
  • external_id (String/Int, optional) - Nur für Web-Widget-Anrufe, falls von deiner Integration bereitgestellt
Zusätzliche Header:
  • X-Agent-UUID, X-Agent-Number, X-Contact-Number, X-Direction, X-Medium (phone/web)
  • X-Room-SID - Eindeutige Kennung für diese Gesprächssitzung
  • X-External-ID - Nur für Web-Widget-Anrufe
Typische Verwendung: Dein Endpunkt verwendet contact_number oder external_id, um den Kunden in deinem CRM/deiner Datenbank nachzuschlagen und gibt dann relevante Kontodaten, Bestellhistorie, Tickets usw. zurück. Die agent_uuid kann verwendet werden, um Antworten pro Agent anzupassen, falls erforderlich.

​
Was du zurückgeben (JSON-Antwort)

{
  "account": {
    "customer_id": "12345",
    "tier": "VIP",
    "status": "active",
    "created_date": "2022-03-15"
  },
  "recent_orders": [
    {
      "order_id": "ORD-789",
      "status": "shipped",
      "tracking": "1Z999AA1234567890"
    }
  ],
  "support_tickets": [
    {
      "ticket_id": "TKT-456",
      "status": "open",
      "subject": "Billing question"
    }
  ]
}
Anforderungen:
  • Gültiges JSON-Format
  • Unter 32 KB
  • Nur notwendige Felder zurückgeben (hält Antwort schnell)
  • Fehlende Daten elegant behandeln (null zurückgeben oder Felder weglassen)
Wie auf Variablen zugegriffen wird: Alle Top-Level-Schlüssel in deiner JSON-Antwort werden zu Template-Variablen. Wenn du {"account": {"tier": "VIP"}} zurückgibst, greifst du darauf als {{ account.tier }} zu, nicht als {{ context.account.tier }}.

​
Kontextvariablen verwenden

Alle zurückgegebenen Daten aus deiner API sind direkt als Top-Level-Variablen in der Begrüßung und den Anweisungen deines Agenten verfügbar. Zugriff auf Felder: 
Konto-Stufe: {{ account.tier }}
→ "VIP"

Bestellstatus: {{ recent_orders[0].status }}
→ "shipped"

Anzahl der Tickets: {{ support_tickets|length }}
→ 1
Beispiel-Begrüßung mit Kontext: 
Danke für Ihren Anruf! Ich sehe, Sie sind ein {{ account.tier }}-Kunde bei uns.
Wie kann ich Ihnen heute helfen?
Beispiel-Anweisungen mit Kontext: 
Sie helfen einem {{ account.tier }}-Kunden seit {{ account.created_date }}.

{% if support_tickets|length > 0 %}
WICHTIG: Kunde hat {{ support_tickets|length }} offene(s) Ticket(s):
{% for ticket in support_tickets %}
- Ticket #{{ ticket.ticket_id }}: {{ ticket.subject }} ({{ ticket.status }})
{% endfor %}

Frage, ob sie wegen Ticket #{{ support_tickets[0].ticket_id }} anrufen.
{% endif %}

{% if recent_orders|length > 0 %}
Letzte Bestellung #{{ recent_orders[0].order_id }} ist {{ recent_orders[0].status }}.
{% if recent_orders[0].tracking %}
Sendungsverfolgung: {{ recent_orders[0].tracking }}
{% endif %}
{% endif %}

Kontostatus: {{ account.status | default("active") }}
Verwende den | default("value")-Filter, um Fallbacks bereitzustellen, wenn Daten fehlen. Siehe Begrüßung und Anweisungen für weitere Templating-Syntax und Verwendungsbeispiele.

​
Authentifizierung

​
Bearer-Token (Empfohlen)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Verwende für JWT, OAuth 2.0 Zugriffstoken oder moderne API-Schlüssel.

​
API-Schlüssel (Header)

X-API-Key: sk-abc123def456...
Benutzerdefinierter Header-Name mit deinem API-Schlüssel.

​
Basic Auth

Authorization: Basic YXBpX3VzZXI6cGFzc3dvcmQ=
Benutzername/Passwort, base64-codiert.

​
Keine

Keine Authentifizierung (nur für interne/private Netzwerke).
Verwende immer HTTPS.

​
Beispiel-Anwendungsfall

Kundensupport mit vollständigem Kontext Szenario: Support-Agent benötigt vollständige Kundenübersicht vor Gesprächsbeginn. deine API gibt zurück: 
{
  "customer": {
    "name": "John Smith",
    "tier": "Premium",
    "since": "2022-01-15"
  },
  "account": {
    "status": "active",
    "subscription": "Pro Plan",
    "renewal_date": "2025-12-01"
  },
  "support": {
    "open_tickets": [
      {
        "id": "TKT-789",
        "subject": "Can't export reports",
        "priority": "high"
      }
    ]
  }
}
Agentenanweisungen: 
Sie helfen {{ customer.name }}, einem {{ customer.tier }}-Kunden
seit {{ customer.since }}.

{% if support.open_tickets|length > 0 %}
Kunde hat ein offenes {{ support.open_tickets[0].priority }}-Priorität-Ticket
über "{{ support.open_tickets[0].subject }}".

Beginne mit der Frage: "Ich sehe, Sie haben ein offenes Ticket über
{{ support.open_tickets[0].subject }}. Rufen Sie deswegen heute an?"
{% endif %}

Konto: {{ account.subscription }}, erneuert {{ account.renewal_date }}
Ergebnis: Agent weiß vor Gesprächsbeginn über das offene Ticket Bescheid, was eine personalisierte Begrüßung und ein informiertes Gespräch während des gesamten Verlaufs ermöglicht.

​
Best Practices

  • Antwortzeit unter 1 Sekunde anstreben
  • Häufig abgerufene Daten zwischenspeichern (5-10 Minuten TTL)
  • Nur Felder zurückgeben, die du in Anweisungen verwenden
  • Datenbankindizes auf Lookup-Feldern verwenden (contact_number, external_id oder deine internen Kunden-IDs)
  • | default("value")-Filter in Anweisungen verwenden
  • Null für fehlende Felder zurückgeben (nicht fehlschlagen)
  • Mit Kontakten testen, die minimale Daten haben
{# Sicher - bietet Fallback #}
Stufe: {{ account.tier | default("Standard") }}

{# Sicherer - prüft Existenz #}
{% if support_tickets and support_tickets|length > 0 %}
  Hat offene Tickets
{% endif %}
  • Gib keine Sozialversicherungsnummern, Kreditkarten, Passwörter zurück
  • Nur HTTPS verwenden
  • Authentifizierung implementieren (Bearer-Token empfohlen)
  • Nur notwendige Felder zurückgeben (z.B. letzte 4 der Kontonummer, nicht vollständig)
  • Zugriff für Audit-Trails protokollieren
  1. Verwende Anfrage testen-Modal mit echten Kundendaten
  2. Teste Grenzfälle (neuer Kunde, VIP, gesperrtes Konto)
  3. Überprüfe, ob Anweisungen fehlende Felder elegant behandeln
  4. Pilotiere mit kleinem Prozentsatz des Traffics vor vollständigem Rollout

​
Fehlerbehebung

  • Überprüfe, ob Anmeldedaten korrekt sind
  • Prüfe, ob Authentifizierungstyp mit deiner API übereinstimmt (Bearer vs. Basic vs. API-Schlüssel)
  • Teste mit denselben Anmeldedaten in Postman
  • Prüfe, ob Token abgelaufen ist
  • Verwende Anfrage testen, um zu überprüfen, ob Endpunkt antwortet
  • Überprüfe, ob JSON-Struktur mit dem übereinstimmt, worauf du zugreifst
  • Überprüfe, ob Dynamischer Kontext-Schalter EIN ist
  • Verwende | default("fallback") für fehlende Felder
  • Datenbankindizes hinzufügen
  • Caching implementieren
  • Nur notwendige Felder zurückgeben
  • Datenbankabfragen optimieren
  • Netzwerklatenz zu deiner API prüfen
  • Überprüfe Parameter im Anfrage testen-Modal
  • Überprüfe, ob Template-Variablen korrekt aufgelöst werden: {{ account.tier }}
  • Stelle sicher, dass Cache-Schlüssel Kundenkennung enthalten
  • Teste mit bekanntem Kunden, um zu bestätigen, dass Daten übereinstimmen

​
Nächste Schritte

Begrüßung

Verwende Kontextvariablen, um die Begrüßung deines Agenten zu personalisieren

Anweisungen

Erfahre, wie du Kontextvariablen mit Jinja-Templating verwendest

Variablen & Dynamischer Inhalt

Templating-Syntax für dynamische Prompts meistern

Benutzerdefinierte API-Aktionen

Erstelle Aktionen, die während Gesprächen Kontextdaten verwenden