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

visualStateData

object

JSON object that represents the visual state

Examples

Client app
alanBtnInstance.setVisualState({data:"your data"});

See also

How-to: Send information about the app visual context to the dialog script

Client app
- (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

Client app
func setVisualState() {
  /// Providing any params
  self.button.setVisualState(["data":"your data"])
}

See also

Client app
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

Client app
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

Client app
_MyHomePageState() {
  void _setVisualState() {
    /// Providing any params with json
    var visualState = jsonEncode({"data":"your data"});
    AlanVoice.setVisualState(visualState);
  }
}

See also

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.setVisualState({data: 'your data'});
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.setVisualState({data: 'your data'});

Ionic Vue

Client app
<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

Client app
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

method

string

Project API method name that is defined in the dialog script

data

object

Any object with arbitrary data that must be sent to the dialog script

callback

function

Callback to be called from the project API method

Dialog script
projectAPI.setClientData = function(p, param, callback) {
  p.userData.data = param.data;
  callback();
};

Examples

Client app
alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
  // Handling error and result
});

See also

Client app
- (void)callProjectApi {
  /// Providing any params
  [self.button callProjectApi:@"script::funcName" withData:@{@"data":@"your data"} callback:nil];
}

See also

Client app
func callProjectApi() {
  /// Providing any params
  self.button.callProjectApi("script::funcName", withData: ["data":"your data"], callback: nil)
}

See also

Client app
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

Client app
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

Client app
_MyHomePageState() {
  void _callProjectApi() {
    /// Providing any params with json
    var params = jsonEncode({"data":"your data"});
    AlanVoice.callProjectApi("script::setClientData", params);
  }
}

See also

Ionic Angular

Client app
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

Client app
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

Client app
<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

Client app
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

text

string

Text message to be played

Examples

Client app
alanBtnInstance.playText("Hi! I am Alan");

See also

How-to: Activate the Alan AI button programmatically and play a greeting

Client app
/// Playing any text message
- (void)playText {
  /// Providing text as string param
  [self.button playText:@"Hi"];
}
Client app
/// 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

Client app
/// Playing any text message
fun playText() {
  /// Providing text as string param
  alanButton?.playText("Hi")
}
Client app
/// Playing any text message
void playText() {
  /// Providing text as string param
  alanButton.playText("Hi");
}
Client app
_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

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.playText("Hi! I am Alan");
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.playText("Hi! I am Alan");

Ionic Vue

Client app
<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

Client app
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

text

string

Text message to be sent to Alan AI

Examples

Client app
alanBtnInstance.sendText("Hello, Alan, can you help me?");
Client app
/// Sending any text message
- (void)sendText {
  /// Providing text as string param
  [self.button sendText:@"Hello Alan, can you help me?"];
}
Client app
/// Sending any text message
func sendText() {
  /// Providing text as string param
  self.button.sendText("Hello Alan, can you help me?")
}
Client app
/// Sending any text message
fun sendText() {
  /// Providing text as string param
  alanButton?.sendText("Hello Alan, can you help me?")
}
Client app
/// Sending any text message
void sendText() {
  /// Providing text as string param
  alanButton.sendText("Hello Alan, can you help me?");
}
Client app
_MyHomePageState() {
  /// Sending any text message
  void _sendText() {
    /// Providing text as string param
    AlanVoice.sendText("Hello Alan, can you help me?");
  }
}

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.sendText("Hello, Alan, can you help me?");
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.sendText("Hello, Alan, can you help me?");

Ionic Vue

Client app
<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>
Client app
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

command

object

JSON object that represents a command

Examples

Client app
alanBtnInstance.playCommand({command:"navigate", screen: "settings"});
Client app
/// Executing a command locally
- (void)playCommand {
  /// Providing any params
  [self.button playCommand:@{@"action":@"openSomePage"}];
}
Client app
/// Executing a command locally
func playCommand() {
  /// Providing any params
  self.button.playCommand(["action":"openSomePage"])
}
Client app
/// 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)
}
Client app
/// 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);
}
Client app
_MyHomePageState() {
  /// Executing a command locally
  void _playCommand() {
    /// Providing any params with json
    var command = jsonEncode({"action":"openSomePage"});
    AlanVoice.playCommand(command);
  }
}

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.playCommand({command:"navigate", screen: "settings"});
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.playCommand({command:"navigate", screen: "settings"});

Ionic Vue

Client app
<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

Communication between components

Client app
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

Client app
 alanBtnInstance.activate();

See also

How-to: Activate the Alan AI button programmatically and play a greeting

Client app
/// Activating the Alan AI button programmatically
- (void)activate {
  [self.button activate];
}
Client app
/// Activating the Alan AI button programmatically
func activate() {
  self.button.activate()
}

See also

Tutorial: Playing a greeting in an iOS Swift app

Client app
/// Activating the Alan AI button programmatically
fun activate() {
  alanButton?.activate()
}
Client app
/// Activating the Alan AI button programmatically
void activate() {
  alanButton.activate();
}
Client app
_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

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.activate();
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.activate();

Ionic Vue

Client app
<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

Client app
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

Client app
alanBtnInstance.deactivate();
Client app
/// Deactivating the Alan AI button programmatically
- (void)deactivate {
  [self.button deactivate];
}
Client app
/// Deactivating the Alan AI button programmatically
func deactivate() {
  self.button.deactivate()
}
Client app
/// Deactivating the Alan AI button programmatically
fun deactivate() {
  alanButton?.deactivate()
}
Client app
/// Deactivating the Alan AI button programmatically
void deactivate() {
  alanButton.deactivate();
}
Client app
_MyHomePageState() {
  /// Deactivating the Alan AI button programmatically
  void _deactivate() {
    AlanVoice.deactivate();
  }
}

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.deactivate();
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.deactivate();

Ionic Vue

Client app
<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

Client app
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

Client app
alanBtnInstance.isActive();

See also

How-to: Activate the Alan AI button programmatically and play a greeting

Client app
[alanBtnInstance isActive];
Client app
alanBtnInstance.isActive()

See also

Tutorial: Playing a greeting in an iOS Swift app

Client app
alanButton?.isActive()
Client app
alanButton.isActive();
Client app
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

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.isActive();
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.isActive();

Ionic Vue

Client app
<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

Client app
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

Client app
alanBtnInstance.remove();

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.removeButton();
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.removeButton();

Ionic Vue

Client app
<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

Communication between components

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

Client app
BOOL enabled = [alanButton getWakewordEnabled];
Client app
let enabled = button.getWakewordEnabled()
Client app
var enabled = alanButton?.getWakewordEnabled()
Client app
boolean enabled = alanButton.getWakewordEnabled();
Client app
var enabled = await AlanVoice.getWakewordEnabled();

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  const isWakewordEnabled = await myAlanBtn.getWakewordEnabled();
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

const isWakewordEnabled = await alanBtnComponent.current.getWakewordEnabled();

Ionic Vue

Client app
<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>
Client app
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

enabled

boolean

Boolean value indicating whether the wake word is enabled or disabled.

Example

Client app
[alanButton setWakewordEnabled:YES];
Client app
alanButton.setWakewordEnabled(true)
Client app
alanButton?.setWakewordEnabled(true)
Client app
alanButton.setWakewordEnabled(true);
Client app
AlanVoice.setWakewordEnabled(enabled);

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.setWakewordEnabled(true);
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.setWakewordEnabled(true);

Ionic Vue

Client app
<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>
Client app
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

Client app
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

Client app
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 mode

  • false: 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

Client app
alanBtnInstance.textChat.setFullScreenMode(true);