--- title: Alan AI date: 2023-03-03 6:00:00 background: bg-[#4aa181] tags: - AI - AlanAI - Prompts - Tips categories: - Toolkit intro: This cheat sheet covers all major script concepts, client API methods, handlers and other tools to create a multimodal conversational experience with Alan AI --- ### Legend - ``pattern`` — phrase to invoke a voice/text command or a response to be played - ``value`` — specified value - ``params`` — passed parameters - ``action`` — action to be performed - ``output`` — data outcome - ``[...]`` — optional data or parameters Dialog script ------------- ### Intents & patterns Define a voice/text command to play a response ``` {.wrap} intent('pattern'[, 'patternN'], reply('pattern')) ``` Define a voice/text command to play a response or perform an action ``` {.wrap} intent('pattern'[, 'patternN'], p => { action }) ``` Define alternatives ``` {.wrap} intent('phrase1|phrase2') ``` Define optional words and phrases ``` {.wrap} intent('pattern (optional phrase|)') ``` ### Response functions Play a response (in case of multiple patterns, a response is picked at random) ``` {.wrap} reply('pattern'[, 'patternN']) ``` Play a response ``` {.wrap} p.play('pattern') ``` Define voice settings for the assistant reply: ``accent (en, fr, de, it, ru, es)``, ``gender (male/female)``, ``voice type``, ``speaking pitch``, ``speaking rate`` ``` {.wrap} p.play([voice(code, gender, type, pitch, rate), ]'pattern') ``` Define play options: ``force:true`` (execute if the button is inactive), ``activate:true`` (activate the button before), ``deactivate:true`` (deactivate the button after) ``` {.wrap} p.play('pattern'[, opts(options)]) ``` Send a command to the app ``` {.wrap} p.play({command:data}) ``` ### User-defined slots Define a static list of values expected in the input ``` {.wrap} $(SLOTNAME value1|value2) => p.SLOTNAME.value ``` Provide labels to classify or identify the slot values ``` {.wrap} $(SLOTNAME value1~label1|value2~label2) => p.SLOTNAME.label ``` Enable fuzzy matching to capture similar variants ``` {.wrap} $(SLOTNAME~ value1|value2) => p.SLOTNAME.value ``` Make a slot optional ``` {.wrap} $(SLOTNAME value1|value2|) ``` Capture several slot values ``` {.wrap} intent('$(SLOTNAME value1|value2) and $(SLOTNAME value1|value2 )') => p.SLOTNAME_ (array), p.SLOTNAME_[0].value, p.SLOTNAME_[1].value ``` ### Predefined slots Capture date values ``` {.wrap} $(DATE) => p.DATE.value, p.DATE.moment, p.DATE.luxon ``` Capture time values ``` {.wrap} $(TIME) => p.TIME.value, p.TIME.moment ``` Capture cardinal numbers ``` {.wrap} $(NUMBER) => p.NUMBER.value, p.NUMBER.number ``` Capture ordinal numbers ``` {.wrap} $(ORDINAL) => p.ORDINAL.value, p.ORDINAL.number ``` Capture locations ``` {.wrap} $(LOC) => p.LOC.value ``` Capture names ``` {.wrap} $(NAME) => p.NAME.value ``` ### Dynamic slots Define a dynamic slot at the project level ``` {.wrap} project.name = {en: "value1|value2|value3"} $(SLOTNAME p:name) => p.SLOTNAME.value ``` Define a dynamic slot at the dialog session level ``` {.wrap} p.userData.name = {en: "value1|value2|value3"} $(SLOTNAME u:name) => p.SLOTNAME.value ``` Get data for a dynamic slot with the visual state ``` {.wrap} let name = ["value1|value2|value3"] p.visual.data = {en: name}; $(SLOTNAME v:name) => p.SLOTNAME.value ``` Define a dynamic slot in a short form ``` {.wrap} project.name = {en: "value1|value2|value3"} $(p:name) => p.SLOTNAME.value ``` Define labels for dynamic slots: see [User-defined slots](#user-defined-slots). Enable fuzzy matching for dynamic slots: see [User-defined slots](#user-defined-slots). Make a dynamic slot optional: see [User-defined slots](#user-defined-slots). Capture several slot values: see [User-defined slots](#user-defined-slots). ### RegEx slots Capture digit and/or letter combination ``` {.wrap} const reg = "([A-Za-z]{1}\\s?){6}" $(SLOTNAME* ${reg}) => p.SLOTNAME.value ``` Capture any user’s input ``` {.wrap} $(SLOTNAME* .+) => p.SLOTNAME.value ``` ### Contexts Define a context ``` {.wrap} let contextName = context(() => { action }) ``` Activate a context ``` {.wrap} intent('pattern', p => {..., p.then(contextName)} ``` Pass data to the context ``` {.wrap} p.then(contextName, state: {data:yourData}) => p.state.data ``` Resolve a context ``` {.wrap} p.resolve([data:yourData]) ``` Reset a context ``` {.wrap} p.resetContext() ``` Define intents to be matched at any time without switching the current context ``` {.wrap} intent(noctx, 'pattern', ...) or noContext(() => {intent(...)}) ``` Play a prompt for an expected input ``` {.wrap} fallback('pattern1'[, 'patternN']) ``` Title a context ``` {.wrap} title('contextName') ``` ### Predefined objects Store static device- and user-specific data passed from the client app ``` {.wrap} authData.data => p.authData.data ``` Store state data to be available globally at the project scope ``` {.wrap} project.info = {data:yourData} => project.info.data ``` Store the intent match score ``` {.wrap} p.score ``` Store data to be passed between contexts ``` {.wrap} p.state.data ``` Store visual context data to be passed from the client app with ``setVisualState()`` ``` {.wrap} p.visual.data ``` Store user-specific state data to be accessible during the dialog session ``` {.wrap} p.userData.data ``` ### Predefined callbacks Define actions to be performed when the script is saved and dialog model is built ``` {.wrap} onCreateProject(() => { action }) ``` Define actions to be performed when the dialog session starts ``` {.wrap} onCreateUser((p) => { action }) ``` Define actions to be performed when the dialog session ends ``` {.wrap} onCleanupUser((p) => { action }) ``` Define actions to be performed when the visual state is set ``` {.wrap} onVisualState((p, s) => { action }) ``` Define actions to be performed when a user event is triggered in the client app: ``buttonReady``, ``buttonClicked``, ``micPermissionPrompt``, ``micAllowed``, ``firstActivate``, ``showPopup``, ``popupCloseClicked``, ``recognized`` ``` {.wrap} onUserEvent((p, e) => { action }) ``` Define actions to be performed when a context is activated ``` {.wrap} onEnter((p) => { action }) ``` ### Q&A service Define a URL of a resource to be indexed ``` {.wrap} corpus({url: url, depth: depthLevel}) ``` Define text corpus to be used by the assistant in the dialog ``` {.wrap} corpus('text') ``` ### Built-in JS libraries Make API calls ``` {.wrap} axios, request ``` Work with time ``` {.wrap} moment-timezone, luxon ``` Work with arrays, numbers, objects, strings and so on ``` {.wrap} lodash ``` ### Other Provide a list of hints to help recognize specific terms ``` {.wrap} recognitionHints('hint'[, 'hintN']) ``` Write info messages to Alan Studio logs ``` {.wrap} console.log(data) ``` Write error messages to Alan Studio logs ``` {.wrap} console.error(data) ``` Client SDK ---------- ### Client API methods Send information about the visual state from the client app to the dialog script ``` {.wrap} setVisualState(visualStateData:object) ``` Send data or perform actions without a voice/text command ``` {.wrap} projectAPI.method = function(p, param, callback) { p.userData.data = param.data; callback(); }; callProjectApi(method:string, data:object, callback:function) ``` Play a text message in the client app ``` {.wrap} playText(text:string) ``` Send a text message to Alan as the user’s input ``` {.wrap} sendText(text:string) ``` Execute a command in the client app ``` {.wrap} playCommand(command:object) ``` ### Client API methods (continued) Activate the Alan button programmatically ``` {.wrap} activate() ``` Deactivate the Alan button programmatically ``` {.wrap} deactivate() ``` Check the Alan button state ``` {.wrap} isActive() ``` Remove the Alan button from the parent element, page (supported on Web, Ionic) ``` {.wrap} remove() ``` Check the state of the wake word (supported on iOS, Android) ``` {.wrap} getWakewordEnabled() ``` Set the state of the wake word (supported on iOS, Android) ``` {.wrap} setWakewordEnabled(enabled:boolean) ``` ### Handlers // Examples are provided for the Web platform Handle commands sent from the dialog script to the client app ``` {.wrap} onCommand: function (commandData) { action } ``` Handle Alan button state changes ``` {.wrap} onButtonState: function (e) { action } ``` Handle connection status to the virtual assistant project in the Alan Cloud ``` {.wrap} onConnectionStatus: function (e) { action } ``` Handle events received from Alan ``` {.wrap} onEvent: function (e) { action } ``` Also see -------- - [Alan AI website](https://alan.app) - [About the Alan Platform](https://alan.app/platform) - [Alan AI documentation](https://alan.app/docs)