Parameter

Parameter definieren, referenzieren, festlegen und abrufen

Es gibt vier allgemeine Arten der Verwendung von Parametern:

• Während der Entwicklung definieren: Während der Entwicklung verwenden Sie die Konsole oder die API, um Parameter zu definieren. Sie können beispielsweise einen Intent-Parameter definieren und in einer Trainingsformulierung verwenden, um die Endnutzereingabe zu bestimmen, die extrahiert werden soll.
• Bei der Entwicklung referenzieren: Parameterverweise sind Variablen, die zur Laufzeit extrahierte Parameterwerte enthalten. Während der Entwicklung verwenden Sie die Konsole oder die API, um auf Parameter in verschiedenen Datentypen zu verweisen. Sie können beispielsweise auf einen Sitzungsparameter in einer statischen Auftragserfüllungsantwort für eine Route verweisen.
• Zur Laufzeit festgelegt: Zur Laufzeit können der Dienst für Konversations-KI (Dialogflow CX), der Dienst, der die API aufruft, und Ihr Webhook-Dienst alle Parameterwerte festlegen. Beispiel: Der Dienst „Conversational Agents“ (Dialogflow CX) legt den Wert eines Intent-Parameters fest, wenn eine Endnutzereingabe dem Intent entspricht und die Eingabe Parameterdaten enthält.
• Zur Laufzeit abrufen: Zur Laufzeit verweist Ihr Parameter auf die festgelegten Parameterwerte. Sie können die Parameterwerte mit der API oder einem Webhook abrufen. Wenn beispielsweise ein Intent zugeordnet und Ihr Webhook aufgerufen wird, empfängt Ihr Webhook-Dienst die Parameterwerte für den Intent.

Parameter benennen

Für die Benennung von Parametern gelten die folgenden Regeln:

• Verwenden Sie die folgenden Zeichen: [A-Z], [a-z], [0-9], ., -, _
• Bei Parameternamen wird nicht zwischen Groß- und Kleinschreibung unterschieden. Daher behandelt Conversational Agents (Dialogflow CX) Apple und apple als denselben Parameter. Der Webhook und der API-Clientcode sollten auch Parameternamen als nicht Groß- und Kleinschreibung behandeln, da es für Parameternamen, die von Conversational Agents (Dialogflow CX) zurückgegeben werden, keine Garantie gibt.
• Wenn Sie Parameter mit derselben ID oder demselben Anzeigenamen in verschiedenen Intents oder Formularen erstellen, müssen der Entitätstyp und andere Einstellungen für alle Definitionen gleich sein. Wenn sich der Entitätstyp oder andere Parametereinstellungen unterscheiden, verwenden Sie für jede Definition eine eindeutige Parameter-ID oder einen eindeutigen Anzeigenamen.

Parameterwerttypen

Parameterwerte unterstützen mehrere Werttypen. Im Abschnitt Sitzungen unten wird beschrieben, wie Sie auf die einzelnen Parameterwerttypen verweisen. Die folgenden Typen werden unterstützt:

Leere Strings und Nullwerte als Parameter

Sie können Stringparameterwerte auf "" festlegen, wodurch der Parameter auf den leeren String gesetzt wird.

Sie können jeden Parameterwert auf null setzen, was bedeutet, dass der Parameter nicht festgelegt wurde.

Ursprüngliche Parameterwerte

Wird einer bestimmten Entität während der Laufzeit ein Text zugeordnet, wird dieser oft in einen Wert aufgelöst, der eine einfachere Verarbeitung erlaubt. Beispielsweise kann das Wort „Äpfel“ in der Endnutzereingabe für eine Obstentität als „Apfel“ aufgelöst werden.

Alle Werttypen für Intent-Parameterverweise können entweder auf den ursprünglichen oder den aufgelösten Wert verweisen.

Nur zusammengesetzte Werttypen für Sitzungsparameterreferenzen können auf den ursprünglichen Wert verweisen.

Intent-Parameter

Intents verwenden Parameter, um beim Abgleich von Intents von Endnutzern angegebene Daten zu extrahieren. Zum Definieren von Intent-Parametern werden folgende Daten verwendet:

