Parameters

Parameters are used to capture and reference values that have been supplied by the end-user during a session. Each parameter has a name and an entity type. Unlike raw end-user input, parameters are structured data that can easily be used to perform some logic or generate responses.

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 with star and # replaced with pound. For example, 123# is interpreted as dtmf_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

  1. Enable Advanced settings from the agent speech and IVR settings if you have not already enabled them.
  2. Create a page parameter.
  3. In the parameter pane, toggle Enable DTMF on.
  4. Set Max digits to the maximum number of digits the end-user can provide for this parameter.
  5. 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

Previous
Fuzzy matching
Next
Fulfillments