Commands and responses

To let users interact with your voice assistant, you need to add to the voice script commands that users can give. A voice command describes a task or action that the user wants to fulfil. Learn how voice commands can be defined and what response actions can be triggered for these commands.

Intent

You can define a voice command in the script with the intent() function. This function can be used to complete tasks requested by users or answer users’ questions.

In the intent() function, you must specify one or more patterns — user’s utterances that invoke the command, and one or more response actions that must be triggered when the command is invoked. In the example below, the command is invoked when the user says: Hello world. As a response action, Alan plays Hello to the user.

Voice script
intent('Hello world', p => {
    p.play('Hello');
});

When writing commands, you can add predefined and user-defined slots to intent patterns. Slots are ‘variables’ in user’s utterance that allow Alan to identify and retrieve useful information.

Voice script
intent('I want to go to $(LOC) on $(DATE)', p => {
    p.play(`Wait a second, I will check available flights on ${p.DATE.value} for you`);
});

Response

In Alan, you can trigger response actions for voice commands with the following functions:

Play

play() is a predefined function for response actions. You can use it to respond to the user or send commands to the client app.

Responding to the user

To play a response to the user, you need to define a pattern in the play() function. Alan will use this phrase as a response.

Voice script
intent('Talk to me', p => {
    p.play('Sure, what do you want to talk about?');
});

You can define more than one pattern. In this case, only one of them will be picked at random and played back to the user. To provide multiple patterns, separate them with a comma.

Voice script
intent('Talk to me', p => {
    p.play('Sure, what do you want to talk about?',
           'Sorry, I am not in the mood to talk to anyone');
});

You can also use slots in responses.

Voice script
intent('Say $(W hello|goodbye)', p => {
    p.play(`${p.W.value}`);
});

Sending commands to the app

The play() function can be used to send commands to the client app integrated with Alan. Such commands let you perform specific activities on the app side, for example, navigate to another page in the app, highlight UI elements on the screen and so on. This way, you can synchronize voice and visuals and create a multi-modal interface for your app.

To send a command, pass JSON to the play() function.

Voice script
intent('Open the menu', p => {
    p.play({command: 'navigate', screen: 'menu'});
    p.play('Opening the menu');
});

intent('Go back', p => {
    p.play({command: 'navigate', screen: 'back'});
    p.play('Going back');
});

To handle the command on the app side, you must define a handler for commands received from Alan’s voice script. For details, see onCommand handler.

When you send a command to the app, you most commonly accompany this command with Alan’s comment so that the user understands what actions are taking place at the moment. If you place the command before Alan’s message, Alan will send the command right after the intent is matched. If you place the command after Alan’s message, the command will be sent after the text has finished playing. For example:

Voice script
// Sending a command when the intent is matched
intent('Open the menu', p => {
    p.play({command: 'navigate', screen: 'menu'});
    p.play('Opening the menu');
});

// Sending a command after the message is played
intent('Open the menu', p => {
    p.play('Opening the menu');
    p.play({command: 'navigate', screen: 'menu'});
});

Specifying play options

By default, Alan plays a response or executes a command specified in the play() function only if the voice assistant button in the client app is active. To change this behavior, you can add the opts() parameter to the play() function. In the parameter, you need to specify one or more play options that define how the voice assistant must behave when the play() function is executed.

You can define the following options:

Option

Action type

Description

force:true

command

Execute a command even if the voice assistant button is not active in the client app

activate:true

response, command

Activate the voice assistant button in the client app before a response is played or command is executed

deactivate:true

response, command

Deactivate the voice assistant button in the client app after a response is played or command is executed

Let’s assume you want to allow users to set a timer that behaves in the following way:

  1. After the timer is set, the voice assistant button is deactivated.

  2. Once half the time is over, a command is sent to notify the user with a text message in the client app.

  3. Once the time is over, the voice assistant button is activated, the Time is over phrase is played, and the button is deactivated.

Voice script
intent('Set a 1 minute timer', p => {
    p.play({command: 'setTimer'});
    p.play('Sure, 1 minute, starting now',  opts({deactivate:true}));
    setTimeout(() => {
        p.play({command: 'notifyUser', text: 'You are half way there'}, opts({force:true}));
    }, 30000)
    setTimeout(() => {
        p.play({command: 'stopTimer'}, opts({force:true}));
        p.play('Time is up', opts({activate:true, deactivate:true}))
    }, 60000)
})

Reply

reply() is a predefined function that can be used if you only need to give a response to the user, without making any complex actions.

Voice script
intent('Hello world',
    reply('Hello'));

In the reply() function, you can use patterns and slots in the same way as in the play() function.

Voice script
intent('Say $(W hello|goodbye)',
    reply('$(W)'));

Note

You can pass multiple patterns as arrays to the reply() function. For details, see Multiple patterns.

Response accent

To make sure Alan sounds natural, you can determine the language-specific voice, or accent, in which Alan’s responses must be played. To do this, add the voice parameter to the play() function and define the necessary language code in it:

Voice script
intent('Say Good morning in Spanish', p => {
    p.play(voice('es'), 'Buenos dias');
})

Alan supports the following language accents:

  • English (en)

  • French (fr)

  • German (de)

  • Italian (it)

  • Portuguese (pt)

  • Russian (ru)

  • Spanish (es)

  • Turkish (tr)

Intent matching

Your project can have many voice commands. When the user gives a command, Alan matches the command to the most appropriate intent in the script. To do this, Alan evaluates every intent separately and assigns different weights, or match scores, to intents.

Match score values range from 1 — the most accurate match, to 0 — no match. The command with the highest score is selected as the best match.

In the example below, if the user asks: What is the weather?, the first intent will be selected as the best match. The second intent will not be matched since it contains more words than user’s utterance. And vice versa, if the user asks: What is the weather today?, the second intent will have a higher score since it is the most accurate match.

Voice script
intent('What is the weather?', p => {
    p.play('The weather is the day-to-day state of the atmosphere');
});

intent('What is the weather today?', p => {
    p.play('The weather today is great!')
});

Tip

To see the match score assigned to a voice command, in Alan Studio logs, click the command and check the Score field.