Variablen pro Anruf

Personalisieren Sie einen gespeicherten Agenten für jeden Anruf, ohne seinen bereitgestellten Prompt, seine Tools oder Einstellungen zu ändern.

Platzieren Sie Platzhalter im Prompt Ihres gespeicherten Agenten und übergeben Sie beim Starten eines Anrufs ein variables-Objekt. Die gespeicherte Konfiguration und der Versionsverlauf bleiben unverändert. ThunderPhone rendert den Text, bevor die Anrufkonfiguration an die Sprach-Runtime gesendet wird.

Wenn keine Werte benötigt werden, lassen Sie variables weg und senden Sie nicht null (wird mit 400 abgelehnt).

Platzhalter und Standardwerte

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Namen unterscheiden zwischen Groß- und Kleinschreibung und folgen [A-Za-z_][A-Za-z0-9_]*. Leerzeichen um den Namen sind zulässig; Leerzeichen nach | sind Teil des Standardwerts und bleiben erhalten. {{name|Friend}} verwendet Friend, wenn name fehlt oder null ist; eine leere Zeichenfolge ist ein ausdrücklich übergebener Wert. Fehlende Werte ohne Standardwert werden zu leeren Zeichenfolgen, und ihre Namen erscheinen in unresolved_variables. Text zwischen doppelten geschweiften Klammern, der kein gültiger Platzhalter ist, wird entfernt. Text in doppelten geschweiften Klammern innerhalb jedes übergebenen Werts wird unabhängig entfernt; ein Wert kann weder umgebenden Prompt-Text noch einen anderen Wert entfernen. Nicht übereinstimmende Trennzeichen mit doppelten geschweiften Klammern werden ebenfalls entfernt. JSON-Beispiele in Prompts dürfen nicht {{ verwenden. Werte sind Klartext und werden weder als Code ausgewertet noch rekursiv als Vorlagen erweitert.

Variablen können auch in Bestätigungs-Prompts, ausgehenden Voicemail-Nachrichten und dem Text der Einwilligungsansage erscheinen, wenn dieses Feld für einen Anruf gesendet wird. Der Agent hat kein separates Feld first_message: Platzieren Sie seine einleitenden Anweisungen im Prompt. Die vorhandenen Voicemail-Platzhalter {agent_name} und {org_name} funktionieren weiterhin.

Werte können Zeichenfolgen, Zahlen, boolesche Werte oder null sein; boolesche Werte werden als true und false gerendert. Unicode-Steuerzeichen (Cc) außer Zeilenumbruch (\n), Tabulator (\t) und Wagenrücklauf (\r), alle Formatzeichen (Cf) und Surrogat-Codepunkte (Cs) werden entfernt; \r\n wird zu \n normalisiert. Jeder Wert ist beim Rendern auf 2.000 Zeichen begrenzt. Übergebene Zeichenfolgen werden auch vor der Speicherung bereinigt und gekürzt. Das ursprüngliche Objekt muss in 32 KB UTF-8-JSON passen; größere Objekte erhalten bei Anruf-/Sitzungsanfragen 400, während Kampagnenimporte ungültige Zeilen einzeln melden. Arrays und verschachtelte Objekte werden nicht als Werte akzeptiert. Nicht übereinstimmende Metadatenschlüssel (beispielsweise ein CSV-Header mit einem Leerzeichen) werden beibehalten und zurückgegeben, können jedoch nicht über einen Platzhalter referenziert werden.

Herkunft der Werte

Outbound-API

Senden Sie variables zusammen mit agent_id in POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Dies funktioniert auch mit dem Standard-Sprachagenten der Telefonnummer für ausgehende Anrufe oder mit einer Inline-config.prompt. Ein Idempotenzschlüssel kann nicht mit unterschiedlichen Variablen erneut verwendet werden.

Kampagnen-CSV

CSV-Spalten, die keine Telefonnummern enthalten, werden bereits als Kontaktvariablen gespeichert. Jeder Wählvorgang verwendet sie jetzt automatisch. Verwenden Sie Überschriften wie name, account_id und appointment_slot, damit sie Ihren Platzhaltern entsprechen. Die bestehende Namenszuordnung kann Spalten für Vor- und Nachnamen in der Variablen name zusammenführen.

Webhook für dynamische Konfiguration

Geben Sie im blockierenden Konfigurations-Webhook-Pfad einen gespeicherten Agenten in Ihrer Organisation sowie alle Werte pro Anruf zurück:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Die Schlüssel der Antwort überschreiben Variablen auf Anfrageebene, während andere Anfrage-Schlüssel erhalten bleiben. Ein Antwortwert von null wählt den Standardwert des Platzhalters aus. Das zusammengeführte Objekt darf ebenfalls nicht größer als 32 KB sein. Antworten für gespeicherte Agenten akzeptieren nur agent_id und variables; geben Sie eine Inline-Konfiguration zurück, wenn Sie den Prompt oder Einstellungen ersetzen müssen. Eine Antwort mit prompt verwendet immer die Inline-Konfiguration: Jeder agent_id in dieser Antwort wird ignoriert, einschließlich null oder nicht ganzzahliger Metadaten. Der Inline-Prompt muss weiterhin die normale Validierung bestehen. Inline-Webhook-Antworten können ebenfalls variables enthalten. Webhook-Antworten für gespeicherte Agenten verwenden die bereitgestellte A/B-Aufteilung des Agenten sowohl bei Telefon- als auch bei Widget-Anrufen; Variablen werden nach der Variantenauswahl gerendert. Verwenden Sie bei eingehenden Telefonanrufen eine Nummer ohne zugewiesenen Sprachagenten für eingehende Anrufe und konfigurieren Sie den Webhook der Telefonnummer oder Organisation; Widget-Schlüssel verwenden mode="webhook". Eingehende Benachrichtigungen des Endpoint-Systems liefern keine blockierenden Konfigurationsantworten.

POST /v1/widget/session akzeptiert ein variables-Objekt auf oberster Ebene. Sein veröffentlichbarer Schlüssel wählt den gespeicherten Agenten aus. Schlüssel im Webhook-Modus leiten diese Werte an den Konfigurations-Webhook weiter und führen die Antwort wie oben beschrieben zusammen. Vom Browser bereitgestellte Widget-/Realtime-variables werden vom Client gesteuert, nach der oben beschriebenen Validierung und Bereinigung von Zeichenfolgen unverändert in web.incoming weitergeleitet und in Completion-Webhooks sowie im Anrufverlauf wiedergegeben. Behandeln Sie sie nicht als vertrauenswürdige Identitäts- oder Autorisierungsdaten.

POST /v1/realtime/sessions akzeptiert variables zusammen mit agent_id (oder Inline-config). Dies sind API-Felder für die Sitzungserstellung. Die Realtime-WebSocket-Bridge leitet keine Variables-Option weiter; übergeben Sie sie direkt an die API für die Sitzungserstellung. Widget-Clients müssen variables in die gesendete Sitzungsnutzlast aufnehmen; die SDK-Weiterleitung ist nicht Teil dieser API-Änderung. Mikrofon- und simulierte Testanrufe im Builder lösen Standardwerte und fehlende Platzhalter auf, verfügen jedoch über keine Eingabe für Variablen pro Anruf.

Nach dem Anruf zurückgegebene Werte

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete und web.complete enthalten die final zusammengeführten variables und unresolved_variables. Legacy-Completion-Nutzlasten, die data.history enthalten, enthalten sie ebenfalls:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

Speichern Sie Ihre CRM- oder Aufgabenkennung im Variablenobjekt, um den abgeschlossenen Anruf wieder seinem Quelldatensatz zuzuordnen. Diese Felder werden mit dem Anrufdatensatz gespeichert; senden Sie nur Informationen, die Sie im Anrufverlauf und in Webhooks aufbewahren dürfen.

Kompatibilität mit bestehenden Prompts

Die Darstellung gilt auch für bestehende Prompts gespeicherter Agenten und A/B-Varianten, für Inline-Konfigurationen für Outbound- und Echtzeit-Anrufe sowie für Prompts, die von Konfigurations-Webhooks zurückgegeben werden. Unbekannte Platzhalter {{name}} werden zu leerem Text, auch wenn keine variables bereitgestellt werden. Prüfen Sie bestehende Prompts vor dem Rollout, einschließlich extern bereitgestellter Inline-/Webhook-Prompts, die ThunderPhone nicht inventarisieren kann. Builder-Mikrofon- und Simulationsanrufe verwenden dasselbe Standard-/Leer-Verhalten.