Documentation

Powered by Algolia

API Reference

Commands and responses

Intent

intent([filter,] pattern1 [, pattern2, ..., patternN], action)

Name Type Description
filter function Defines the conditions on when intent is available to be called.
pattern string Comma separated strings, each represents a pattern of a user voice input.
action function Defines what actions should be taken when one of the intent patterns is matched. Either anonymous arrow function or reply() function.

intent() is a predefined function where you define expected user inputs (patterns), conditions on when it will be available for the user (visual filters), and actions that should occur when user input matches one of the patterns.

Read more about intent() here.

Play

play([voice,] response1 [, response2, ..., responseN])
play(command)

Name Type Description
voice function Defines the language specific voice for natural pronunciation
response string/number Comma separated strings or numbers, each represents a pattern of a voice response from Alan
command object An arbitrary JSON object used to send commands to a client

Supported voice languages: en, fr, es, de, ru

play() is a predefined function used to generate voice responses or to send JSON commands to web/mobile client. If more than one response is passed to play() function - only one will be played at random.

Read more about play() here.

Question

question([filter,] pattern1 [, pattern2, ..., patternN], action)

Name Type Description
filter function Defines the conditions on when intent is available to be called.
pattern string Comma separated strings, each represents a pattern of a user voice input.
action function Defines what actions should be taken when one of the intent patterns is matched. Either anonymous arrow function or reply().

question() is a predefined function where you define expected user inputs (patterns), conditions on when it will be available for the user (visual filters), and actions that should occur when user input matches one of the patterns. Unlike intents and follows, questions has the lowest priority and can't be used to activate the context.

Read more about question() here.

Reply

reply(response1 [, response2, ..., responseN], follow1 [, follow2, ..., followN])

Name Type Description
response string Comma separated strings, each represents a pattern of a voice response from Alan.
follow function A follow() function available only if parent intent or follow has been called.

reply() is a predefined action function that will give one of the specified voice responses (at a random) to the user. And allows its follows to be called and matched, should one be provided.

Read more about reply() here.

Contexts

Follow

follow([filter,] pattern1 [, pattern2, ..., patternN], action)

Name Type Description
filter function Defines the conditions on when follow is available to be called.
pattern string Comma separated strings, each represents a pattern of a user voice input.
action function Defines what actions should be taken when follow patterns is matched. Either anonymous arrow function or reply().

follow() is a predefined function where you define expected user inputs (patterns), conditions on when it will be available for the user (visual filters), and actions that should occur when user input matches one of the patterns. Unlike intents, follows will only be available if the parent intent has been called or context containing it has been activated.

Read more about follow() here.

Then

then(context[, state])

Name Type Description
context function Represents the variable name where context was defined
state object Predefined object which exists in every context

then() is a predefined function that should be used to activate the context manually. You can pass the current state object to it, that will carry all the data that you have in the current context to the new one.

Read more about then() here.

Resolve

resolve([returnValue])

Name Type Description
returnValue object Represents the object that is returned to the parent context

resolve() is a predefined function that should be used to manually deactivate current context and return to its parrent context. You can pass any data to it, this data will be available in the parrent context.

Read more about resolve() here.

State

Each context has a special predefined object state. You can access it via p.state. This object should be treated as the knowledge base that is available to Alan in the current conversational context. You can store any data in it.

Read more about p.state here.

Fallback

fallback(pattern1 [, pattern2, ..., patternN])

Name Type Description
pattern string Comma separated strings, each represents a pattern of a voice response from Alan

For each context, you can define a fallback response which will be activated if this context is active and no intent,follow or question from this context has been matched.

Read more about fallback() here.

onEnter

onEnter(action)

Name Type Description
action function Defines what actions should be taken when context is activated

onEnter() is a special predefined function activated each time the script enters the context.

Read more about onEnter() here.

Title

title(contextName)

Name Type Description
contextName string Represents the name of the context that will be shown in logs

title() is a special predefined function that is used to name or label the context.

Read more about title() here.

Session-specific objects and methods

All of the session-specific object and methods are available from the predefined object p. All such methods and objects will persist during the user-session until it is terminated due to inactivity. Session is terminated after 30 minutes without a user command or if user force-quits the application.

userData

p.userData is a runtime object that can be used to store any data. You can access it at any time from any script of your project regarding of the context. Take a note that this data will be available only in a given user-session.

Read more about p.userData here.

authData

