state

The state tag declares a state in which the dialog context can be.

caution

States should always be nested into some theme declared using the theme tag.

Value

A state name is specified after the tag. Names can consist of arbitrary Unicode characters.

Nested data

On the next nesting level after a state declaration, you can specify trigger, reaction, and action tags. They determine how the dialog context can enter the state and what reactions the bot will then execute.

Additionally, state tags can have other state tags nested recursively into them. This makes it possible to build up the hierarchical script structure, where some states are nested into others.

tip

Learn more about switching between states

How to use

require: name/nameEn.sc
    module = sys.zb-common

theme: /

    state: Start
        q!: $regex</start>
        a: Hi! What’s your name?

        state: GetName
            q: * $Name *
            a: Nice to meet you, {{capitalize($parseTree._Name.name)}}!

    state: NoMatch
        event: noMatch
        a: I’m sorry, I didn’t catch that.

tip

The Start state is a parent state in relation to GetName. States nested into parent states are called children states.

Parameters

info

Parameters are key–value pairs separated from the name or value (if present) with two vertical bars. If there are several parameters, they are separated from each other with commas. Parameters modify the tag behavior.

The state tag accepts the following parameters:

Parameter	Type	Description	Default value
noContext	Boolean	If true, making a transition to the state doesn’t change the current bot context.	false
modal	Boolean	If true, the state sets restrictions on the states in which the next request can be processed.	false
sessionResult	String	The dialog result set upon entering the state.	—
sessionResultColor	String	The color of the dialog result label in the J‑Graph visual editor.	—

noContext

If a state has the noContext parameter set to true, making a transition to this state doesn’t change the current bot context. The next user request is processed in the context of the state the bot was before making this transition.

Take a look at the following script:

theme: /

    state: Greeting
        q!: * (hi/good (~day/~morning/~evening)) *
        a: Hi! How are you doing?

        state: DoinGood
            q: * (good/okay/fine) *
            a: Glad to hear you’re fine! How can I help you?

        state: DoinBad
            q: * (bad/not [really] good) *
            a: I’m sorry to hear that. Is there any way I can help?

    state: NoMatch || noContext = true
        event!: noMatch
        a: I’m sorry, I didn’t catch that. Try saying it differently.

Let’s assume that in response to the bot’s question How are you doing? , the user replies I’m all right. No patterns in the nested states match this answer, so the script switches to NoMatch, making the bot ask to reformulate the answer. The user then says I’m doing fine.

If the NoMatch state didn’t have the noContext parameter, then the reply wouldn’t be recognized despite the fact that it is matched by the pattern in the DoinGood state: previously, the dialog context switched to the NoMatch, and it cannot access DoinGood by the q trigger tag.

With the noContext parameter, the dialog context doesn’t change on entering NoMatch and remains in the Greeting state. The answer gets processed in the appropriate context and switches to the DoinGood nested state.

tip

Use the noContext parameter for states that shouldn’t move the conversation forward: this usually means states for handling unrecognized requests, repeated inquiries in the phone channel, etc.

modal

If a state has the modal parameter set to true, this state sets restrictions on the states in which the next user request can be processed. When the dialog context is in a modal state, only the following states are reachable:

• States directly nested into the modal state.
• States which can be entered from the modal state by a tag with the fromState or toState parameter.

caution

• The restrictions of modal states do not apply to events. When the context is in a modal state and an event occurs for which there is a handler state in the script, the event will be successfully processed.

• If among the reachable states there is neither a state for processing the request nor the noMatch event handler, the bot will attempt to switch to the global noMatch handler state. If there is no such state in the script either, an error will be raised, telling you that no state to switch to has been found.

Take a look at the following script:

theme: /

    state: OrderStatus || modal = true
        q!: * (where/status) * [my] ~order *
        a: What is your order number?

        state: GetNumber
            q: * @duckling.number *
            a: Your order is on its way!
            go!: /WhatElse

        state: LocalCatchAll
            event: noMatch
            a: This doesn’t look like an order number. Please try again.

    state: WhatElse
        intent: /DontKnow || fromState = "/OrderStatus"
        a: What else can I help you with?

In this script, the user can learn the status of their order by telling its number. Since the OrderStatus has the modal parameter, the dialog can only exit it when the user:

• Tells the order number. The context will switch to WhatElse by the go! tag.
• Tells they don’t know the number. The context will switch to WhatElse by the q tag with fromState.

tip

Use the modal parameter for states where the user is asked some important information which is necessary to allow the dialog to continue.

sessionResult and sessionResultColor

The sessionResult parameter sets the result assigned to the dialog upon entering the state. This is usually the description of a business goal achieved by the bot, but it may as well be an arbitrary comment.

tip

The $analytics.setSessionResult method works in the same way. If one state has both this parameter and a call to this method from a script tag, only the method call counts.

The optional sessionResultColor parameter configures the color of the dialog result label in the J‑Graph visual editor. The parameter value is a HEX code of one of the colors which can be selected in J‑Graph (for example, #FFFFFF).

state: Feedback
    a: Did you find out everything you wanted?

    state: Positive || sessionResult = "Positive feedback", sessionResultColor = "#15952F"
        intent: /Yes
        a: Thanks for your feedback. We are always happy to help!

    state: Negative || sessionResult = "Negative feedback", sessionResultColor = "#CD4C2B"
        intent: /No
        a: Sorry that we couldn’t help you. How can we improve our service?