Rate this page:


This article will help you to start with Voximplant Avatar.

Avatar is a virtual assistant based on AI and NLP, that you can integrate into a voice or text channel. To understand, how avatar works, you need to learn about avatar intents and scenarios.

Avatar limits

Each account can have up to 32 avatar applications.


Copy URL

Create an avatar from template

Copy URL

You can create an avatar manually or use one of the existing templates. A template creates a ready-to-use avatar with a scenario, all necessary intents and entities, so you can integrate it right away.

Additionally, you can modify the template's scenario and intents to customize your avatar.

To use a template:

  1. Log in to your control panel
  2. In the main menu, go to the Templates section
  1. Choose one of the avatar templates and click on it
  2. Read the avatar description and if it suits you, click the Install button.
  3. Specify the avatar's settings: language, time zone, and type: chatbot or omnichannel bot.
  4. Click Create.

Your avatar is ready! After you open it, you can test the bot in the Debug mode, and integrate it into your product.

Debug in multiple windows

You cannot open the debug window in multiple windows. Use only one window in the debug mode to test your avatar.

Create an avatar manually

Copy URL

If you want to create an avatar manually, you need to create an avatar instance, write an avatar scenario, create intents, and integrate it with your telephony or chat.

Let us create a first-line support robot for a restaurant. The robot handles:

  • Questions about open hours (intent - “openHours”)

  • Questions about delivery options (intent - “delivery”)

  • Reservation requests (intent - “reservation”)

Create an avatar

Go to the Avatar section of the control panel and click the Create button. Enter your avatar name and click Create again.

Create an avatar
Avatar limits

An avatar application's name cannot be more than 128 characters.

Now you have an empty avatar with predefined basic intents and a basic dialog scenario.

Set up intents

To add an intent, click the Add intent button, type “open_hours” in the modal window, and click Create:

Create an intent

Now you can set up your intent by adding phrases a user might say and default responses to those phrases.

Add 10-20 training phrases, for example:

  • What are your opening hours?

  • Do you work tomorrow?

  • How late are you open tonight?

Add training phrases

Then go to the Responses tab and add a default response: "We are open every day from 7 am till 9 pm."

Repeat this procedure for “delivery” and “reservation” intents. So as not to have to do it manually, import all the data from this file by clicking the Import button.

Import training phrases

When you add the data you will see the “Training required” hint.

Training required

This means that you need to retrain your neural network with the added data. So click on it and wait till the training finishes.

Training in progress

Your avatar is ready to handle natural speech so let’s jump into building a scenario.

Write a dialog scenario

Go to the Dialog scenario tab. Here you will find the default conversation scenario that needs to be replaced with yours. Let’s start with a very simple one-state dialog.

Here your avatar will greet the user upon entering the state, and if they say something that fits into the list of utterances, it responds with a default response defined in the UI on the previous step. If the intent is unknown, it returns ‘can’t get that' and continues listening.

Modifying scenario

Modifying scenario

Key points:

  • addState registers a dialog state. The dialog can be in only one state at a time. А state defines the avatar's reactions to user inputs.

  • onEnter callback is called when the dialog enters a state. It is like a doorway where you can greet the user.

  • onUtterance callback is called when the user says something to the avatar (when the dialog is in a certain state). Here you can check what the user intent is, which entities are extracted, and then respond.

  • onTimeout is called when the state reaches its timeout. You can specify a custom timeout for each state, or for voice avatar, there is a default timeout.

  • Response generates a special object that defines the avatar reaction upon triggering the handler. Using it, you can return the utterance to be sent to the user, set the listen flag that specifies whether the avatar should listen to further user input, and set nextState indicating the state to which the dialog should jump.

  • setStartState defines the dialog entry point.


If you do not specify the onTimeout callback in the avatar's state, the avatar crashes after reaching the timeout.

Time to test your avatar! To do this, save your scenario and click Debug. This dialog box pops up:

Test your avatar

Type some questions and check if your avatar responds correctly:

Chat with your avatar
Avatar limits

You can have only one avatar debug session per account.

All works but you need to add exit points to the scenario to make it not infinite. For example:

  • If the avatar did not understand the user 3 times.

  • When you ask the user “Can we help you with anything else?“, and the user says 'no'.

With these exit points, the scenario becomes a bit more complex. See what you should do here:

  1. Check if the entry state is entered for the first time. If yes, let your avatar greet the user; if no, let it ask if the user needs help with something else. For this purpose, use visitsCounter and increment it every time the dialog enters the state.
  2. In the onUtterance handler, add a branch to handle the “no“ and “yes” intents for “can I help you with something else?“. Depending on the response, finish the dialog (by going to the final state) or continue the conversation.
  3. Every time the user says something while the dialog stays in the same handler, increment utteranceCounter. When leaving the handler, reset it. So if the user says something unknown again and again without leaving the handler, this counter will grow. When it becomes equal to 3, the avatar stops the dialog.
  4. The final state of the dialog causes termination. You can pass some additional information to the scenario at this state. For example, you can add a custom key – needRedirectionToOperator.
Adding exit points

Adding exit points

Enable reservations

Now your avatar can understand user intents and respond to them, so it is time to teach it how to book tables.

  1. Track the conversation context alongside the conversation state when filling out the reservation form. To do this, declare the reservationForm object at the very beginning of the scenario. Use it to store all the collected information about the reservation.

  2. Since the user can request a reservation with both phrases: “Can I book a table?“ (no parameters) and “Can I book a table for two?“ (people: 2), start collecting extracted entities (date and a number of people) from the very first phrase in the onUtterance handler of the start state. Store the collected info in the reservation form.

  3. In the new reservation state, formulate a question for the user depending on the info in the form. If the user does not answer and the weirdUtterancesInRow counter overflows, stop trying to complete the form and return to the start state.

  4. In the onUtterance handler of the reservation state, check if the requested information is given through entities. If yes, add it to the form and continue the loop. If not, increment the weirdUtterancesInRow counter to avoid getting stuck in an endless loop.

  5. At the same time the avatar can continue answering clarifying questions without stopping the form-filling process, using the intent check in the onUtterance handler.

  6. In the reservationConfirm state, double-check the provided information. If everything is ok, ask if you can help with something else by returning to the start state.

  7. The final state passes the information from the form to the scenario. Alternatively, you can send it to your CRM/backend right from the avatar scenario by calling the httpRequest method.

Enabling reservations

Enabling reservations

Now, you have a fully functional bot with a complex scenario that supports a flexible and natural flow of dialog. Let’s integrate it with telephony.

Integrate with telephony and chat

You have two integration options:

  • Using the Avatar class - you will have fine-grained control over integration

  • Using the VoiceAvatar class - it already has ASR + TTS integration with telephony and avatar logic

Let’s implement the second one.

To do that:

  1. Copy the code from the Integration section of your avatar.
  2. Create a platform scenario and paste the code there.
  3. Specify ASR and TTS options in the configuration step (select a language and voice).
  4. Set everything up to handle calls via this scenario and test it.

The complete VoxEngine scenario for Avatar will look like this:

VoxEngine scenario

VoxEngine scenario

Congratulations! Now you can call your avatar and have a voice conversation with it.

Refer to the AvatarEngine and VoxEngine.VoximplantAvatar API references to create a more complex solution.

See also

Copy URL