API Reference

Data corpuses

Static corpus

Defines a corpus of static documents to be processed and indexed. For details, see Static corpus.

Syntax

Function syntax

corpus({ [title,] urls [, auth] [, include] [, exclude] [, depth] [, maxPages] [, query] [, transforms] [, priority] })

Function syntax

corpus({ [title,] text [, query] [, transforms] [, priority] })

Parameters

Name

Type

Required/Optional

Description

title

string

Optional

Corpus title.

urls

string array

Required

List of URLs from which information must be retrieved. You can define URLs of website folders and pages.

auth

JSON object

Optional

Credentials to access resources that require basic authentication: {username: 'johnsmith', password: 'password'}. For details, see Protected web resources.

include

string array

Optional

Resources to be obligatory indexed. You can define an array of URLs or use RegEx to specify a rule. For details, see Corpus includes and excludes.

exclude

string array

Optional

Resources to be excluded from indexing. You can define an array of URLs or use RegEx to specify a rule. For details, see Corpus includes and excludes.

query

function

Optional

Transforms function used to process user queries. For details, see Static corpus transforms.

transforms

function

Optional

Transforms function used to format the corpus output. For details, see Static corpus transforms.

depth

integer

Optional

Crawl depth for web and PDF resources. The minimum value is 0 (crawling only the page content without linked resources). For details, see Crawling depth.

maxPages

integer

Optional

Maximum number of pages and files to index. If not set, only 1 page with the defined URL will be indexed.

priority

integer

Optional

Priority level assigned to the corpus. Corpuses with higher priority are considered more relevant when user requests are processed. For details, see Corpus priority.

Name

Type

Required/Optional

Description

title

string

Optional

Corpus title.

text

plain text or Markdown-formatted strings

Required

Text corpus presented as plain text strings or Markdown-formatted strings.

query

function

Optional

Transforms function used to process user queries. For details, see Static corpus transforms.

transforms

function

Optional

Transforms function used to format the corpus output. For details, see Static corpus transforms.

priority

integer

Optional

Priority level assigned to the corpus. Corpuses with higher priority are considered more relevant when user requests are processed. For details, see Corpus priority.

Example

Dialog script
corpus({
    title: `HTTP corpus`,
    urls: [
        `https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview`,
        `https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages`,
        `https://developer.mozilla.org/en-US/docs/Web/HTTP/Session`],
    auth: {username: 'johnsmith', password: 'password'},
    include: [/.*\.pdf/],
   exclude: [`https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Evolution_of_HTTP`],
    query: transforms.queries,
    transforms: transforms.answers,
    depth: 1,
    maxPages: 5,
    priority: 0,
});
Dialog script
corpus({
    title: `HTTP corpus`,
    text: `
        # Understanding **async/await** in JavaScript

       **async/await** is a feature in JavaScript that makes working with asynchronous code easier and more readable. It allows you to write asynchronous code that looks and behaves like synchronous code, making it easier to follow and understand.

       ## How Does **async/await** Work?

       ### **async** Keyword:

       - The **async** keyword is used to declare a function as asynchronous.
       - An **async** function returns a **Promise**, and it can contain **await** expressions that pause the execution of the function until the awaited **Promise** is resolved.

       ### **await** Keyword:

       - The **await** keyword can only be used inside an **async** function.
       - It pauses the execution of the function until the **Promise** passed to it is settled (either fulfilled or rejected).
       - The resolved value of the **Promise** is returned, allowing you to work with it like synchronous code.

       ## Why Use **async/await**?

       ### Readability:

       - By using **async/await**, you can avoid the complexity of chaining multiple **.then()** methods when dealing with Promises.
       - Your code looks more like traditional synchronous code, making it easier to read.

       ### Error Handling:

       - Error handling with **async/await** is simpler and more consistent with synchronous code.
       - You can use **try/catch** blocks to handle errors.
    `,
    query: transforms.queries,
    transforms: transforms.answers,
    priority: 0,
});