p.authData is a runtime object that should be used to provide static device- or user-specific data to the Alan script/project. If you need to receive dynamic data from the application - use Visual State instead.

visual

p.visual is a runtime object that contains an arbitrary JSON. It should be used to provide any dynamic data of the application state to the Alan script/project. You can read on how to use visual state here.

Read more about p.visual here.

Global objects and methods

project

project is a global object that can contain any data. When Alan is building a language model for your project it loads scripts in the order from top to bottom. This object will be available in any script that is below the script where it was defined and can be used to store data and methods that you might need in separate scripts in your project.

//script1
project.config = {initValue: 1};

//script2
console.log("Init value is " + project.config.initValue);

projectAPI

projectAPI.functionName = function(p, data, callback) {}

Name Type Description
p object Predefined object containing the user session data and methods
data object An object containing the data you want to pass to your script
callback function A callback function used to receive data back to the app

projectAPI is needed when you want to provide some data to your Alan Studio script or perform some script logic without a voice command from the user. This can be done by setting up the logic for projectAPI and then calling it with the Alan SDK method:

projectAPI.setToken = function(p, param, callback) {
    if (!param || !param.token) {
        callback("error: token is undefined");
    }
    p.userData.token = param.token;
    callback();
};

onCreate

onCreate(action)

Name Type Description
action function Defines what actions must be taken when a new user session/dialog is started

onCreate() is a special predefined function. When a client connects to the Alan Studio project, onCreate() is called and the configuration object provided by the client is passed to the p.authData session object.

onCreate((p) => {
    if (_.isEmpty(p.authData)) {
        p.authData.username = "DEFAULT_USER_NAME";
        p.authData.password = "DEFAULT_PASSWORD";
    }
});

Recognition hints

recognitionHints(recognitionHint1 [, recognitionHint2, ..., recognitionHintN])

Name Type Description
recognitionHint string Comma separated strings, each represents a pattern of a user voice input

recognitionHints are used to increase the accuracy of recognition of certain phrases that are expected from the user. This usually helps if the user is expected to use specific words and terms that are not used in everyday life, which leads to frequent errors in recognition.

recognitionHints("Open ICIK");

intent (`Open $(PARAM~ ICIK~ICIK)`, p => {
    p.play(`Opening ${p.PARAM.label}`);
});

Predefined callbacks

After you create a voice assistant with Alan, the dialog goes through several states: the project is created, the user connects to the dialog and so on. When the dialog state changes, you may want to perform some activities that are appropriate to this state. For example, when a new user connects to the dialog session, it may be necessary to set user-specific data.

To perform actions at different stages of the dialog lifecycle, you can use the following predefined callback functions:

onCreateProject

onCreateProject(()=> {action})

Name Type Description
action function Defines what actions must be taken when the project model is created on the server

onCreateProject is invoked when the project model is created on the server. You can use this function to perform activities that are required immediately after the project model is built, for example, for any data initialization.

In the example below, onCreateProject is used to define values for dynamic entities in the global scope.

onCreateProject(() => {
        project.drinks = "green tea|black tea|oolong";
    });

onCreateUser

onCreateUser(p => {action})

Name Type Description
p object Predefined object containing the user session data and methods
action function Defines what actions must be taken when a new user starts the dialog session

onCreateUser is invoked when a new user starts the dialog session. You can use this function, for example, to set user-specific data.

In the example below, the onCreateUser function is used to assign the value to the p.userData variable:

onCreateUser(p => {
            p.userData.favorites = "nature|landscape|cartoons";
        });

onCleanupUser

onCleanupUser(p => {action})

Name Type Description
p object Predefined object containing the user session data and methods
action function Defines what actions must be taken when the user disconnects from the dialog session or the dialog stops

onCleanupUser is invoked when the user disconnects from the dialog session or the dialog stops. You can use this function, for example, for cleanup activities.

In the example below, the onUserCleanup function is used to reset the p.userData variable value:

onCleanupUser(p => {
            p.userData.favorites = "";
        });

onVisualState

onVisualState((p, s) => {action})

Name Type Description
p object Predefined object containing the user session data and methods
s object JSON object passed in visualState
action function Defines what actions must be taken when visualState comes

onVisualState is invoked when the visualState object is set. You can use this function, for example, to process data passed in visualState.

In the example below, the onVisualState function is used to define values for dynamic entities created with the help of visualState.

onVisualState((p, s) => {
        if (s.values) {
            p.visual.ent = s.values.join('|');
        }
		else {
        p.visual.ent = "";
        }	
    });