---
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)