Dynamic corpus

Defines a dynamic corpus of data to be processed.

The dynamic corpus allows retrieving JSON data from external data sources and using it to answer user queries in natural language. For details, see Dynamic corpus.

Syntax

Function syntax

corpus({ [title,] [input,] query [, output] [, transforms] [, priority] })

Parameters

Name

Type

Required/Optional

Description

title

string

Optional

Corpus title.

input

function

Optional

Function used to populate the Input field of the query transform.

query

function

Required

Transforms function used to process user queries and generate code to retrieve necessary data.

output

function

Optional

Function used to process obtained data, before it is passed to the transforms function.

transforms

function

Optional

Transforms function used to process and format data obtained with the query transform, and, optionally, the output function.

priority

integer

Optional

Priority level assigned to the corpus. Corpuses with higher priority are considered more relevant when user requests are processed. For details, see Corpus priority.

Example

Dialog script
corpus({
   title: `Infrastructure requests`,
   input: project.objects,
   query: transforms.vms_queries,
   output: project.cleanObjects,
   transforms: transforms.vms_answer,
   priority: 1
});

Corpus with the Puppeteer crawler

Defines a corpus of pages with complex structures or interactions.

The corpus with the Puppeteer crawler allows crawling specific page content and dynamically loaded resources and using the retrieved content to answer user queries. For details, see Puppeteer crawler.

Syntax

Function syntax

corpus({ [title,] urls, crawler [, auth] [, include] [, exclude] [, depth] [, maxPages] [, query] [, transforms] [, priority] })

Parameters

Name

Type

Required/Optional

Description

title

string

Optional

Corpus title.

urls

string array

Required

List of URLs from which information must be retrieved. You can define URLs of website folders and pages.

crawler

JSON object

Required

Type of crawler and function to be used to index corpus content. Crawler parameters:

  • puppeteer: function used to crawl data.

  • args: arguments to be passed to the crawler function.

  • browserLog: parameter to control the Puppeteer logging mode. Set the parameter to on to print logs from the browser interaction process to Alan Studio Logs, or off to disable logging.

auth

JSON object

Optional

Credentials to access resources that require basic authentication: {username: 'johnsmith', password: 'password'}. For details, see Protected web resources.

include

string array

Optional

Resources to be obligatory indexed. You can define an array of URLs or use RegEx to specify a rule. For details, see Corpus includes and excludes.

exclude

string array

Optional

Resources to be excluded from indexing. You can define an array of URLs or use RegEx to specify a rule. For details, see Corpus includes and excludes.

query

function

Optional

Transforms function used to process user queries. For details, see Puppeteer transforms.

transforms

function

Optional

Transforms function used to format the corpus output. For details, see Puppeteer transforms.

depth

integer

Optional

Crawl depth for web and PDF resources. The minimum value is 0 (crawling only the page content without linked resources). For details, see Crawling depth.

maxPages

integer

Optional

Maximum number of pages and files to index. If not set, only 1 page with the defined URL will be indexed.

priority

integer

Optional

Priority level assigned to the corpus. Corpuses with higher priority are considered more relevant when user requests are processed. For details, see Corpus priority.

Example

Dialog script
corpus({
    title: `Knowledge Base`,
    urls: [`urls to crawl`]
    crawler: {
        puppeteer: crawlPages(),
        browserLog: 'on',
        args: {arg1: 'value1', agr2: 'value2'},
    },
    auth: {username: 'johnsmith', password: 'password'},
    include: [/.*\.pdf/],
    exclude: [/.*\.zip/],
    query: transforms.queries,
    transforms: transforms.answers,
    depth: 10,
    maxPages: 10,
    priority: 1
});

async function* crawlPages({url, page, document, args}) {

    // crawlPages function code ...

}

api.sleep

Pauses the execution of the current script for the specified number of milliseconds.

Use api.sleep() in the data crawling function if a page takes a long time to load and there is no selector to wait for. For details, see Puppeteer crawler.

