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.
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.
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.
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.
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.
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.
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:
// 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¶
Note
At present play options are supported only on iOS and Android platforms.
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 |
|---|---|---|
|
command |
Execute a command even if the voice assistant button is not active in the client app |
|
response, command |
Activate the voice assistant button in the client app before a response is played or command is executed |
|
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:
After the timer is set, the voice assistant button is deactivated.
Once half the time is over, a command is sent to notify the user with a text message in the client app.
Once the time is over, the voice assistant button is activated, the
Time is overphrase is played, and the button is deactivated.
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.
intent('Hello world',
reply('Hello'));
In the reply() function, you can use patterns and slots in
the same way as in the play() function.
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:
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.
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.