Scenarios

In this article, you will find out how to write an avatar scenario, learn about avatar states and form states, and take a look at the complete avatar scenarios.

To write an avatar scenario, go to the Avatar section in the control panel, choose your avatar, and go into the Dialog scenario tab.

An avatar scenario consists of avatar states. A state is a part of a conversation between a user and an avatar designed for a specific goal, for example, greeting and finding the user intention, or getting the necessary information from the user.

An avatar can switch between these states when it finds an intent in user's speech. An intent is a user's intention to do something. You can read more about intents in the Avatar quickstart article.

In the end of an avatar scenario, you need to specify the initial state, that your avatar should choose when you launch it. To do this, use the setStartState method.

In general, an avatar scenario looks like this:

addState({
    name: 'state-one',
    // state logic
});

addState({
    name: 'state-two',
    // state logic
});

addState({
    name: 'state-three',
    // state logic
});

setStartState('state-one');

In the avatar scenario, there can be simple states and form states. Let us take a look at both of them one by one.

To add a simple state to the avatar scenario, use the addState method. A state needs to have a scenario-unique name parameter, and its callbacks, which specify what your avatar needs to do in a current state.

For example, let us write a simple state which makes an avatar ask user to have pizza.

When an avatar switches to a new state, it searches for the onEnter callback. In this callback, we want to return a phrase to suggest pizza, and then listen to the user's answer.

When a user answers, the avatar searches for the onUtterance callback. In this callback, we can say different phrases depending on what intents our avatar has recognized.

For example, our avatar has recognized the 'yes' intent. In this case, let us congratulate the user and tell that we are going to order it. After that, we exit the current state and go to another state called 'order' via the nextState parameter.

If our avatar has not recognized the 'yes' intent, we are going to accept it and not to continue the dialogue. Let us tell the user that we are sad and then transfer to the 'goodbye' state.

You can specify a specific utterance for the avatar to response in the utterance parameter or use the event.response value to take one of the responses from the intent.

Please notice that the nextState parameter is optional, and you can recognize a lot of different intents in a single state, providing different answers to each of them, without exiting the state.

The whole state is looking like this:

addState({
    name: 'pizza',
    onEnter: async (event) => {
        return Response({ utterance: 'Hey user! Do you want to eat pizza tonight?', listen: true });
    },
    onUtterance: async (event) => {
        if (event.intent === 'yes') {
            return Response({ utterance: 'Super cool! I am going to order it right now!', nextState: 'order' })
        } else {
            return Response({ utterance: 'Okay, stay hungry then.', nextState: 'goodbye' })
        }
    }
});

For your reference, here is a complete avatar scenario with multiple states and transfers between them.

A form state is designed to collect information of multiple fields from a user and fill the received information into a form.

Same as a simple state, the form state should have a scenario-unique form state name parameter, and the form state callbacks, but the callbacks differ from a simple state.

To add a form state to the avatar scenario, use the addFormState method.

For example, let us write a form state which collects a form for an appointment and asks for a time and a user name.

First, you need to specify the desired form fields into the parameters parameter. In our case, it is a time and a user name.

Each parameter has multiple fields. There are 4 required fields:

You can specify the number of attempts to fill the form in the attempts parameter. It is optional and the default value is 3 attempts. Please note, that each form field can have its own attempts parameter which can be different from the global parameter.

It may happen, that a user wants to cancel filling form. In this case, you need to specify the intent to cancel it in the exitIntents parameter. If the avatar recognizes this intent, it stops asking form questions.

To complete the form state, you need to process the following callbacks:

You can process the callbacks the same way you process simple state callbacks, responding to the user with a specific utterance, switching to another state via nextState, or listening to additional user utterances.

For your reference, here is a complete avatar form state code example with processing all the parameters and callbacks.

Please note, that the onEnter callback, which triggers when an avatar enters a new state, is not necessary for the form state. If you do not specify this callback, the avatar starts filling the form as soon it enters the form state. However, if you want to implement a custom logic at the form state start, you can do it in the onEnter callback.