State handlers

State handlers, also simply called handlers, are used to control the conversation by creating responses for end-users and/or by transitioning the current page. For each conversational turn, handlers are evaluated and may affect the session. Handlers have three general types of data:

Term Definition
Handler requirements These are the requirements that must be satisfied for the handler to have any effect on the session. A handler is said to be called when it satisfies its requirements and affects the session in some way.
Handler fulfillment If a handler is called, an optional fulfillment is used to create responses for end-users. These responses are either defined in static agent data or retrieved dynamically from your webhook service.
Handler transition target If a handler is called, an optional transition target is used to change the current page. The next page can only be a flow start page or a page within the currently active flow.

There are two types of state handlers with differing handler requirements:

Term Definition
Routes Routes are called when an end-user input matches an intent and/or some condition on the session status is met. A route with an intent requirement is also called an intent route. A route with only a condition requirement is also called a condition route.
Event handlers Event handlers are called when an event is invoked. Some built-in events are triggered when unexpected end-user input is received, or when a webhook error occurs. You can also define custom events that you invoke when something happens outside the conversation.

There are three steps to processing a state handler:

Term Definition
1. Scope A handler must be in scope to have any effect on the session. The scope is determined by whether a handler is applied to a flow, a page, or a form parameter; and by whether the associated flow is active, the associated page is active, or the agent is currently attempting to fill the associated form parameter.
2. Evaluation Each handler in scope is evaluated in order. If a handler's requirements are met, it passes evaluation.
3. Call If a handler is in scope and passes evaluation, it is called. Any associated fulfillment is called, and any associated transition target is applied to the session.

Scope

In order for a handler to be evaluated, it must be in scope. Handler scope is an important and powerful tool that helps you control the conversation. By controlling the scope of a handler, you can control:

X Item
When an intent can be matched
When a condition should be checked
When a certain event can be handled
When a page transition can occur
When a static fulfillment response is provided
When a webhook-enabled fulfillment is called for dynamic responses

The scope is determined by whether a handler is applied to a flow, a page, or a form parameter; and by whether the associated flow is active, the associated page is active, or the agent is currently attempting to fill the associated form parameter.

The detailed scoping rules are as follows:

  • Routes applied to the active flow:
    • If the current page is the flow start page, they are in scope.
    • If the current page is not the flow start page, they are only in scope if they have an intent requirement.
  • Routes applied to the current page are in scope.
  • Event handlers applied the active flow are in scope.
  • Event handlers applied to the current page are in scope.
  • Event handlers applied to a form parameter that the agent is currently attempting to fill are in scope.

Routes

Routes have two requirements, and one or both must be provided. If both requirements are provided, they both must be satisfied in order to call the route:

Term Definition
Intent requirement An intent which must be matched to end-user input for the current conversational turn. When a route has an intent requirement, it is called an intent route.
Condition requirement A condition which must be met. When a route has a condition requirement, it is called a condition route.

You can apply routes to flows (flow-level routes) and pages (page-level routes). For example, you might use routes in the following situations:

X Item
When end-user input matches an intent, the match should trigger a static fulfillment response.
When end-user input matches an intent, the match should trigger a webhook-enabled fulfillment for a dynamic response.
When end-user input has provided the final required form parameter a condition check triggers a session transition to another page.
When end-user input has provided a specific form parameter a condition check triggers a static fulfillment response.
A condition check set to true that forces a page transition.

Intent propagation

Normally, when a route is called due to a matched intent, the intent is consumed. A consumed intent cannot be matched again, unless new end-user input triggers a new intent match. However, it is possible to propagate an intent match from one flow to another in the following scenario:

  • A route in flow F1 has intent I1 as a requirement and flow F2 as a transition target.
  • Flow F2 has a route that also has intent I1 as a requirement.

In this case, when the route in flow F1 is called, intent I1 is matched twice for a single end-user input, and both routes are called.

Propagating intents is useful to:

X Item
Change the current page to a specific page in another flow (transition target flow's route has a specific transition target page).
Create an entry message for a flow's start page (transition target flow's route has a fulfillment).

Route groups

When building an agent, you may find that many pages have a common set of routes. To make routes reusable, you can define route groups. These groups are a resource for the entire flow.

For example, you may want your flow to handle end-user input like "I want to add a topping to my pizza" and "I want to change my drink size". These inputs should be handled when any one of multiple pages of the flow are active. You could define two routes with intents to handle these inputs for all relevant pages, but this is a lot of duplicated work. Instead, you can define the route group once, and add a reference to the group on all relevant pages.

Flow-level routes

Flow-level routes are routes that are applied to a flow. These types of handlers have the following use cases:

X Item
Handlers with an intent or condition requirement in scope for the flow start page.
Handlers with an intent requirement in scope for all pages within the flow.

Page-level routes

Page-level routes are routes that are applied to a page. These types of handlers have the following use cases:

X Item
Handlers with an intent or condition requirement in scope when specific pages are active.

Event handlers

Event handlers have one requirement in order to be called:

