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's intention, or getting the necessary information from the user.

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

At 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 specifies what your avatar needs to do in a current state.

For example, let us write a simple state that makes an avatar ask a 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 them 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 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 respond 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.

If a user does not answer for a certain period, the onTimeout callback is executed. Voice avatar has a default timeout, but you can specify custom timeouts for each 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' })
        }
    },
    onTimeout: (event)=> {
        return Response({utterance: 'I could not hear you, could you repeat?', listen: true})
    },
});

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

Customer's response timeouts

You can set up timeouts for customer's responses to your avatar.

If you design your avatar manually, call the handleTimeout method in the VoxEngine scenario to invoke the onTimeout callback function, specified in the avatar scenario.

For VoiceAvatar, the handleTimeout method executes automatically after the timeout expires.

You can change the global timeout for all customer's responses by modifying the defaultListenTimeout parameter in the VoxEngine scenario. The default timeout value is 10 seconds. Optionally, you can specify different timeouts for each response in the listenTimeout parameter in the avatar scenario.

Voice and media player parameters

You can also specify voice and media player parameters for each Avatar's response.

To do that, add the channelParameters parameter to the Response in the avatar's state or even form state.

In this parameter, you can pass both voice and text settings. For voice parameters, you can specify the text to synthesize in the text parameter, and other parameters, such as voice and language, pitch, emotion and more.

In addition, in this parameter, you can specify settings for URL media player to play an audio file to your customer.

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 that collects a form for an appointment and asks for a time and a user name.

First, you need to specify the desired form fields to 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 out 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.

A user may want to cancel filling out the 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.

Same as for common state, you need to specify the onTimeout callback, so the avatar knows what to do if a customer does not say anything and the timeout occurs.

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 is triggered 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 out 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.

The same as for avatar states, you can specify the customer's answer timeout and voice and url player parameters in the form state.

Processing the results of the form state

You can get the result form of the form state at any stage of the dialogue.

To get the form, first, get the instance of the form state instance by its name via the getFormState method. After that, use the getParameters method to get the object with all the form fields, or use the getParameter method to get a specific parameter by its name.

You can process the results in any state or form state of the avatar, for example, in the onEnter callback, when your avatar enters the state, then process the results the way you need.