• Name (auch als ID oder Anzeigename bezeichnet): Ein Name zur Bezeichnung des Parameters.
• Entitätstyp: der Entitätstyp, der dem Parameter zugeordnet ist
• Ist-Liste: Wenn "true", wird der Parameter als Liste von Werten behandelt.
• Im Log entfernen: Wenn der Wert "true" ist, werden vom Endnutzer bereitgestellte Parameterdaten entfernt.

Intent-Parameter definieren

Intent-Parameter werden während der Erstellung definiert, wenn Intent-Daten erstellt oder Trainingsformulierungen annotiert werden.

Intent-Parameter referenzieren

Intent-Parameterverweise können in statischen Antwortnachrichten der Auftragsausführung von Intent-Routen verwendet werden.

Sie können entweder auf den ursprünglichen Wert oder den aufgelösten Wert verweisen.

Verwenden Sie eines der folgenden Formate, um für den aktuell zugeordneten Intent auf einen Parameter zu verweisen:

$intent.params.parameter-id.original
$intent.params.parameter-id.resolved

Wenn die Parameter-ID beispielsweise date lautet, können Sie auf den aufgelösten Wert als $intent.params.date.resolved verweisen.

Intent-Parameter festlegen

Wenn eine Endnutzereingabe zur Laufzeit einem Intent zugeordnet wird, wird jeder von einer Anmerkung verwendete Parameter für die zugehörige Trainingsformulierung von Conversational Agents (Dialogflow CX) festgelegt.

Die Auftragsausführung für eine Intent-Route kann mit einer Voreinstellung für den Auftragsausführungsparameter einen Intent-Parameterwert zur Laufzeit festlegen.

Intent-Parameter abrufen

Während der Unterhaltungsrunde, in der ein Intent zugeordnet wird, kann Ihr Code auf die Werte des Intent-Parameters zugreifen.

Interaktionen mit der API geben Intent-Parameterwerte zurück. Weitere Informationen finden Sie im Feld queryResult.parameters der Methode detectIntent für den Typ Session. Zur API-Referenz-Sitzung

Die empfangenden Intent-Parameterwerte von Webhook. Weitere Informationen finden Sie in der Webhook-Anfrage im Feld intentInfo.parameters.

Formularparameter

Für jede Seite können Sie ein Formular definieren. Dies ist eine Liste von Parametern, die vom Endnutzer für die Seite erfasst werden sollen. Der Agent interagiert mit dem Endnutzer mehrere Unterhaltungsrunden lang, bis er alle erforderlichen Formularparameter, auch Seitenparameter genannt, erfasst hat. Der Agent erfasst diese Parameter in der auf der Seite definierten Reihenfolge. Für jeden Formularparameter geben Sie auch Aufforderungen an, mit denen der Agent diese Informationen vom Endnutzer anfordert. Dieser Vorgang wird als Ausfüllen von Formularen bezeichnet.

Sie können beispielsweise ein Formular erstellen, in dem der Name und die Telefonnummer des Endnutzers für eine Collect Customer Info-Seite erfasst werden.

Folgende Daten werden verwendet, um Formularparameter zu definieren:

Formularparameter definieren und verwalten

Formularparameter werden bei der Erstellung einer Seite zur Entwurfszeit definiert.

Um die Reihenfolge der Formularparameter mit der Konsole zu ändern, klicken Sie auf der Seite auf den Abschnitt Parameter und ziehen Sie die Parameterzeilen per Drag-and-drop in die Parametertabelle.

Wenn Sie einen Formularparameter löschen möchten, klicken Sie auf der Seite auf den Abschnittstitel Parameter, bewegen Sie den Mauszeiger auf einen Parameter und klicken Sie dann auf die Schaltfläche „Löschen“ delete.

Formularparameter referenzieren

Formularparameterreferenzen werden nicht direkt verwendet. Sie können nur den Ausfüllstatus einzelner Formularparameter oder des gesamten Formulars prüfen. Sie können diese Formularstatusreferenzen in einer Bedingungsanforderung einer Bedingungsroute verwenden.