Term Definition
Event requirement An event which must be invoked. Events are identified by their name. Some built-in events are invoked when unexpected end-user input is received, or when a webhook error occurs. You can also define custom events that you invoke when something happens outside of the conversation.

You can apply event handlers to flows (flow-level event handlers), pages (page-level event handlers), and parameters (parameter-level event handlers). For example, you might use event handlers in the following situations:

X Item
When end-user input does not match any intents, a no-match event handler provides a specific static fulfillment response.
A timer expires in your system, and you want to provide reminder information to the end-user with a specific static fulfillment response.

Flow-level event handlers

Flow-level event handlers are event handlers that are applied to a flow. These types of handlers have the following use cases:

X Item
Handlers with an event requirement in scope for the flow start page.
Handlers with an event requirement in scope for all pages within the flow.
Handling unexpected end-user input, shared by all pages in a flow.
Handling webhook errors, shared by all pages in a flow.
Handling custom events invoked by your system, shared by all pages in a flow.

Every flow has event handlers for the no-match and no-input built-in events. These event handlers are automatically created when you create a flow, and they cannot be deleted.

Page-level event handlers

Page-level event handlers are event handlers that are applied to a page. These types of handlers have the following use cases:

X Item
Handlers with an event requirement in scope when specific pages are active.
Handling unexpected end-user input, specific to a page.
Handling webhook errors, specific to a page.
Handling custom events invoked by your system, specific to a page.

Parameter-level event handlers

Parameter-level event handlers are event handlers that are applied to a form parameter. They are also known as reprompt handlers. These event handlers do not allow custom events, as they are specifically intended to handle invalid end-user input during form filling.

These types of handlers have the following use cases:

X Item
The end-user did not provide valid input when asked to fill a form parameter.

Built-in events

The following events are built-in. Some events are restricted to certain levels.

Event name
Flow-level Page-level Parameter-level Invoked when
sys.no-match-default End-user input does not match any intents for handlers that are in scope, nor does it satisfy any form parameters.
sys.no-match-[1-6] If you provide handlers for any of these numerically ordered events, they are invoked instead of sys.no-match-default and in order: sys.no-match-1, sys.no-match-2, ...
sys.no-input-default End-user input was not received.
sys.no-input-[1-6] If you provide handlers for any of these numerically ordered events, they are invoked instead of sys.no-input-default and in order: sys.no-input-1, sys.no-input-2, ...
sys.invalid-parameter Invoked when a webhook invalidates the parameter.
webhook.error The webhook call returned an error.
webhook.error.timeout The webhook call timed out.

Custom events

You can create custom events and event handlers. Events are simply identified by name, but you must avoid using built-in event names to avoid conflict.

To invoke an event with the API, see the queryParams.event field of the detectIntent method in the

Select a protocol and version for the Session reference:

Protocol V3beta1
REST Session resource
RPC Session interface

Evaluation order

Handlers are evaluated in a specific order. The following general rules apply:

  1. Only handlers in scope are evaluated.
  2. Only handlers whose requirements are satisfied can be called.
  3. If a handler without a transition target is called, evaluation of the list of handlers continues. Due to this rule, multiple fulfillments can add multiple messages to the response queue.
  4. If a handler with a transition target is called, evaluation of the list of handlers ends.
  5. If a handler with fulfillment is called, and the fulfillment results in a webhook error:
    • If an event handler is in scope for the event, it handles the event and evaluation of the list of handlers ends.
    • If no event handler is in scope for the event, the webhook silently fails.
  6. When an intent or condition requirement is satisfied, the intent or condition is not consumed, so multiple routes with the same intent or condition can be called.
  7. When an event requirement is satisfied, the event is consumed, so only the first event handler found for the event can be called.

There are three phases to the evaluation:

  1. Routes that have an intent requirement are evaluated in this order:
    1. Page-level: Individual routes applied to the current page, in the order supplied.
    2. Page-level groups: Route groups applied to the current page, in the order supplied.
    3. Flow-level: Routes applied to the active flow, in the order supplied.
  2. Routes with only a condition requirement are evaluated in this order:
    1. Page-level: Individual routes applied to the current page, in the order supplied.
  3. Event handlers are evaluated in this order:
    1. Parameter-level: Event handlers applied to the current page's form parameter that the agent is currently attempting to fill (reprompt handlers), in the order supplied.
    2. Page-level: Event handlers applied to the current page, in the order supplied.
    3. Flow-level: Event handlers applied to the active flow, in the order supplied.

Symbolic transition targets

When entering a transition target for a handler, you can enter specific flows or pages, but you can also enter symbolic transition targets:

Symbolic transition target
Description
START_PAGE Transition to the like-named active flow's start page.
END_FLOW End the currently active flow and transition back to the page that caused a transition to the current flow.
END_SESSION Clear current session and transition to the special page named END_SESSION. The next user input will restart the session at the start page of the Default Start Flow.
PREVIOUS_PAGE Transition to the previous page.
CURRENT_PAGE Re-transition to the current page. This can be useful if you want the agent to repeat something.