Powered by Algolia

Voice scripts

To let users interact with your application with their voice, you must create a voice script in Alan Studio. A voice script is a scenario by which the dialog with the user is carried out. It contains a set of commands that the user can execute and actions that must be taken in response to these commands.

Voice scripts are written in JavaScript. You can use Alan objects and entities and standard JavaScript means to write scripts. For details, see Server API.

In Alan, you can create custom scripts or use predefined scripts. Alan comes with a library of script templates that can give you a good example of how a voice script can be organized. You can add and remove predefined scripts from the project at any moment.

An Alan project can contain one or multiple voice scripts. Multiple scripts can be helpful, for example, if you want to split the project logic and separate configuration and data structures from utility functions. This will make your project more transparent and easier to support.

In projects with multiple scripts, scripts are loaded in the order they are set up, starting from the upper one. You can use the Alan built-in functionality to share data and make it accessible between scripts. For details, see Multiple scripts in the project.

To work with scripts in Alan Studio, you can do the following:

Managing scripts

To add a voice script to the Alan project:

  1. In Alan Studio, open the project to which you want to add a voice script.
  2. At the top of the left pane, click Add Script.
  3. Do either of the following:

    • To add a custom script, in the New script name field, enter the script name and click Add New Script.
    • To add a predefined script, in the Add script example list, select one or more scripts and click Add Predefined Scripts. For details, see Voice scripts examples.
You can rename a script or delete it from the project when necessary.
  • To rename a script, in the left pane, hover over the script name, click the options icon and select Rename.
  • To delete a script, in the left pane, hover over the script name, click the options icon and select Delete.
  • To discard the changes in the script and revert it to the latest saved state, in the left pane, hover over the script name, click the options icon and select Discard local changes.

Exporting scripts

You can export a copy of your scripts from the Alan project, for example, if you want to save some script version locally.

To export scripts from the Alan project:

  1. In Alan Studio, open the project from which you want to export scripts.
  2. In the left pane, select a script.
  3. At the bottom of the left pane, click Export. Alan will save a ZIP archive to the default downloads location on your computer. The archive will contain all scripts you have in the project.

Importing scripts

If you have an external file with a voice script, you can import it to work with it in Alan Studio. For example, you may want to import voice scripts that you exported from Alan Studio previously.

To import voice scripts to Alan Studio:

  1. In Alan Studio, open the project to which you want to import scripts.
  2. Drag one or more voice script files and drop them onto the Import button at the bottom left of Alan Studio. You can also click the Import button and select one or more files to be imported.
    Alan supports import of the following file types:

    • JS files
    • ZIP archives with voice scripts (JS files)

If an imported script has the same name as a script already added to the project, you can choose to replace the existing script or add the imported script as a copy.

Sharing and keeping scripts in GitHub

Alan Studio lets you integrate with GitHub to store voice scripts and share them with other people. This option can be helpful if you are working on a voice assistant in a team and want to safely merge every developer's work into a single project. You may also use it if you want to keep voice scripts in GitHub repositories, outside Alan Studio.

To integrate with GitHub:

  1. In Alan Studio, open your voice assistant project.
  2. In the left pane of the code editor, click Sync with GitHub.
  3. If you are not already signed in, sign in to GitHub.
  4. Agree to authorize Alan to access your GitHub account data.
  5. In the left pane of the code editor, click Add GitHub repo and in the displayed window, enter the URL of the repository in which you want to store voice scripts, for example:

Once you connect to a GitHub repository, Alan automatically pulls its content and displays it in the code editor. To work with voice scripts over GitHub, you can do the following:

  • To pull the latest version of voice scripts from the repository, in the left pane of the code editor, click Pull. If the script version in Alan Studio differs from the repository one, you can choose to get the repository version or keep the local version.
  • To push the updated script version to the repository, in the left pane of the code editor, click Push and enter a comment on the pushed changes.

Alan pushes changes with the -force flag set. Before you start working with the script, pull the latest version from the repository to make sure you do not overwrite important changes made by other team members.

Viewing the script flowchart

To get a visual representation of your voice script, you can use the flowchart panel in Alan Studio. The flowchart can help you better understand the script workflow, analyze its design and identify potential flaws.

The flowchart panel is located at the bottom right of the code editor. To expand it, in the bottom left corner of the panel, click the expand icon.

The flowchart presents the voice script as a diagram consisting of a set of blocks — the global context and user-defined contexts. The global context is depicted on the left, while user-defined contexts are available on the right. All voice commands added to the voice script belong to this or that context block.

User-defined contexts are connected to voice commands with arrows. This way, you can easily see from which place in the script a context is activated. In a script with a great number of contexts, the number of connections can be great as well. To see how a specific element is linked with others, hover over it, and all connections going from or pointing at it will be highlighted.

For even better visualization, Alan displays the following script objects in the flowchart:

  • Slots added to voice commands are presented as colored blocks inside commands.
  • Visual filters are presented in the block at the top left of the chart.
  • Project variables are presented in the block at the top right of the chart.

Visual filters and project variables are linked to voice commands in which they are used.

If the voice script contains no voice commands, only configuration and data structures, the flowchart will be empty.

Here are some tips you can follow when working with the flowchart:

  • To zoom in and out in the flowchart, click the plus and minus icons in the bottom left corner of the flowchart.
  • To go to the necessary line in the voice script, click the corresponding block or element in the flowchart.
  • And, vice versa, to see what element in the flowchart corresponds to a specific line of code in the script, in the bottom left corner of the flowchart, click the target icon so that it becomes enabled and then click the necessary line in the code editor. The corresponding element in the flowchart will be highlighted.
  • If a voice command has several alternatives, only the first command is displayed in the command block. The number of remaining alternatives is displayed at the right of the block. To see all possible variants, hover over the command block.
  • To make more room for the flowchart and the code editor, collapse the scripts list and, if you are not planning to test your voice commands, the Debug Chat. To do this, at the top of the code editor, click the left and right arrow buttons.

Changing the code editor theme and font size

If you want to change colors and the font size for the code in Alan Studio, you can do the following:

  • To choose another color theme, in the top right corner, click the menu button and select Color Theme > theme you want to apply.
  • To make the font size larger or smaller, in the top right corner, click the menu button and select Font Size > Small, Medium or Large.

Finding and replacing text

You can search for strings and words in your voice scripts and optionally replace them. To work with the search and replace tool, use the following shortcuts:

  • Ctrl + F or Cmd + F — open the search bar
  • Ctrl + Shift + F or Cmd + Shift + F — open the search and replace bar
  • Enter — move to the next occurrence
  • Shift + Enter — move to the previous occurrence
  • Enter — replace the current occurrence with a new string (the focus must be in the Replace field)
  • Ctrl + Alt + Enter or Cmd + Alt + Enter — replace all occurrences with a new string
  • Esc — close the search bar

Using shortcuts

While writing voice scripts, you can use the following shortcuts:

  • Ctrl + / or Cmd + / — comment out the selected line(s) of code
  • Ctrl + Del or Cmd + Del — delete the selected line(s) of code
  • Ctrl + Alt + L or Cmd + Alt + L — auto-format the selected block of code
  • Ctrl + S or Cmd + S — save the changes
  • Ctrl + left mouse click or Cmd + left mouse click on the function — navigate to the function definition
  • Shift + Backspace — navigate back