Verwenden Sie die folgende Bedingung, um zu prüfen, ob das vollständige Formular der aktuellen Seite ausgefüllt ist:

$page.params.status = "FINAL"

Mit der folgenden Bedingung können Sie prüfen, ob ein bestimmter Formularparameter in der letzten Runde ausgefüllt wurde:

$page.params.parameter-id.status = "UPDATED"

Formularparameter festlegen

Formularparameterwerte können auf verschiedene Arten festgelegt werden. In den folgenden Unterabschnitten werden die einzelnen Mechanismen zum Festlegen von Formularparameterwerten beschrieben.

Standardparameterwerte

Sie können Standardwerte für optionale Formularparameter angeben. Wenn das Ausfüllen des Formulars beginnt, werden alle nicht festgelegten optionalen Formularparameter auf ihre Standardwerte gesetzt. Diese Werte können mit einigen der folgenden Mechanismen initialisiert oder überschrieben werden.

Wenn ein Parameter erforderlich ist, wird sein Standardwert ignoriert.

Formular ausfüllen

Konversations-Agenten (Dialogflow CX) legen automatisch Parameterwerte fest, die der Endnutzer während des Ausfüllens eines Formulars angegeben hat. Der Agent erfasst die erforderlichen Parameter in der auf der Seite definierten Reihenfolge. Der Agent fordert den Endnutzer auf, die erforderlichen Werte mithilfe der anfänglichen Eingabeauftragsausführung für jeden erforderlichen Parameter einzugeben. Optionale Parameter lösen keine Aufforderungen aus.

Wenn ein erforderlicher Parameterwert nicht vom Endnutzer nach einer Agent-Eingabeaufforderung bereitgestellt wird, wird die erste Eingabeaufforderung wiederholt, es sei denn, in den Handlern für erneute Eingabeaufforderungen ist ein anderes Verhalten definiert. Wenn mehrere anfängliche Texteingaben definiert sind, entspricht das Agent-Verhalten dem Verhalten von Antworttexten der Auftragsausführung.

Weitergabe von Intent- und Sitzungsparametern

Wenn ein Parameter eines beliebigen Typs zur Laufzeit festgelegt wird, wird er in die Sitzung geschrieben und wird zu einem Sitzungsparameter.

Wenn eine Seite erstmalig aktiv wird und während ihres aktiven Zeitraums, wird jeder Formularparameter mit demselben Namen wie ein Sitzungsparameter automatisch auf den Sitzungsparameterwert gesetzt.

Dies kann mit einem zugeordneten Intent-Parameter in einer Intent-Route oder Parameterverteilung auftreten.

Die Intent- und Sitzungsparameterverteilung ist der einzige Mechanismus, um optionale Formularparameter auf Werte aus der Endnutzereingabe festzulegen. Dieser Mechanismus kann jedoch auch die erforderlichen Formularparameterwerte festlegen oder überschreiben.

Voreinstellungen für Auftragsausführungsparameter

Die Auftragsausführung für eine Route, einen Event-Handler oder eine erneute Aufforderung zur Formulareingabe kann eine Voreinstellung für einen Auftragsausführungsparameter verwenden, um einen Formularparameterwert zur Laufzeit festzulegen. Eine Voreinstellung für einen Auftragsausführungsparameter überschreibt einen Parameterwert, einschließlich der Standardwerte von Parametern.

Webhook-Parametereinstellung

Ihr Webhook kann Formularparameterwerte zur Laufzeit festlegen. Weitere Informationen finden Sie in der Webhook-Antwort im Feld pageInfo.formInfo.parameterInfo.

Formularparameter abrufen

Interaktionen mit der API geben Formularparameterwerte zurück. Weitere Informationen finden Sie im Feld queryResult.parameters der Methode detectIntent für den Typ Session. Zur API-Referenz-Sitzung

Die empfangenden Formularparameterwerte von Webhook. Weitere Informationen finden Sie in der Webhook-Anfrage im Feld pageInfo.formInfo.parameterInfo.

