Client API methods¶
Alan AI exposes a set of client API methods that you can use to enable communication between the client app and Alan AI and trigger activities on the client side.
The client API methods are supported on all platforms:
setVisualState()¶
Sets the visual state for the client app. Use this method to inform the AI agent about the app’s visual context, for example, the currently active screen, state of the cart and so on.
In the dialog script, the data passed with this method can be accessed through the visual object. For details, see Visual state.
Syntax
Function syntax
setVisualState(visualStateData:object)
Parameters
Name |
Type |
Description |
|---|---|---|
|
object |
JSON object that represents the visual state |
Examples
alanBtnInstance.setVisualState({data:"your data"});
See also
How-to: Send information about the app visual context to the dialog script
- (void)setVisualState {
/// Providing any params
[self.button setVisualState:@{@"data":@"your data"}];
}
See also
How-to: Send information about the app visual context to the dialog script
func setVisualState() {
/// Providing any params
self.button.setVisualState(["data":"your data"])
}
See also
fun setVisualState() {
/// Providing any params
val params = JSONObject()
try {
params.put("data", "your data")
} catch (e: JSONException) {
Log.e("AlanButton", e.message)
}
alanButton?.setVisualState(params.toString())
}
See also
How-to: Send information about the app visual context to the dialog script
void setVisualState() {
/// Providing any params
JSONObject params = new JSONObject();
try {
params.put("data","your data");
} catch (JSONException e) {
Log.e("AlanButton", e.getMessage());
}
alanButton.setVisualState(params.toString());
}
See also
How-to: Send information about the app visual context to the dialog script
_MyHomePageState() {
void _setVisualState() {
/// Providing any params with json
var visualState = jsonEncode({"data":"your data"});
AlanVoice.setVisualState(visualState);
}
}
See also
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.setVisualState({data: 'your data'});
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.setVisualState({data: 'your data'});
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
mounted : function() {
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.setVisualState({data: 'your data'});
}
});
</script>
See also
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
setVisualState() {
/// Providing any params with json
AlanManager.setVisualState({"data":"your data"});
}
See also
callProjectApi()¶
Calls a project API method defined in the dialog script in the Alan AI Studio project. Use the project API functionality to:
Pass arbitrary data from the app to the dialog script
Trigger activities without a voice or text command
For details, see Project API.
Syntax
Function syntax
callProjectApi(method:string, data:object, callback:function)
Parameters
Name |
Type |
Description |
|---|---|---|
|
string |
Project API method name that is defined in the dialog script |
|
object |
Any object with arbitrary data that must be sent to the dialog script |
|
function |
Callback to be called from the project API method |
projectAPI.setClientData = function(p, param, callback) {
p.userData.data = param.data;
callback();
};
Examples
alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
// Handling error and result
});
See also
- (void)callProjectApi {
/// Providing any params
[self.button callProjectApi:@"script::funcName" withData:@{@"data":@"your data"} callback:nil];
}
See also
func callProjectApi() {
/// Providing any params
self.button.callProjectApi("script::funcName", withData: ["data":"your data"], callback: nil)
}
See also
fun callProjectApi() {
/// Providind any params
val params = JSONObject()
try {
params.put("data", "your data")
} catch (e: JSONException) {
Log.e("AlanButton", e.message)
}
alanButton?.callProjectApi("script::funcName", params.toString())
}
See also
void callProjectApi() {
/// Providing any params
JSONObject params = new JSONObject();
try {
params.put("data","your data");
} catch (JSONException e) {
Log.e("AlanButton", e.getMessage());
}
alanButton.callProjectApi("script::funcName", params.toString());
}
See also
_MyHomePageState() {
void _callProjectApi() {
/// Providing any params with json
var params = jsonEncode({"data":"your data"});
AlanVoice.callProjectApi("script::setClientData", params);
}
}
See also
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.callProjectApi("myFunc", {myData: 123}, function (error, result) {
console.log("cb from myFunc was received", error, result);
});
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.callProjectApi("myFunc", {myData: 123}, function (error, result) {
console.log("cb from myFunc was received", error, result);
});
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
methods: {
callProjectApi() {
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.callProjectApi("setClientData", {data: "myData"}, function (error:any, result:any) {
console.log("cb from myFunc was received", error, result);
});
},
}
});
</script>
See also
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
callProjectApi() {
/// Providing any params with json
AlanManager.callProjectApi(
'script::setClientData', {"data":"your data"},
(error, result) => {
if (error) {
console.error(error);
} else {
console.log(result);
}
},
)
}
See also
playText()¶
Plays a text string passed to the method.
For the AI agent to play the text message, make sure the Alan AI button is activated. To check the button state and activate the button programmatically, use the onButtonState handler, isActive() and activate() client API methods.
Syntax
Function syntax
playText(text:string)
Parameters
Name |
Type |
Description |
|---|---|---|
|
string |
Text message to be played |
Examples
alanBtnInstance.playText("Hi! I am Alan");
See also
How-to: Activate the Alan AI button programmatically and play a greeting
/// Playing any text message
- (void)playText {
/// Providing text as string param
[self.button playText:@"Hi"];
}
/// Playing any text message
func playText() {
/// Providing text as string param
self.button.playText("Hi")
}
See also
Tutorial: Playing a greeting in an iOS Swift app
/// Playing any text message
fun playText() {
/// Providing text as string param
alanButton?.playText("Hi")
}
/// Playing any text message
void playText() {
/// Providing text as string param
alanButton.playText("Hi");
}
_MyHomePageState() {
/// Playing any text message
void _playText() {
/// Providing text as string param
AlanVoice.playText("Hi");
}
}
See also
How-to: Activate the Alan AI button programmatically and play a greeting
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.playText("Hi! I am Alan");
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.playText("Hi! I am Alan");
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
methods: {
playText() {
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.playText("Hi there!");
},
}
});
</script>
See also
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
/// Playing any text message
playText() {
/// Providing text as string param
AlanManager.playText("Hi");
}
sendText()¶
Sends a text string passed to the method to Alan AI as the user’s input.
With this method, you can send text commands to Alan AI and allow users to type their requests instead of saying them with voice. To capture the user’s input and Alan AI’s response, use the onEvent handler and the parsed and text events.
Syntax
Function syntax
sendText(text:string)
Parameters
Name |
Type |
Description |
|---|---|---|
|
string |
Text message to be sent to Alan AI |
Examples
alanBtnInstance.sendText("Hello, Alan, can you help me?");
/// Sending any text message
- (void)sendText {
/// Providing text as string param
[self.button sendText:@"Hello Alan, can you help me?"];
}
/// Sending any text message
func sendText() {
/// Providing text as string param
self.button.sendText("Hello Alan, can you help me?")
}
/// Sending any text message
fun sendText() {
/// Providing text as string param
alanButton?.sendText("Hello Alan, can you help me?")
}
/// Sending any text message
void sendText() {
/// Providing text as string param
alanButton.sendText("Hello Alan, can you help me?");
}
_MyHomePageState() {
/// Sending any text message
void _sendText() {
/// Providing text as string param
AlanVoice.sendText("Hello Alan, can you help me?");
}
}
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.sendText("Hello, Alan, can you help me?");
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.sendText("Hello, Alan, can you help me?");
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
methods: {
sendText() {
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.sendText("Hello, Alan, can you help me?");
},
}
});
</script>
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
/// Sending any text message
sendText() {
/// Providing text as string param
AlanManager.sendText("Hello Alan, can you help me?");
}
See also
How-to: Send text messages to Alan AI
playCommand()¶
Executes a command locally in the client app. The command is handled by the onCommand handler.
For the AI agent to play messages provided in the command, make sure the Alan AI button is activated. To check the button state and activate the button programmatically, use the onButtonState handler, isActive() and activate() client API methods.
Syntax
Function syntax
playCommand(command:object)
Parameters
Name |
Type |
Description |
|---|---|---|
|
object |
JSON object that represents a command |
Examples
alanBtnInstance.playCommand({command:"navigate", screen: "settings"});
/// Executing a command locally
- (void)playCommand {
/// Providing any params
[self.button playCommand:@{@"action":@"openSomePage"}];
}
/// Executing a command locally
func playCommand() {
/// Providing any params
self.button.playCommand(["action":"openSomePage"])
}
/// Executing a command locally
fun playCommand() {
/// Providing any params
val params = JSONObject()
try {
params.put("action", "openSomePage")
} catch (e: JSONException) {
e.message?.let { Log.e("AlanButton", it) }
}
alanButton?.playCommand(params.toString(), null)
}
/// Executing a command locally
void playCommand() {
/// Providing any params
JSONObject params = new JSONObject();
try {
params.put("action","openSomePage");
} catch (JSONException e) {
Log.e("AlanButton", e.getMessage());
}
alanButton.playCommand(params.toString(), null);
}
_MyHomePageState() {
/// Executing a command locally
void _playCommand() {
/// Providing any params with json
var command = jsonEncode({"action":"openSomePage"});
AlanVoice.playCommand(command);
}
}
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.playCommand({command:"navigate", screen: "settings"});
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.playCommand({command:"navigate", screen: "settings"});
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
methods: {
navigate() {
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.playCommand({command:"navigate", screen: "settings"});
},
}
});
</script>
See also
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
/// Executing a command locally
playCommand() {
/// Providing any params with json
AlanManager.playCommand({"action":"openSomePage"})
}
activate()¶
Activates the Alan AI button programmatically.
Syntax
Function syntax
activate()
Example
alanBtnInstance.activate();
See also
How-to: Activate the Alan AI button programmatically and play a greeting
/// Activating the Alan AI button programmatically
- (void)activate {
[self.button activate];
}
/// Activating the Alan AI button programmatically
func activate() {
self.button.activate()
}
See also
Tutorial: Playing a greeting in an iOS Swift app
/// Activating the Alan AI button programmatically
fun activate() {
alanButton?.activate()
}
/// Activating the Alan AI button programmatically
void activate() {
alanButton.activate();
}
_MyHomePageState() {
/// Activating the Alan AI button programmatically
void _activate() {
AlanVoice.activate();
}
}
See also
How-to: Activate the Alan AI button programmatically and play a greeting
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.activate();
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.activate();
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
mounted : function() {
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.activate();
}
});
</script>
See also
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
/// Activating the Alan AI button programmatically
activate() {
AlanManager.activate();
}
deactivate()¶
Deactivates the Alan AI button programmatically.
Syntax
Function syntax
deactivate()
Example
alanBtnInstance.deactivate();
/// Deactivating the Alan AI button programmatically
- (void)deactivate {
[self.button deactivate];
}
/// Deactivating the Alan AI button programmatically
func deactivate() {
self.button.deactivate()
}
/// Deactivating the Alan AI button programmatically
fun deactivate() {
alanButton?.deactivate()
}
/// Deactivating the Alan AI button programmatically
void deactivate() {
alanButton.deactivate();
}
_MyHomePageState() {
/// Deactivating the Alan AI button programmatically
void _deactivate() {
AlanVoice.deactivate();
}
}
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.deactivate();
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.deactivate();
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
methods: {
deactivate() {
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.deactivate();
},
}
});
</script>
See also
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
/// Deactivating the Alan AI button programmatically
deactivate() {
AlanManager.deactivate();
}
isActive()¶
Checks the Alan AI button state. Returns true if the Alan AI button is activated by the user or programmatically or false if the Alan AI button is deactivated by the user or programmatically.
Syntax
Function syntax
isActive()
Example
alanBtnInstance.isActive();
See also
How-to: Activate the Alan AI button programmatically and play a greeting
[alanBtnInstance isActive];
alanButton?.isActive()
alanButton.isActive();
void _checkIsActive() async {
var isActive = await AlanVoice.isActive();
if (isActive) {
_showDialog("Active");
} else {
_showDialog("NOT active");
}
}
See also
How-to: Activate the Alan AI button programmatically and play a greeting
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.isActive();
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.isActive();
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.isActive();
});
</script>
See also
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
AlanManager.isActive((error, result) => {
if (error) {
console.error(error);
} else {
console.log(result);
}
})
remove()¶
Removes the Alan AI button.
Use this method to completely remove the Alan AI button from the parent element (page).
Note
At present, this method is supported only on the Web platform.
Syntax
Function syntax
remove()
Example
alanBtnInstance.remove();
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.removeButton();
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.removeButton();
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.removeButton();
});
</script>
See also
getWakewordEnabled()¶
Checks the state of the wake word for the Alan AI button. Returns true if the wake word is enabled; false if the wake word is disabled.
Note
This method is supported on the iOS and Android platforms.
Syntax
Function syntax
getWakewordEnabled()
Example
BOOL enabled = [alanButton getWakewordEnabled];
let enabled = button.getWakewordEnabled()
var enabled = alanButton?.getWakewordEnabled()
boolean enabled = alanButton.getWakewordEnabled();
var enabled = await AlanVoice.getWakewordEnabled();
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
const isWakewordEnabled = await myAlanBtn.getWakewordEnabled();
});
Ionic React
const alanBtnComponent = useRef<any>(null);
const isWakewordEnabled = await alanBtnComponent.current.getWakewordEnabled();
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
const isWakewordEnabled = await alanBtnInst.getWakewordEnabled();
});
</script>
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
AlanManager.getWakewordEnabled((error, result) => {
if (error) {
console.error(error);
} else {
console.log(`getWakewordEnabled ${result}`);
}
});
setWakewordEnabled()¶
Enables or disables the wake word for the Alan AI button.
Note
This method is supported on the iOS and Android platforms.
Syntax
Function syntax
setWakewordEnabled(enabled:boolean)
Parameters
Name |
Type |
Description |
|---|---|---|
|
boolean |
Boolean value indicating whether the wake word is enabled or disabled. |
Example
[alanButton setWakewordEnabled:YES];
alanButton.setWakewordEnabled(true)
alanButton?.setWakewordEnabled(true)
alanButton.setWakewordEnabled(true);
AlanVoice.setWakewordEnabled(enabled);
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.setWakewordEnabled(true);
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.setWakewordEnabled(true);
Ionic Vue
<ion-content :fullscreen="true">
<alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>
<script lang="ts">
import {Components} from '@alan-ai/alan-button';
export default defineComponent({
const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
alanBtnInst.setWakewordEnabled(true);
});
</script>
import { NativeModules } from 'react-native';
const { AlanManager } = NativeModules;
AlanManager.setWakewordEnabled(true);
textChat.isAudioOutputEnabled()¶
Checks the state of audio output for the Alan AI Chat. Returns true if audio output is enabled; false if audio output is disabled.
Note
At present, this method is supported only on the Web platform.
Syntax
Function syntax
textChat.isAudioOutputEnabled()
Example
alanBtnInstance.textChat.isAudioOutputEnabled()
textChat.setAudioOutputEnabled()¶
Enables or disables audio output for the Alan AI Chat.
Note
At present, this method is supported only on the Web platform.
Syntax
Function syntax
textChat.setAudioOutputEnabled(enabled:boolean)
Example
alanBtnInstance.textChat.setAudioOutputEnabled(true)
textChat.setFullScreenMode()¶
Allows switching the Alan AI Chat interface between full-screen and normal view. The method accepts the following arguments:
true: sets the chat interface to full-screen modefalse: exits full-screen mode and returns the chat interface to its normal size
Note
At present, this method is supported only on the Web platform.
Syntax
Function syntax
textChat.setFullScreenMode(enabled:boolean)
Example
alanBtnInstance.textChat.setFullScreenMode(true);