Define, reference, set, and get parameters
There are four general ways in which parameters are used:
- Define at design-time: During design-time, you use either the console or the API to define parameters. For example, you can define an intent parameter and use it in a training phrase to indicate end-user input that should be extracted.
- Reference at design-time: Parameter references are variables that hold parameter values to be extracted at runtime. During design-time, you use either the console or the API to reference parameters in various data types. For example, you can reference a session parameter in a static fulfillment response for a route.
- Set at runtime: At runtime, the Conversational Agents (Dialogflow CX) service, your service that calls the API, and your webhook service can all set parameter values. For example, the Conversational Agents (Dialogflow CX) service sets the value of an intent parameter when an end-user input matches the intent, and the input contains parameter data.
- Get at runtime: At runtime, your parameter references contain the parameter values that have been set, and you can use the API or a webhook to get the parameter values. For example, when an intent is matched and your webhook is called, your webhook service receives the parameter values for the intent.
Parameter naming
The following rules apply to parameter naming:
- Use the following characters:
[A-Z]
,[a-z]
,[0-9]
,.
,-
,_
- Parameter names are case insensitive,
so Conversational Agents (Dialogflow CX) treats
Apple
andapple
as the same parameter. Webhook and API client code should also treat parameter names as case insensitive, because there is no case guarantee for parameter names returned by Conversational Agents (Dialogflow CX). - When you create parameters with the same ID or display name in different intents or forms, make sure that the entity type and other settings are the same for all definitions. If the entity type or other parameter settings differ, use unique parameter ID or display name for each definition.
Parameter value types
Parameter values support multiple value types. The sessions section below describes how to reference each parameter value type. The following types are supported:
Type | Description |
---|---|
Scalar | A single numeric or string value. |
Composite | A JSON object populated by matching a composite entity, or by filling of an intent parameter, which contains original and resolved fields. |
List | A list of scalar or composite values populated for a parameter configured as a list. See the Is List options below. |
Parameter empty string and null values
You can set string parameter values to ""
,
which sets the parameter to the empty string.
You can set any parameter value to null
,
which indicates that the parameter has not been set.
Parameter original values
When text is matched to a particular entity at runtime, it is often resolved to a value that is more convenient for processing. For example, the word "apples" in end-user input may be resolved as "apple" for a fruit entity.
All value types for intent parameter references can reference either the original or resolved value.
Only composite value types for session parameter references can reference the original value.
Intent parameters
Intents use parameters to extract data provided by end-users when intents are matched. The following data is used to define an intent parameter:
- Name (also known as ID or Display Name): A name that identifies the parameter.
- Entity Type: The entity type associated with the parameter.
- Is List: If true, the parameter is treated as a list of values.
- Redact in log: If true, end-user provided parameter data is redacted.
Define intent parameters
Intent parameters are defined at design-time when creating intent data or when annotating training phrases.
Reference intent parameters
Intent parameter references can be used in static fulfillment response messages of intent routes.
You can reference either the original value or the resolved value.
To reference a parameter for the currently matched intent, use one of the following formats:
$intent.params.parameter-id.original $intent.params.parameter-id.resolved
For example,
if the parameter ID is date
,
you can reference the resolved value as $intent.params.date.resolved
.
Set intent parameters
When an end-user input matches an intent at runtime, any parameter used by an annotation for the associated training phrase is set by Conversational Agents (Dialogflow CX).
The fulfillment for an intent route can use a fulfillment parameter preset to set an intent parameter value at runtime.
Get intent parameters
During the conversational turn in which an intent is matched, your code can access the intent parameter values.
Interactions with the API will return the intent parameter values.
See the detectIntent
method's queryResult.parameters
response field
for the Session
type.
Select a protocol and version for the Session reference:
Protocol | V3 | V3beta1 |
---|---|---|
REST | Session resource | Session resource |
RPC | Session interface | Session interface |
C++ | SessionsClient | Not available |
C# | SessionsClient | Not available |
Go | SessionsClient | Not available |
Java | SessionsClient | SessionsClient |
Node.js | SessionsClient | SessionsClient |
PHP | Not available | Not available |
Python | SessionsClient | SessionsClient |
Ruby | Not available | Not available |
Webhook's receive intent parameter values.
See the intentInfo.parameters
field in the
Webhook request.
Form parameters
For each page, you can define a form, which is a list of parameters that should be collected from the end-user for the page. The agent interacts with the end-user for multiple conversation turns, until it has collected all of the required form parameters, which are also known as page parameters. The agent collects these parameters in the order defined on the page. For each required form parameter, you also provide prompts that the agent uses to request that information from the end-user. This process is called form filling.
For example, you might create a form
that collects the end-user's name
and telephone number for a Collect Customer Info
page.
The following data is used to define a form parameter:
Console option name | API field chain | Description |
---|---|---|
Display name | Page.form.parameters[].displayName |
A name that identifies the parameter. |
Entity type | Page.form.parameters[].entityType |
The entity type associated with the parameter. |
Required | Page.form.parameters[].required |
Indicates whether the parameter is required. Required parameters must be filled before form filling concludes, and the agent will prompt the end-user for values. See the Set form parameters section below for details. |
Default Value (only visible when Required is unchecked) | Page.form.parameters[].defaultValue |
The default value of an optional parameter. See the Set form parameters section below for details. |
Is list | Page.form.parameters[].isList |
If true, the parameter is treated as a list of values. |
Redact in log | Page.form.parameters[].redact |
If true, end-user provided parameter data is redacted. |
Initial prompt fulfillment | Page.form.parameters[].fillBehavior.initialPromptFulfillment |
Initial prompts in the form of fulfillment to request a required parameter value from the end-user. See the Set form parameters section below for details. |
Reprompt event handlers | Page.form.parameters[].fillBehavior.repromptEventHandlers |
These are used when the agent needs to reprompt the end-user to fill the parameter after a failed attempt. See Form filling reprompt handlers. If no reprompt event handlers are defined, the agent will reprompt with the initial prompts after a failed attempt. |
DTMF | Not available | See the DTMF section below. |
Define and manage form parameters
Form parameters are defined at design-time when creating a page.
To change the form parameter order with the console, click the Parameters section title on the page, then drag parameter rows in the parameter table.
To delete a form parameter, click the Parameters section title on the page, hover your mouse over a parameter, then click the delete delete button.
Reference form parameters
Form parameter references are not used directly. You can only check the fill status of individual form parameters or the form as a whole. You can use these form status references in a condition requirement of a condition route.
To check whether the current page's complete form is filled, use the following condition:
$page.params.status = "FINAL"
To check whether a particular form parameter was filled in the last turn, use the following condition:
$page.params.parameter-id.status = "UPDATED"
Set form parameters
Form parameter values can be set in a variety of ways. The following subsections describe each mechanism for setting form parameter values.
Default parameter values
You can provide default values for optional form parameters. When form filling starts, all unset optional form parameters are set to their default values. These values can be initialized or overridden by some of the mechanisms below.
If a parameter is required, its default value is ignored.
Form filling
Conversational Agents (Dialogflow CX) automatically sets parameter values provided by the end-user during form filling. The agent collects required parameters in the order defined on the page. The agent prompts the end-user for required values using the initial prompt fulfillment you provide for each required parameter. Optional parameters will not trigger prompts.
If a required parameter value is not provided by the end-user after an agent prompt, the initial prompt will be repeated unless a different behavior is defined in the reprompt handlers. If there are multiple initial text prompts defined, the agent behavior is the same as the behavior for any fulfillment text responses.
Intent and session parameter propagation
When a parameter of any type is set at runtime, the parameter is written to the session and becomes a session parameter.
When a page initially becomes active, and during its active period, any form parameter with the same name as a session parameter is automatically set to the session parameter value.
This can happen with a matched intent parameter in an intent route or parameter propagation.
Intent and session parameter propagation is the only mechanism to set optional form parameters to values from end-user input, but this mechanism can also set or override required form parameter values.
Fulfillment parameter presets
Fulfillment for a route, event handler, or form reprompt can use a fulfillment parameter preset to set a form parameter value at runtime. A fulfillment parameter preset will override a parameter value, including parameter default values.
Webhook parameter setting
Your webhook can set the values of form parameters at runtime.
See the pageInfo.formInfo.parameterInfo
field in the
Webhook response.
Get form parameters
Interactions with the API will return the form parameter values.
See the detectIntent
method's queryResult.parameters
response field
for the Session
type.
Select a protocol and version for the Session reference:
Protocol | V3 | V3beta1 |
---|---|---|
REST | Session resource | Session resource |
RPC | Session interface | Session interface |
C++ | SessionsClient | Not available |
C# | SessionsClient | Not available |
Go | SessionsClient | Not available |
Java | SessionsClient | SessionsClient |
Node.js | SessionsClient | SessionsClient |
PHP | Not available | Not available |
Python | SessionsClient | SessionsClient |
Ruby | Not available | Not available |
Webhook's receive form parameter values.
See the pageInfo.formInfo.parameterInfo
field in the
Webhook request.
Form filling reprompt handlers
Reprompt handlers, also known as parameter-level event handlers, are used to define complex parameter prompt behavior for required parameters. For example, reprompt handlers can be used to alter the prompt when the end-user fails to provide a value after the initial prompt, and to transition to another page after N failed attempts.
If no reprompt handlers are defined, the initial prompt will be used to reprompt the end-user as needed.
If the end-user responds with unexpected input,
a sys.no-match-*
or sys.no-input-*
event is invoked,
and any reprompt handlers defined for these events are called.
Like other event handlers, a reprompt handler is a type of state handler that can be configured with one or both of:
- A fulfillment to provide an end-user reprompt message and/or a parameter preset.
- A transition target to change the current page.
Session parameters
When a parameter of any type is set at runtime, the parameter is written to the session and becomes a session parameter. These parameters are not explicitly defined at design-time. You can reference these session parameters at any point during a session.
Reference session parameters
Session parameter references can be used in the static response messages for the following types of fulfillment:
- Page entry fulfillment
- Route fulfillment
- Event handler fulfillment
- Form prompt fulfillment
- Form reprompt fulfillment
The references can also be used in:
- Webhook header values for authentication.
- Flexible webhook requests, for sending parameter values to a webhook.
To reference a session parameter, use the following formats:
Scalar
To access a parameter with a scalar entity type:
$session.params.parameter-id
For example,
if the parameter ID is date
,
you can reference the value as $session.params.date
.
Composite
To access a member of a parameter with a composite entity type:
$session.params.parameter-id.member-name
For example, if the parameter ID is
location
, you can reference thezip-code
member value as$session.params.location.zip-code
.To access the original value of a parameter with a composite entity type:
$session.params.parameter-id.original
To access the full object of a parameter with a composite entity type, use the IDENTITY system function.
List
To access a complete list of elements:
$session.params.parameter-id
For example, if the list parameter ID is
colors
and the values extracted from a user query are["red", "blue", "yellow"]
, you can reference all the values as$session.params.colors
.To access the ith element of a list parameter:
$session.params.parameter-id[i]
For example, if the list parameter ID is
colors
, you can reference the first value as$session.params.colors[0]
.
Set session parameters
When form filling is done, the filled parameters are written to the session by Conversational Agents (Dialogflow CX).
Fulfillment for a route, event handler, or form reprompt can use a fulfillment parameter preset to set a session parameter value at runtime.
Your webhook can set the values of session parameters at runtime.
See the sessionInfo.parameters
field in the
standard webhook response
or see
flexible webhook response.
Interactions with the API can set session parameter values.
See the detectIntent
method's queryParams.parameters
request field
for the Session
type.
Select a protocol and version for the Session reference:
Protocol | V3 | V3beta1 |
---|---|---|
REST | Session resource | Session resource |
RPC | Session interface | Session interface |
C++ | SessionsClient | Not available |
C# | SessionsClient | Not available |
Go | SessionsClient | Not available |
Java | SessionsClient | SessionsClient |
Node.js | SessionsClient | SessionsClient |
PHP | Not available | Not available |
Python | SessionsClient | SessionsClient |
Ruby | Not available | Not available |
Get session parameters
Interactions with the API will return the session parameter values.
See the detectIntent
method's queryResult.parameters
response field
for the Session
type.
Select a protocol and version for the Session reference:
Protocol | V3 | V3beta1 |
---|---|---|
REST | Session resource | Session resource |
RPC | Session interface | Session interface |
C++ | SessionsClient | Not available |
C# | SessionsClient | Not available |
Go | SessionsClient | Not available |
Java | SessionsClient | SessionsClient |
Node.js | SessionsClient | SessionsClient |
PHP | Not available | Not available |
Python | SessionsClient | SessionsClient |
Ruby | Not available | Not available |
Webhook's receive session parameter values.
See the sessionInfo.parameters
field in the
Webhook request.
Parameter propagation
When an end-user input provides a parameter value, the parameter may be propagated to other levels:
- When an intent parameter is set by an intent match, like-named form parameters for the active page are set to the same value. The entity type of the parameter is dictated by the intent parameter definition.
- When an intent parameter is set by an intent match, or a form parameter is set while filling a form, the parameter becomes a session parameter.
DTMF for telephony integrations
You can enable and configure DTMF (Dual-tone multi-frequency signaling) for a parameter. Once enabled, an end-user for an agent using a telephony integration can use the telephone keypad to provide parameter values.
To reduce ambiguity, DTMF input can be interpreted in both normal and DTMF-specific (recommended) forms:
- The normal form is simply the keypad values as entered by the end-user.
For example,
123#
. - The DTMF-specific form converts the input to
dtmf_digits_[digits]
, where[digits]
is the original DTMF digits with*
replaced withstar
and#
replaced withpound
. For example,123#
is interpreted asdtmf_digits_123pound
.
When matching entity types for a parameter,
Conversational Agents (Dialogflow CX) will try to match both the normal and DTMF-specific forms.
When an entity type is used for DTMF input,
it is recommended that you define synonyms like dtmf_digits_123
to improve NLU matching.
If the DTMF input does not meet the termination condition (either it has not reached the max digit length or it has not been terminated by the finish digit), the Conversational Agents (Dialogflow CX) agent will keep waiting for more input. During this period, if no-speech timeout is triggered, the agent will instead invoke a no-input event. If only a speech utterance is detected, the agent matches against the speech input. If both speech and DTMF input are detected, the speech input is dropped and only the DTMF input is considered.
To enable and customize DTMF for a parameter:
Console
- Enable Advanced settings from the agent speech and IVR settings if you have not already enabled them.
- Create a page parameter.
- In the parameter pane, toggle Enable DTMF on.
- Set Max digits to the maximum number of digits the end-user can provide for this parameter.
- Set Finish digit to the keypad value
that will terminate DTMF input for the parameter.
It is common to use
#
for this setting. The finish digit is not added to the Conversational Agents (Dialogflow CX) query on the agent, so if finish digit is # and the input is 123#, then the actual query input will be '123'
When building your agent, you can test DTMF inputs in the simulator.
Smart endpointing
If smart endpointing is enabled for the agent, you can customize smart endpointing behavior for a numeric parameter.
- Set Minimum digits to hint smart endpointer to wait until all the digits collected.
- Set Fix transcripts to improve digits speech recognition by fixing common digits transcription errors. This is supported only for requests that specify an en or en-* language code.
- Set Waiting timeout to specify the additional time Conversational Agents (Dialogflow CX) will wait for the user to provide more input.
Flow-scoped parameters
Flow-scoped parameters can be defined as fulfillment parameter presets or form parameters. These parameters can only be referenced while the flow they are defined in is active, and they are not persisted into the session parameters.
To define or reference a flow-scoped parameter, use the following syntax:
$flow.parameter-name
For example,
if the parameter name is date
,
you can define or reference the parameter as $flow.date
.
Note that using a prefix of $
when defining parameters
is different than other parameter types that do not use $
for parameter definitions.
An example flow-scoped parameter definition:
Flow-scoped parameter value lifetime
It is uncommon, but in certain advanced cases, you may need to understand how flow-scoped parameter values are retained (or discarded) when a flow becomes inactive, then active again.
Whether flow-scoped parameter values are retained when a flow becomes inactive, then active again depends on the flow stack and flow instances on the stack.
- When flow A transitions to flow B using a specific transition target, flow A (parent flow) remains on the stack, flow A retains its flow-scoped parameter values, and a new instance of flow B (child flow) is added to the stack.
- When a child flow transitions back to a parent flow using a symbolic transition target (for example, END_FLOW), the child flow is removed from the stack, all child flow-scoped parameter values are discarded, and all parent flow-scoped parameter values are retained.
- Using a series of transitions with specific transition targets, the flow stack can contain multiple instances of one flow type. Each instance of the flow type has unique flow-scoped parameter values. For example: A1 -> B1 -> C1 -> B2, where A, B, and C are flow types, and the numbers denote instances of those flow types. In this example, B1 and B2 are different instances of flow B, and have unique flow-scoped parameters.
Examples:
Transitions | Outcome |
---|---|
Flow A (A1) becomes active. Flow B (B1) becomes active using a specific transition target. Flow B transitions back to the flow A (A1) that initiated it using a symbolic transition target. |
Flow A retains the parameter values. |
Flow A (A1) becomes active. Flow B (B1) becomes active using a specific transition target. Flow B transitions to a new instance of flow A (A2) using a specific transition target. |
The new instance of flow A (A2) at the top of the stack does not have access to the parameter values of flow A (A1) at the bottom of the stack. |
Flow A (A1) becomes active. Flow B (B1) becomes active using a specific transition target. Flow A (A1) becomes active using a symbolic transition target. Flow B (B2) becomes active using a specific transition target. |
Flow B (B2) does not retain parameter values that were set while it was active after the second transition (B1). |
Request-scoped parameters
Request-scoped parameters are short-lived parameters created by Conversational Agents (Dialogflow CX) that can only be referenced during the lifecycle of the current request, and are not persisted into the session parameters.
Request-scoped parameters are generated by Conversational Agents (Dialogflow CX) for the following features.
Built-in parameters
You can access the various data associated with the request using:
Reference | Description |
---|---|
$request.agent-id | The identifier of the agent. |
$request.session-id | The identifier of the session. |
$request.language | Language code specified in QueryInput.language_code . |
$request.resolved-language | The actual language code used by the agent during processing. The resolved language can be different from the language specified in the request. For example, if the agent only supports "en", while the language specified in the request is "en-US", the resolved language would be "en". |
$request.user-utterance | The current user utterance specified in the request. |
$request.last-agent-utterance | The most recent utterance sent by the agent. |
Custom Payload
When QueryParameters.payload
is set, you can access the corresponding parameter via $request.payload.param-id
.
Sentiment Analysis
The following sentiment references are available when sentiment analysis is enabled:
Reference | Type | Description |
---|---|---|
$request.sentiment.score | Number | Sentiment score between -1.0 (negative sentiment) and 1.0 (positive sentiment). |
$request.sentiment.magnitude | Number | Indicates the overall strength of emotion (both positive and negative) between 0.0 and +inf. Unlike score, magnitude is not normalized; each expression of emotion within the end-user input (both positive and negative) contributes to the input's magnitude. Longer inputs may have greater magnitudes. |
$request.sentiment.succeeded | Boolean | True if sentiment analysis succeeded, false otherwise. |
Parameter redaction
For any intent or form parameter,
you can enable parameter redaction,
which will redact end-user runtime parameter data from logs
and Conversational Agents (Dialogflow CX) internal storage.
Redacted parameters are shown as $parameter-name_redacted
in logs.
For example, consider an end-user input of "My address is 1600 Amphitheatre Parkway" that results in an address parameter being sent to "1600 Amphitheatre Parkway". The logged text will be "My address is $address_redacted".
To enable parameter redaction:
Console
Check the Redact in log checkbox when creating or updating a parameter.
API
Set the parameters[].redact
field to true for the Intent
type.
Select a protocol and version for the Intent reference:
Protocol | V3 | V3beta1 |
---|---|---|
REST | Intent resource | Intent resource |
RPC | Intent interface | Intent interface |
C++ | IntentsClient | Not available |
C# | IntentsClient | Not available |
Go | IntentsClient | Not available |
Java | IntentsClient | IntentsClient |
Node.js | IntentsClient | IntentsClient |
PHP | Not available | Not available |
Python | IntentsClient | IntentsClient |
Ruby | Not available | Not available |
Set the form.parameters[].redact
field to true for the Page
type.
Select a protocol and version for the Page reference:
Protocol | V3 | V3beta1 |
---|---|---|
REST | Page resource | Page resource |
RPC | Page interface | Page interface |
C++ | PagesClient | Not available |
C# | PagesClient | Not available |
Go | PagesClient | Not available |
Java | PagesClient | PagesClient |
Node.js | PagesClient | PagesClient |
PHP | Not available | Not available |
Python | PagesClient | PagesClient |
Ruby | Not available | Not available |
As an alternative, you can redact all parameters of a specific entity type.