Syntax

Function syntax

api.sleep(time)

Parameters

Name

Type

Description

time

integer

Duration for which the script should be paused in milliseconds.

Example

Dialog script
async function* crawlKB({url, page, document}) {
    if (url.includes(`knowledge.hubspot.com/search?`)) {
        let linksSelector = `a.st-search-result-link`;
        await page.waitForSelector(linksSelector, { timeout: 20000 });
        const urls = await page.evaluate(() => {
            let linksSelector = `a.st-search-result-link`;
            return Array.from(document.querySelectorAll(linksSelector)).map(e=>e.href);
        });
        console.log(`# index [](${url}) => `, urls);
        yield {urls};
    } else if (url.includes(`knowledge.hubspot.com`)) {
        console.log(`# parse [](${url})`);
        await page.waitForSelector(`div.blog-post-wrapper.cell-wrapper`, {timeout: 20000});
        await api.sleep(4000);
        const html = await page.evaluate(() => {
            const selector = 'div.blog-post-wrapper.cell-wrapper';
            return document.querySelector(selector).innerHTML;
        });
        let content = await api.html2md_v2({html, url});
        yield {content, mimeType: 'text/markdown'};
    }
}

api.html2md_v2

Converts the HTML content into Markdown format, preserving the structure of the original HTML. For details, see Puppeteer crawler.

Syntax

Function syntax

api.html2md_v2(html [, url])

Parameters

Name

Type

Description

html

HTML string

A string of HTML content to be converted to Markdown.

url

URL

The URL of a crawled page. The function uses the URL of a crawled page to replace relative links with the full domain value.

Example

Dialog script
async function* crawlPages({url, page, document}) {
     const html = await page.evaluate(() => {
         const selector = 'div.content_col';
         return document.querySelector(selector).innerHTML;
     });
     let content = await api.html2md_v2({html, url});
     yield {content, mimeType: 'text/markdown'};
 }

Transforms

You can use the following function for data preprocessing and transformation: transforms.

transforms

Pre-processes and formats input data according to the defined template. For details, see Transforms.

Syntax

Function syntax

transforms.transformName({input, query})

Parameters

Name

Type

Description

tranformName

string

Name of the transform created in the AI agent project.

input

object

An object containing the data input passed to the transform.

query

function

An object containing the transform query.

Intent-driven dialogs

Intent

Defines a user command to perform. For details, see User commands.

Syntax

Function syntax

intent([filter,] [noctx,] pattern1 [, pattern2, …, patternN], action)

Parameters

Name

Type

Description

filter

function

Defines the conditions on when the intent can be invoked.

noctx

function

Signals that the intent must not switch the current context. For details, see noContext intents.

pattern

string

Comma separated strings, each represents a pattern invoking the intent.

action

function

Defines what actions must be taken when one of the intent patterns is matched. Either an anonymous arrow function or the reply() function.

Play

Provides a voice or text response or sends a JSON command to the client app. For details, see play().

Syntax

Function syntax

play([voice(lang),] response1 [, response2, …, responseN] [, opts(options)])

Or

Function syntax

play(command [, opts(options)])

Parameters

Name

Type

Description

voice

function

Settings defining how the voice of the agent must be customized. voice() takes the following settings:

  • language: language, or accent, in which the response must be played - en, fr, de, it, ru, es

  • gender: Voice gender - male or female

  • type: voice type - 0 (standard for the selected gender) or 1 (custom voice)

  • pitch: Speaking pitch in the range [-20.0, 20.0]

  • rate: Speaking rate in the range [0.25, 4]

For details, see Voice settings.

response

string/number

String representing a response from the AI agent.

command

object

An arbitrary JSON object used to send commands to the client app.

opts

function

Options defining how the play() function must be executed in the client app. opts() takes an object with the one or more options:

  • force:true: execute a command even if the agent button is not active in the client app

  • activate:true: activate the agent button in the client app before a response is played or command is executed

  • deactivate:true: deactivate the agent button in the client app after a response is played or command is executed

