CX parameters are similar to ES parameters, but the utility and scope has been expanded, and the syntax to reference parameters has changed.
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 Dialogflow service, your service that calls the API, and your webhook service can all set parameter values. For example, the Dialogflow 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.
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.
When text is matched to a particular entity at runtime,
it is often converted to a value that is more convenient for processing.
For example, the word "apples" in end-user input
may be extracted as "apple" for a fruit entity.
You can reference either the original
value written or spoken by the end-user
or the resolved
value extracted by the entity.
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
.
You can also access the parameter's entity type name:
$intent.params.parameter-id.type
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 Dialogflow.
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# | Not available | Not available |
Go | Not available | 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. For each 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.
CX form filling is similar to ES slot filling.
The following data is used to define a form 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.
- Required: Indicates whether the parameter is required. Optional parameters will not trigger prompts, however, they are filled if the user specifies them. Required parameters must be filled before form filling concludes.
- Default Value: The default value of an optional parameter. If the parameter is required, the default value will be ignored.
- Initial Prompt Fulfillment: You configure this with a fulfillment that is used when the agent needs to initially prompt the end-user to fill the parameter.
- Reprompt Handlers: 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.
Define form parameters
Form parameters are defined at design-time when creating a page.
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
Fulfillment for a route, event handler, or form reprompt can use a fulfillment parameter preset to set a form parameter value at runtime.
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# | Not available | Not available |
Go | Not available | 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
During form filling, the agent asks the end-user to provide parameter values.
If the end-user responds with unexpected input,
a sys.no-match-*
or sys.no-input-*
event is invoked.
You can define reprompt handlers, also known as
parameter-level event handlers,
to reprompt the end-user for the parameter value.
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
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 the zip-code
member value as
$session.params.location.zip-code
.
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 Dialogflow.
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
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# | Not available | Not available |
Go | Not available | 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# | Not available | Not available |
Go | Not available | 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 partner 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 partner 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,
Dialogflow 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 Dialogflow 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 a speech utterance is detected, the agent will instead match against the speech transcript. In both cases, existing DTMF input will be dropped.
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 Dialogflow query on the agent, so if finish digit is # and the input is 123#, then the actual query input will be '123'
Parameter redaction
For any intent or form parameter,
you can enable parameter redaction,
which will redact end-user runtime parameter data from logs
and Dialogflow 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# | Not available | Not available |
Go | Not available | 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# | Not available | Not available |
Go | Not available | Not available |
Java | PagesClient | PagesClient |
Node.js | PagesClient | PagesClient |
PHP | Not available | Not available |
Python | PagesClient | PagesClient |
Ruby | Not available | Not available |