Handler für die erneute Eingabeaufforderung zum Ausfüllen von Formularen

Handler für erneute Eingabeaufforderungen, auch als Event-Handler auf Parameterebene bezeichnet, werden verwendet, um das Verhalten von komplexen Parametern für erforderliche Parameter zu definieren. Handler für die erneute Eingabeaufforderung können beispielsweise verwendet werden, um die Eingabeaufforderung zu ändern, wenn der Endnutzer nach der ersten Eingabeaufforderung keinen Wert angibt, und um nach einer fehlgeschlagenen N-Eingabe zu einer anderen Seite zu wechseln.

Wenn keine Handler für die erneute Eingabeaufforderung definiert sind, wird die erste Eingabeaufforderung verwendet, um den Endnutzer nach Bedarf noch einmal aufzufordern.

Macht der Endnutzer unerwartete Eingaben, wird ein Ereignis vom Typ sys.no-match-* oder sys.no-input-* aufgerufen und alle für diese Ereignisse definierten Handler für die erneute Eingabeaufforderung werden aufgerufen.

Wie andere Ereignis-Handler ist ein Reprompt-Handler ein Zustands-Handler, der mit einer oder beiden der folgenden Optionen konfiguriert werden kann:

• Eine Auftragsausführung zur Bereitstellung einer Nachricht an den Nutzer mit einer erneuten Eingabeaufforderung und/oder einer Parametervoreinstellung.
• Ein Umstellungsziel zum Ändern der aktuellen Seite.

Sitzungsparameter

Wenn ein Parameter eines beliebigen Typs zur Laufzeit festgelegt wird, wird er in die Sitzung geschrieben und wird zu einem Sitzungsparameter. Diese Parameter werden nicht explizit bei der Entwicklung definiert. Sie können während einer Sitzung jederzeit auf diese Sitzungsparameter verweisen.

Sitzungsparameter referenzieren

Sitzungsparameterverweise können in den statischen Antwortnachrichten für die folgenden Arten von Auftragsausführungen verwendet werden:

• Auftragsausführung für Seiteneingaben
• Auftragsausführung für Routen
• Auftragsausführung für Event-Handler
• Auftragsausführung für Eingabeaufforderungen für Formulare
• Auftragsausführungen für erneute Eingabeaufforderungen für Formulare

Die Verweise können auch in folgenden Tools verwendet werden:

• Webhook-Headerwerte für die Authentifizierung.
• Flexible Webhook-Anfragen zum Senden von Parameterwerten an einen Webhook.

Verwenden Sie folgende Formate, um auf einen Sitzungsparameter zu verweisen:

$session.params.parameter-id

Sitzungsparameter festlegen

Wenn das Ausfüllen des Formulars abgeschlossen ist, werden die ausgefüllten Parameter von Conversational Agents (Dialogflow CX) in die Sitzung geschrieben.

Die Auftragsausführung für eine Route, einen Event-Handler oder eine erneute Eingabeaufforderung für Formulare kann mit einer Voreinstellung für Auftragsausführungsparameter einen Sitzungsparameterwert zur Laufzeit festlegen.

Ihr Webhook kann Sitzungsparameterwerte zur Laufzeit festlegen. Weitere Informationen finden Sie im Feld sessionInfo.parameters der Standard-Webhook-Antwort oder der flexiblen Webhook-Antwort.

Durch Interaktion mit der API können Sitzungsparameterwerte festgelegt werden. Weitere Informationen finden Sie im Feld queryParams.parameters der Anfragemethode detectIntent für den Typ Session. Zur API-Referenz-Sitzung

Sitzungsparameter abrufen

Interaktionen mit der API geben Sitzungsparameterwerte zurück Weitere Informationen finden Sie im Feld queryResult.parameters der Methode detectIntent für den Typ Session. Zur API-Referenz-Sitzung

Die empfangenden Sitzungsparameterwerte von Webhook. Weitere Informationen finden Sie in der Webhook-Anfrage im Feld sessionInfo.parameters.

Parameterverteilung

Wenn eine Endnutzereingabe einen Parameterwert bereitstellt, kann der Parameter an andere Ebenen weitergegeben werden:

