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.

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 V3beta1
REST Session resource
RPC Session interface
Java SessionsClient
Node.js SessionsClient
Python SessionsClient

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.
  • 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 V3beta1
REST Session resource
RPC Session interface
Java SessionsClient
Node.js SessionsClient
Python SessionsClient

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 V3beta1
REST Session resource
RPC Session interface
Java SessionsClient
Node.js SessionsClient
Python SessionsClient

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 V3beta1
REST Session resource
RPC Session interface
Java SessionsClient
Node.js SessionsClient
Python SessionsClient

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.