For details, see Play options.

Reply

Provides a voice or text response to the user. For details, see reply().

Syntax

Function syntax

reply(response1 [, response2, …, responseN])

Parameters

Name

Type

Description

response

string

String representing a response from the AI agent.

Contexts

Then

Activates the context in the dialog. For details, see Activating contexts.

Syntax

Function syntax

then(context[, state])

Parameters

Name

Type

Description

context

function

Represents the variable name with which context is defined.

state

object

Predefined object that exists in every context.

Resolve

Used to manually deactivate the current context in the dialog to return to the parent context. For details, see Exiting contexts.

Syntax

Function syntax

resolve([returnValue])

Parameters

Name

Type

Description

returnValue

object

Represents the object returned to the parent context.

Fallback

Handles situations when the AI agent cannot understand or process the user request effectively. For details, see Error handling and re-prompts.

Syntax

Function syntax

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

Parameters

Name

Type

Description

pattern

string

Comma separated strings, each represents a pattern of a response from Alan AI.

noContext

Encloses intents that should not change the current context, such as general questions in a conversation. For details, see noContext intents.

Syntax

Function syntax

noContext(() => {intent1 [, intent2, …, intentN]});

Parameters

Name

Type

Description

intent

function

An intent that must not switch the current context when invoked.

Title

Assigns a label or name to a context in the dialog script. For details, see Labeling contexts.

Syntax

Function syntax

title(contextName)

Parameters

Name

Type

Description

contextName

string

Represents the name of a context that will be shown in logs

State

Functions as the knowledge base available to the AI agent within the current dialog context. The state object can be used to store any relevant data. For details, see state.

Session-specific objects and methods

Session-specific objects and methods are accessible through the predefined p object. They persist throughout a user session, which lasts until either 30 minutes of inactivity or when the user ends the dialog with the AI agent and closes the app/AI chat.

userData

A runtime object used to store any relevant data. The data in p.userData is available only for the duration of the user session. You can access it at any time from any dialog script in the AI agent project, regardless of the context. For details, see userData.

authData

A runtime object used to store static data specific to the device or user, such as user credentials or product version. For details, see authData.

visual

A runtime object used to store any arbitrary JSON data. Use it to provide dynamic information about the app’s state or visual context to the AI agent. For details, see Visual state.

Global objects and methods

project

A global object used to store data that can be accessed by any dialog scripts in the project.

When Alan AI builds the dialog model, it loads scripts from top to bottom as listed in the scripts panel. As a result, the project object will be accessible in any script that follows the one where it was defined.

Dialog script
// Script 1
project.config = {initValue: 1};

// Script 2
console.log(`Init value is ${project.config.initValue}`);

project API

Allows sending data from the client app to the dialog script or executing script logic without a user command.

Define the logic using projectAPI in the dialog script and then invoke it with the callProjectApi() method in the Alan AI SDK. For details, see Project API.

Syntax

Function syntax

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

Parameters

Name

Type

Description

p

object

Predefined object containing the user session data and exposing Alan AI’s 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.

Example

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

Predefined callbacks

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

onCreateProject

onCreateProject is invoked when the dialog model for the dialog script is built. Use this function for activities that must be accomplished after the creation of the dialog model, such as data initialization.

Syntax

Function syntax

onCreateProject(()=> {action})

Parameters

Name

Type

Description

action

function

Defines what actions must be taken when the dialog model is created on the server in Alan AI Cloud.

Example

In the example below, onCreateProject is used to define values for project.drinks.

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

intent(`Get me $(DRINKS: ${project.drinks})`, p => {
    p.play(`Adding ${p.DRINKS.value} to your order...`)
});;

onCreateUser

onCreateUser is invoked when a new user starts a dialog session. Use this function to set up user-specific data.

Syntax

Function syntax

onCreateUser(p => {action})

Parameters

Name

Type

Description

p

object

