Commands and responses¶

To let users interact with your in-app 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()
reply()

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 in-app 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 in-app 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 in-app assistant button is not active in the client app
`activate:true`	response, command	Activate the in-app assistant button in the client app before a response is played or command is executed
`deactivate:true`	response, command	Deactivate the in-app 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 in-app 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 in-app 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.