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.

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 Dialogflow treats Apple and apple 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 Dialogflow.

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 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++ 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.

CX form filling is similar to ES slot filling.

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 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

Dialogflow 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:

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.

  • 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 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 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 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 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

  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'

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.

  1. Set Minimum digits to hint smart endpointer to wait until all the digits collected.
  2. 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.
  3. Set Waiting timeout to specify the additional time Dialogflow 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 screenshot.

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 Dialogflow 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 Dialogflow for the following features.

Language and user input

You can access the language code and user input associated with the request using:

Reference Description
$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.

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 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++ 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.