Predefined object containing the user session data and exposing Alan AI’s methods.

action

function

Defines what actions must be taken when a new user starts a dialog session.

Example

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

Dialog script
onCreateUser(p => {
    p.userData.name = "John Smith";
});

onUserEvent((p, e) => {
    if (e.event == 'firstClick') {
        p.play(`Hi, ${p.userData.name}, how can I help you today?`);
    }
});

onCleanupUser

onCleanupUser is invoked when the user session ends. Use this function for cleanup tasks.

Syntax

Function syntax

onCleanupUser(p => {action})

Parameters

Name

Type

Description

p

object

Predefined object containing the user session data and exposing Alan AI’s methods.

action

function

Defines what actions must be taken when the user session ends.

Example

In the example below, the onCleanupUser function is used to reset p.userData.favorites value:

Dialog script
onCleanupUser(p => {
    p.userData.name = "";
});

onVisualState

onVisualState is invoked when the visual state object is set. Use this function to process any data stored in the visual state or to accomplish tasks to be performed when the new visual state is set.

Syntax

Function syntax

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

Parameters

Name

Type

Description

p

object

Predefined object containing the user session data and exposing Alan AI’s methods.

s

object

JSON object passed with the visual state.

action

function

Defines what actions must be taken when the visual state is sent.

Example

In the example below, when the user opens the Admittance section of the website, the AI agent plays a greeting to the user.

Setting the visual state in the app:

Client app
<script>
  function myFunction() {
    alanBtnInstance.setVisualState({"page": "admittance"});
  }
</script>

Playing a greeting in the dialog script:

Dialog script
onVisualState((p, s) => {
    if (p.visual.page === "admittance") {
        p.play("Hello there! I'm your AI agent, here to guide you through your journey towards academic success.")
    }
});

onUserEvent

onUserEvent is invoked when Alan AI emits an event driven by users’ interactions with the AI agent. For the events list, see User events.

Syntax

Function syntax

onUserEvent((p, e) => {action})

Parameters

Name

Type

Description

p

object

Predefined object containing the user session data and exposing Alan AI’s methods.

e

object

Event fired by Alan AI.

action

function

Defines what actions must be taken when the event is fired.

Example

In the example below, the AI agent listens to the firstClick event and, if the user activates the AI agent for the first time, plays a greeting to the user.

Dialog script
onCreateUser(p => {
    p.userData.name = "John Smith";
});

onUserEvent((p, e) => {
    if (e.event == 'firstClick') {
        p.play(`Hi, ${p.userData.name}, how can I help you today?`);
    }
});

onEnter

onEnter() is invoked when the dialog script enters a context. For details, see onEnter() callback.

Syntax

Function syntax

onEnter(action)

Parameters

Name

Type

Description

action

function

Defines what actions must be taken when the context is activated.

Example

In the example below, when the user enters the countContext, the p.state.result value is set to 0:

Dialog script
let countContext = context(() => {
    onEnter(p => {
        p.state.result = 0;
    });

    intent('Yes', p => {
        p.state.result += 1;
        p.play(p.state.result.toString());
    });
});

intent("Count the number of times I've said yes", p =>{
    p.play("Sure, let's go");
    p.then(countContext);
});

Debugging

console.log

Outputs informational messages to Alan AI Studio logs. Use console.log() for debugging purposes to display slot values, messages and other data.

Syntax

Function syntax

console.log(message)

Parameters

Name

Type

Description

message

string

Message to be logged.

Example

Dialog script
intent('Save this location as my $(LOCATION: home|office|work) address', p => {
    console.log(p.LOCATION.value);
    p.play('The location is saved');
})

console.error

Outputs error messages to Alan AI Studio logs. Use it to report errors or exceptions that occur during the dialog script execution.

Syntax

Function syntax

console.error(message)

Parameters

Name

Type

Description

message

string

Message to be logged.

Example

Dialog script
try {
    // your code
}
catch (e) {
    console.error(e)
}