User commands

To define user commands, use the intent() function. This function allows you to complete tasks requested by users or answer the user’s questions.

In the intent() function, you must specify:

  • Pattern: the user’s phrase that invokes the command. You can specify one or more patterns in the intent() function.

  • Response: a response phrase or action that must be executed when the command is invoked.

In the example below, when the user asks: Who are you?, the intent is invoked and the AI agent replies: I am your AI agent:

Dialog script
intent('Who are you?', p => {
    p.play('I am your AI agent');
});

Command responses

To provide responses or execute actions for commands, use the following functions:

  • play(): use this function to provide a response to the user or send a command to the app

  • reply(): use this function to provide a response to the user

Play()

To provide a response to the user, add the play() function to intent() and define a response phrase:

Dialog script
intent('How can you help me?', p => {
    p.play('I can provide information, answer questions and offer suggestions');
});

The play() function can also be used to send commands to the client app integrated with Alan AI. Such commands let you perform specific actions in the app, for example, navigate to another page, highlight UI elements on the screen and so on. This way, you can synchronize user commands and visuals and design a multimodal AI experience for your app.

To send a command, pass a JSON object containing the command name and any further information to the play() function. To handle the command in the app and execute the requested action, you must add a handler for commands received from the dialog script. For details, see onCommand handler.

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

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

When you send a command to the app, you most commonly accompany this command with the AI agent comment so that the user understands what actions are taking place at the moment.

  • If you place the command before the AI agent message, Alan AI will send the command immediately when the intent is matched.

  • If you place the command after the AI agent message, the command will be sent after the message has been provided.

For example:

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

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

Note

To send a command to the app using Alan AI Chat, set the play options for the command to force:true. When you use the text interaction channel, the AI agent button is inactive, and commands cannot be executed unless the force option is enabled. For details, see Play options.

Reply

If you only need to respond to the user and do not need to take any action, add the reply() function to intent().

Dialog script
intent('Who are you?',
    reply('I am your AI agent'));