• Wenn ein Intent-Parameter durch eine Intent-Übereinstimmung festgelegt wird, werden ähnliche Formularparameter für die aktive Seite auf denselben Wert gesetzt. Der Entitätstyp des Parameters wird durch die Intent-Parameterdefinition festgelegt.
• Wenn ein Intent-Parameter durch einen Intent-Abgleich festgelegt wird oder ein Formularparameter beim Ausfüllen eines Formulars festgelegt wird, wird der Parameter zu einem Sitzungsparameter.

DTMF für Telefonieintegrationen

Sie können DTMF (Dual-Tone-Multifrequenzsignalisierung) für einen Parameter aktivieren und konfigurieren. Nach der Aktivierung kann ein Endnutzer für einen Kundenservicemitarbeiter, der eine Telefonieintegration verwendet, das Telefon-Keypad verwenden, um Parameterwerte bereitzustellen.

Zur Vermeidung von Mehrdeutigkeit kann die DTMF-Eingabe sowohl in normalen als auch in DTMF-spezifischen Formen (empfohlen) interpretiert werden:

• Die normale Form ist einfach die Keypad-Werte, die vom Endnutzer eingegeben werden. z. B. 123#.
• Die DTMF-spezifische Form konvertiert die Eingabe in dtmf_digits_[digits], wobei [digits] die ursprünglichen DTMF-Ziffern sind, wobei * durch star und # durch pound ersetzt wird. Beispiel: 123# wird als dtmf_digits_123pound interpretiert.

Beim Abgleich von Entitätstypen für einen Parameter versucht Conversational Agents (Dialogflow CX), sowohl die normalen als auch die DTMF-spezifischen Formen abzugleichen. Wenn ein Entitätstyp für die DTMF-Eingabe verwendet wird, sollten Sie Synonyme wie dtmf_digits_123 definieren, um den NLU-Abgleich zu verbessern.

Wenn die DTMF-Eingabe nicht die Beendigungsbedingung erfüllt (entweder hat sie die maximale Ziffernlänge nicht erreicht oder wurde sie nicht durch die Ziffer beendet wurde), wartet der Conversational Agents (Dialogflow CX)-Agent auf weitere Eingabe. Wenn in diesem Zeitraum das Zeitlimit ohne Sprache ausgelöst wird, ruft der Agent stattdessen ein Ereignis ohne Eingabe auf. Wenn nur eine Sprachäußerung erkannt wird, stimmt der Agent mit der Spracheingabe überein. Wenn sowohl die Sprach- als auch die DTMF-Eingabe erkannt werden, wird die Spracheingabe verworfen und nur die DTMF-Eingabe berücksichtigt.

So aktivieren und passen Sie DTMF für einen Parameter an:

Beim Erstellen Ihres Agents können Sie DTMF-Eingabe im Simulator testen.

Intelligente Endpunktermittlung

Wenn die intelligente Weiterleitung für den Kundenservicemitarbeiter aktiviert ist, können Sie das Verhalten der intelligenten Weiterleitung für einen numerischen Parameter anpassen.

1. Legen Sie Mindestanzahl der Ziffern fest, um dem Smart Endpointer zu signalisieren, dass er warten soll, bis alle Ziffern erfasst wurden.
2. Wenn Sie Transkripte korrigieren auswählen, werden häufige Transkriptionsfehler bei Ziffern korrigiert, um die Spracherkennung von Ziffern zu verbessern. Dies wird nur für Anfragen unterstützt, bei denen ein Sprachcode „en“ oder „en-*“ angegeben ist.
3. Legen Sie mit Wartezeitüberschreitung fest, wie lange Konversations-Agenten (Dialogflow CX) zusätzlich warten, bis der Nutzer weitere Eingaben macht.

Parameter auf Flussebene

Parameter auf Flussebene können als Voreinstellungen für Auftragsausführungsparameter oder Formularparameter definiert werden. Auf diese Parameter kann nur verwiesen werden, solange der Ablauf, in dem sie definiert sind, aktiv ist. Sie werden nicht in den Sitzungsparametern gespeichert.

