Zum Hauptinhalt springen

​
Wie Dynamic Context funktioniert

Profi Dynamic Context lässt dich Kundendaten aus deinen externen APIs einmalig vor jedem Gesprächsstart abrufen. Statt nur auf Kontaktdatensätze zu setzen, können deine Agenten auf Account-Status, Bestellhistorie, Support-Tickets und Geschäftskontext aus deinem Customer-Relationship-Management-(CRM)-System, aus Datenbanken und aus externen Systemen zugreifen. Du kannst außerdem Benutzerdefinierte Aktionen verwenden, um Daten während des Gesprächs abzurufen.
Konfiguriere Dynamic Context im Anrufablauf unter Vor dem Anruf im Agent-Editor. Die zurückgegebenen JSON-Daten stehen direkt als Variablen (z. B. {{ field_name }}) in der greeting und im prompt deines Agents zur Verfügung.
Die Plattform ruft die Context-API einmal auf, bevor das Gespräch beginnt. Die Daten stehen für die Begrüßung und während des gesamten Gesprächs zur Verfügung. Sie werden während des Gesprächs nicht aktualisiert. Das harte Request-Timeout beträgt 30 Sekunden, aber du solltest den Endpunkt so auslegen, dass er in unter 1 Sekunde antwortet.
Kurze Anforderungen:
  • HTTPS-Endpunkt
  • Gültiges JSON-Objekt oder ein Array von Objekten, das zusammengeführt werden kann
  • Kleine Antwort-Payload mit nur den Daten, die das Gespräch braucht
  • Schnelle Antwortzeit; Ziel: unter 1 Sekunde
  • Authentifizierung via Bearer Token, Basic Auth, Custom Header oder keine Authentifizierung

​
So funktioniert es

Request-Flow:
1

Anruf gestartet

Anruf gestartet (Inbound) oder steht kurz vor dem Start (Outbound)
2

Context-API aufgerufen

BEVOR das Gespräch beginnt: Das System sendet eine 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

Die Plattform stellt die Kontextdaten als Template-Variablen bereit
6

Begrüßung gerendert

Die Plattform rendert die Begrüßung (unter Verwendung von Kontextvariablen, falls referenziert)
7

Gespräch beginnt

Das Gespräch beginnt (Kontextvariablen sind verfügbar, wenn sie im Prompt referenziert werden)Der Kontext bleibt während des gesamten Gesprächs statisch (keine Aktualisierung)

Inbound calls

direction: "inbound" mit der contact_number des Anrufers. Suche Kundendaten in deinem CRM.

Outbound calls

direction: "outbound" mit der contact_number, die du anrufst. Hole Kampagnenkontext ab.

Web widget

medium: "web" mit optionaler external_id. Identifiziere Nutzer in deinem System über das web widget.

​
Konfiguration

1

Zu Dynamic Context navigieren

  1. Öffne deinen Agenten im Editor
  2. Klicke auf Anrufablauf
  3. Öffne unter Vor dem Anruf Dynamic Context
2

Endpunkt konfigurieren

Dieser Schritt wird normalerweise von einer technischen Teamkollegin oder einem technischen Teamkollegen erledigt.Endpoint-URL: https://api.company.com/contextAuthentifizierung: Wähle Bearer Token, Basic Auth, Custom Header oder KeineDie Anfrage enthält: agent_uuid, direction, agent_number, contact_number (und external_id für Web-Widget)
3

Testen

Speichere die Dynamic-Context-Einstellungen und nutze dann Test, um zu prüfen, ob der gespeicherte Endpunkt und die Authentifizierung korrekt antworten.
4

Speichern

Aktivieren und speichern. Die Plattform holt den Kontext vor jedem Gespräch.

​
Request- und Response-Format

​
Request-Payload (POST-Request)

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 Agents, 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 nutzt contact_number oder external_id, um den Kunden in deinem CRM/Datenbank nachzuschlagen, und gibt dann relevante Account-Daten, Bestellhistorie, Tickets usw. zurück. agent_uuid kann verwendet werden, um Antworten bei Bedarf agentenspezifisch anzupassen.

​
Was du zurückgibst (JSON-Response)

