state

Декларативный тег state объявляет стейт — состояние, в котором может находиться контекст диалога.

предупреждение

Стейты всегда должны быть вложены в какую-либо тему, которая объявлена при помощи тега theme.

Значение

После тега записывается название стейта. Название может содержать любые символы Unicode.

Вложенные данные

На уровне вложенности, следующем после объявления стейта, могут записываться теги активации, теги реакций и теги действий. Они определяют то, как контекст диалога может попасть в стейт и какие реакции выполнит бот.

Кроме того, в теги state могут быть рекурсивно вложены другие теги state. Таким образом задается древовидная структура сценария, где одни стейты вложены в другие.

подсказка

Подробнее о принципах перехода по стейтам

Примеры использования

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

theme: /

    state: Start
        q!: $regex</start>
        a: Здравствуйте! Как вас зовут?

        state: GetName
            q: * $Name *
            a: Очень приятно, {{capitalize($parseTree._Name.name)}}!

    state: NoMatch
        event: noMatch
        a: Извините, я вас не понял.

подсказка

Стейт Start является родительским для стейта GetName. Стейты, вложенные в родительские, называются дочерними.

Параметры

к сведению

Параметры — пары «ключ — значение», которые отделяются от названия или значения тега (если оно есть) двумя вертикальными чертами. Если параметров несколько, они отделяются друг от друга запятыми. Параметры позволяют модифицировать поведение тега.

Для тега state могут быть заданы параметры:

Параметр	Тип	Описание	Значение по умолчанию
noContext	Логический	Если true, то после перехода в стейт контекст того, в каком стейте находится бот, не меняется.	false
modal	Логический	Если true, то стейт накладывает ограничения на то, в каких стейтах может быть обработан следующий запрос.	false
sessionResult	Строка	Результат, который присваивается диалогу при попадании в стейт.	—
sessionResultColor	Строка	Цвет метки с результатом в графическом редакторе J-Graph.	—

noContext

Если у стейта есть параметр noContext со значением true, то при переходе в такой стейт контекст того, в каком стейте находится бот, не меняется. Следующий запрос пользователя обрабатывается в контексте стейта, в котором бот находился до перехода.

Рассмотрим сценарий:

theme: /

    state: Greeting
        q!: * (прив*/добр* (~день/~утро/~вечер)) *
        a: Привет! Как дела?

        state: DoinGood
            q: * (хорош*/норм*/замечательн*) *
            a: Рад, что все в порядке! Как я могу помочь?

        state: DoinBad
            q: * (плох*/не [очень] хорош*) *
            a: Жаль это слышать. Может, я могу чем-то помочь?

    state: NoMatch || noContext = true
        event!: noMatch
        a: Извините, я вас не понял. Попробуйте переформулировать.

Предположим, что в ответ на вопрос Как дела? пользователь ответил Я в порядке. Паттерны во вложенных стейтах не предусматривают такого ответа, поэтому сценарий перешел в стейт NoMatch — бот попросил переформулировать ответ. Пользователь ответил У меня все хорошо.

Если бы у стейта NoMatch не было параметра noContext, то несмотря на то, что ответ пользователя соответствует паттерну в стейте DoinGood, он бы не распознался: контекст диалога ранее перешел в стейт NoMatch, из которого по тегу активации q стейт DoinGood недоступен.

С параметром noContext при попадании в NoMatch контекст диалога не меняется и остается в стейте Greeting. Ответ обрабатывается в нужном контексте и попадает во вложенный стейт DoinGood.

подсказка

Параметр noContext используется для стейтов, которые не должны продвигать диалог вперед: обычно это стейты для обработки нераспознанных запросов, переспросов в телефонном канале и т. д.

modal

Если у стейта есть параметр modal со значением true, то такой стейт накладывает ограничения на то, в каких стейтах может быть обработан следующий запрос пользователя. Когда контекст диалога находится в модальном стейте, переход возможен только:

• В стейты на первом уровне вложенности по отношению к модальному стейту.
• В стейты, в которые можно перейти из модального стейта по тегу с параметром fromState или toState.

предупреждение

• Ограничения модальных стейтов не распространяются на события. Если при нахождении в модальном стейте возникнет событие, для которого в любом стейте сценария предусмотрен стейт-обработчик, событие будет успешно обработано.

• Если среди достижимых стейтов нет стейтов для обработки запроса или события noMatch, то бот попытается перейти в глобальный стейт-обработчик события noMatch. Если такого стейта в сценарии нет, возникнет ошибка о том, что не найден стейт для перехода.

Рассмотрим сценарий:

theme: /

    state: OrderStatus || modal = true
        q!: * (где/статус) * [мой] ~заказ *
        a: Какой номер у вашего заказа?

        state: GetNumber
            q: * @duckling.number *
            a: Ваш заказ уже в пути!
            go!: /WhatElse

        state: LocalCatchAll
            event: noMatch
            a: Это не похоже на номер заказа. Попробуйте еще раз.

    state: WhatElse
        intent: /DontKnow || fromState = "/OrderStatus"
        a: Чем еще я могу помочь?

В этом сценарии пользователь может уточнить статус своего заказа, назвав его номер. У стейта OrderStatus есть параметр modal, поэтому диалог сможет выйти из него, только когда пользователь:

• Назовет номер заказа. Контекст перейдет в стейт WhatElse по go!.
• Скажет, что не знает номер. Контекст перейдет в стейт WhatElse по q с fromState.

подсказка

Параметр modal используется для стейтов, в которых от пользователя запрашивается важная информация, без получения которой диалог не может продолжаться.

sessionResult и sessionResultColor

Параметр sessionResult задает результат, который присваивается диалогу при попадании в стейт. Чаще всего это описание бизнес-результата, которого достигает бот, однако это может быть и свободный комментарий.

подсказка

То же назначение имеет метод $analytics.setSessionResult. Если у стейта есть и параметр, и вызов этого метода из тега script, то учитывается только вызов метода.

Опциональный параметр sessionResultColor задает цвет метки с результатом, которая отображается в графическом редакторе J-Graph. Значение параметра — HEX-код одного из цветов, доступных для выбора в J-Graph (например, #FFFFFF).

state: Feedback
    a: Довольны ли вы нашим сервисом?

    state: Positive || sessionResult = "Положительный отзыв", sessionResultColor = "#15952F"
        intent: /Yes
        a: Спасибо за отзыв! Всегда рады помочь!

    state: Negative || sessionResult = "Отрицательный отзыв", sessionResultColor = "#CD4C2B"
        intent: /No
        a: Сожалеем, что не смогли вам помочь. Что мы могли бы улучшить?