Verwenden Sie die folgende Syntax, um einen Parameter auf Flussebene zu definieren oder darauf zu verweisen:

$flow.parameter-name

Beispiel: Wenn der Parametername date lautet, können Sie den Parameter als $flow.date definieren oder darauf verweisen.

Die Verwendung eines $-Präfixes bei der Definition von Parametern unterscheidet sich von anderen Parametertypen, bei denen $ nicht für Parameterdefinitionen verwendet wird.

Beispiel für eine Parameterdefinition auf Flussebene:

Gültigkeitsdauer von Parameterwerten auf Flussebene

In bestimmten Fällen ist es jedoch wichtig zu wissen, wie Parameterwerte auf Flussebene bei Inaktivität eines Flusses beibehalten (oder verworfen) werden, wenn der Fluss wieder aktiv wird.

Ob Parameterwerte auf Ablaufebene bei Inaktivität eines Ablaufs beibehalten werden, hängt vom Ablaufstack und den Ablaufinstanzen im Stack ab.

• Wenn Ablauf A über ein bestimmtes Übergangsziel zu Ablauf B wechselt, bleibt Ablauf A (übergeordneter Ablauf) im Stapel, behält seine Parameterwerte auf Ablaufebene bei und dem Stapel wird eine neue Instanz von Ablauf B (untergeordneter Ablauf) hinzugefügt.
• Wenn ein untergeordneter Ablauf über ein symbolisches Übergangsziel (z. B. END_FLOW) zu einem übergeordneten Ablauf zurückkehrt, wird der untergeordnete Ablauf aus dem Stapel entfernt, alle Parameterwerte auf Ebene des untergeordneten Ablaufs werden verworfen und alle Parameterwerte auf Ebene des übergeordneten Ablaufs bleiben erhalten.
• Mit einer Reihe von Übergängen mit bestimmten Übergangszielen kann der Ablaufstapel mehrere Instanzen eines Ablauftyps enthalten. Jede Instanz des Ablauftyps hat eindeutige Parameterwerte auf Ablaufebene. Beispiel: A1 -> B1 -> C1 -> B2, wobei A, B und C Flusstypen sind und die Zahlen Instanzen dieser Flusstypen bezeichnen. In diesem Beispiel sind B1 und B2 unterschiedliche Instanzen von Ablauf B und haben eindeutige Parameter auf Ablaufebene.

Beispiele:

Parameter auf Anfrageebene

Parameter auf Anfrageebene sind kurzlebige Parameter, die von Conversational Agents (Dialogflow CX) erstellt werden. Sie können nur während des Lebenszyklus der aktuellen Anfrage referenziert werden und werden nicht in den Sitzungsparametern gespeichert.

Parameter auf Anfrageebene werden von Conversational Agents (Dialogflow CX) für die folgenden Funktionen generiert.

Integrierte Parameter

Sie können auf die verschiedenen Daten zugreifen, die mit der Anfrage verknüpft sind:

Benutzerdefinierte Nutzlast

Wenn QueryParameters.payload festgelegt ist, können Sie über $request.payload.param-id auf den entsprechenden Parameter zugreifen.

Sentimentanalyse

Wenn die Sentimentanalyse aktiviert ist, sind die folgenden Sentimentreferenzen verfügbar:

Entfernen von Parametern

Für jeden Intent- oder Formularparameter können Sie die Parameterentfernung aktivieren, um Endnutzer-Laufzeitparameterdaten aus Logs und dem internen Speicher von Conversational Agents (Dialogflow CX) zu entfernen. Entfernende Parameter werden in Logs als $parameter-name_redacted angezeigt.

Beispiel: Der Endnutzer gibt "My address is 1600 Amphitheatre Parkway" ein. Dies führt dazu, dass ein Address-Parameter an "1600 Amphitheatre Parkway" gesendet wird. Der protokollierte Text lautet "My address is $address_redacted".

So aktivieren Sie die Parameterentfernung:

Alternativ können Sie alle Parameter eines bestimmten Entitätstyps entfernen.