{
  "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-Objekt oder ein Array von Objekten, das zusammengeführt werden kann
  • Halte die Antwort klein und fokussiere auf Felder, die der Agent braucht
  • Gib nur notwendige Felder zurück (das hält die Antwort schnell)
  • Gehe mit fehlenden Daten sauber um (gib null zurück oder lasse Felder weg)
Wie Variablen abgerufen werden: Alle Top-Level-Keys in deiner JSON-Response werden zu Template-Variablen. Wenn du {"account": {"tier": "VIP"}} zurückgibst, rufst du es als {{ account.tier }} ab, nicht als {{ context.account.tier }}.

​
Kontextvariablen verwenden

Alle von deiner API zurückgegebenen Daten stehen direkt als Top-Level-Variablen in der Begrüßung und im Prompt deines Agents zur Verfügung. Felder abrufen: 
Account Tier: {{ account.tier }}
→ "VIP"

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

Number of Tickets: {{ support_tickets|length }}
→ 1
Beispiel-Begrüßung mit Kontext: 
Thanks for calling! I see you're a {{ account.tier }} customer with us.
How can I help you today?
Beispiel-Prompt mit Kontext: 
You are helping a {{ account.tier }} customer since {{ account.created_date }}.

{% if support_tickets|length > 0 %}
IMPORTANT: Customer has {{ support_tickets|length }} open ticket(s):
{% for ticket in support_tickets %}
- Ticket #{{ ticket.ticket_id }}: {{ ticket.subject }} ({{ ticket.status }})
{% endfor %}

Ask if they're calling about ticket #{{ support_tickets[0].ticket_id }}.
{% endif %}

{% if recent_orders|length > 0 %}
Recent order #{{ recent_orders[0].order_id }} is {{ recent_orders[0].status }}.
{% if recent_orders[0].tracking %}
Tracking: {{ recent_orders[0].tracking }}
{% endif %}
{% endif %}

Account Status: {{ account.status | default("active") }}
Nutze den Filter | default("value"), um Fallbacks bereitzustellen, wenn Daten fehlen. Siehe Begrüßungen und Prompt für weitere Template-Syntax und Verwendungsbeispiele.

​
Authentifizierung

​
Bearer Token (Empfohlen)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Verwende dies für JSON Web Token (JWT), OAuth (Open Authorization) 2.0 Access Tokens oder moderne API-Keys.

​
Benutzerdefinierter Header

X-API-Key: sk-abc123def456...
Benutzerdefinierter Header-Name mit einem Credential-Wert, z. B. einem API-Key.

​
Basic Auth

Authorization: Basic YXBpX3VzZXI6cGFzc3dvcmQ=
Benutzername/Passwort, Base64-kodiert.

​
Keine Authentifizierung

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

​
Beispiel-Anwendungsfall

Kundensupport mit vollständigem Kontext Szenario: Ein Support-Agent braucht eine vollständige Kundenansicht, bevor das Gespräch beginnt. 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"
      }
    ]
  }
}
Agent-Prompt: 
You're helping {{ customer.name }}, a {{ customer.tier }} customer
since {{ customer.since }}.

{% if support.open_tickets|length > 0 %}
Customer has an open {{ support.open_tickets[0].priority }} priority ticket
about "{{ support.open_tickets[0].subject }}".

Start by asking: "I see you have a ticket open about
{{ support.open_tickets[0].subject }}. Is that what you're calling about today?"
{% endif %}

Account: {{ account.subscription }}, renews {{ account.renewal_date }}
Ergebnis: Der Agent kennt das offene Ticket bereits vor dem Gesprächsstart, was eine personalisierte Begrüßung und ein informiertes Gespräch ermöglicht.

​
Best Practices

  • Ziel: Antwortzeit unter 1 Sekunde
  • Häufig abgerufene Daten cachen (TTL 5–10 Minuten)
  • Nur Felder zurückgeben, die im Prompt verwendet werden
  • Datenbankindizes auf Lookup-Felder setzen (contact_number, external_id oder interne Kunden-IDs)
  • | default("value")-Filter im Prompt verwenden
  • null für fehlende Felder zurückgeben (keinen Fehler werfen)
  • Mit Kontakten testen, die nur minimale Daten haben
{# Sicher - liefert Fallback #}
Tier: {{ account.tier | default("Standard") }}

{# Sicherer - prüft Existenz #}
{% if support_tickets and support_tickets|length > 0 %}
  Has open tickets
{% endif %}
  • Keine Sozialversicherungsnummern, Kreditkarten oder Passwörter zurückgeben
  • Nur HTTPS verwenden
  • Authentifizierung implementieren (Bearer Token empfohlen)
  • Nur notwendige Felder zurückgeben (z. B. letzte 4 Stellen der Kontonummer, nicht die vollständige)
  • Zugriff für Audit-Trails protokollieren
  1. Test mit echten Kundendaten verwenden
  2. Edge Cases testen (neuer Kunde, VIP, gesperrtes Konto)
  3. Prüfen, ob dein Prompt fehlende Felder sauber behandelt
  4. Mit kleinem Traffic-Anteil pilotieren, bevor du vollständig ausrollst

​
Fehlerbehebung

  • Prüfen, ob die Credentials korrekt sind
  • Sicherstellen, dass der Authentifizierungstyp zu deiner API passt (Bearer Token, Basic Auth oder Custom Header)
  • Mit denselben Credentials in Postman testen
  • Prüfen, ob das Token abgelaufen ist
  • Test verwenden, um zu prüfen, ob der Endpunkt antwortet
  • JSON-Struktur gegen die abgerufenen Felder prüfen
  • Sicherstellen, dass der Dynamic-Context-Toggle eingeschaltet ist
  • | default("fallback") für fehlende Felder verwenden
  • Datenbankindizes hinzufügen
  • Caching implementieren
  • Nur notwendige Felder zurückgeben
  • Datenbankabfragen optimieren
  • Netzwerklatenz zur API prüfen
  • Parameter in Test prüfen
  • Sicherstellen, dass Template-Variablen korrekt aufgelöst werden: {{ account.tier }}
  • Prüfen, ob Cache-Keys die Kundenkennung enthalten
  • Mit bekanntem Kunden testen, um zu bestätigen, dass die Daten übereinstimmen

​
Nächste Schritte

Begrüßungen

Kontextvariablen verwenden, um die Begrüßung des Agenten zu personalisieren

Prompt

Kontextvariablen im Prompt mit Jinja-Templating verwenden

Template-Syntax

Template-Syntax für dynamische Prompts meistern

Benutzerdefinierte Aktion

Tools erstellen, die Kontextdaten während des Gesprächs verwenden