Client API methods

Alan exposes a set of client API methods that you can use to enable communication between the client app and Alan and trigger voice 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 in-app assistant about the app’s visual context, for example, the currently active screen, state of the cart and so on.

On the voice script side, 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 voice 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 voice 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 voice 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 voice 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
setVisualState() {
  /// Providing any params with json
  AlanManager.setVisualState({"data":"your data"});
}

See also

callProjectApi()

Calls a project API method defined in the voice script in the Alan Studio project. Use the project API functionality to:

  • Pass arbitrary data from the app to the voice script

  • Trigger activities without a voice 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 voice script

data

object

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

callback

function

Callback to be called from the project API method
Voice 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
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 in-app assistant to play the text message, make sure the Alan 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 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 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
/// Playing any text message
playText() {
  /// Providing text as string param
  AlanManager.playText("Hi");
}

sendText()

Sends a text string passed to the method to Alan as the user’s input.

With this method, you can send text commands to Alan and allow users to type their requests instead of saying them with voice. To capture the user’s input and Alan’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

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

playCommand()

Executes a command locally in the client app. The command is handled by the onCommand handler.

For the in-app assistant to play messages provided in the command, make sure the Alan 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
/// Executing a command locally
playCommand() {
  /// Providing any params with json
  AlanManager.playCommand({"action":"openSomePage"})
}

activate()

Activates the Alan button programmatically.

Syntax

Function syntax

activate()

Example

Client app
 alanBtnInstance.activate();

See also

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

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

See also

Tutorial: Playing a greeting in an iOS Swift app

Client app
/// Activating the Alan button programmatically
fun activate() {
  alanButton?.activate()
}
Client app
/// Activating the Alan button programmatically
void activate() {
  alanButton.activate();
}
Client app
_MyHomePageState() {
  /// Activating the Alan button programmatically
  void _activate() {
    AlanVoice.activate();
  }
}

See also

How-to: Activate the Alan 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
/// Activating the Alan button programmatically
activate() {
  AlanManager.activate();
}

deactivate()

Deactivates the Alan button programmatically.

Syntax

Function syntax

deactivate()

Example

Client app
alanBtnInstance.deactivate();
Client app
/// Deactivating the Alan button programmatically
- (void)deactivate {
  [self.button deactivate];
}
Client app
/// Deactivating the Alan button programmatically
func deactivate() {
  self.button.deactivate()
}
Client app
/// Deactivating the Alan button programmatically
fun deactivate() {
  alanButton?.deactivate()
}
Client app
/// Deactivating the Alan button programmatically
void deactivate() {
  alanButton.deactivate();
}
Client app
_MyHomePageState() {
  /// Deactivating the Alan 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
/// Deactivating the Alan button programmatically
deactivate() {
  AlanManager.deactivate();
}

isActive()

Checks the Alan button state. Returns true if the Alan button is activated by the user or programmatically or false if the Alan button is deactivated by the user or programmatically.

Syntax

Function syntax

isActive()

Example

Client app
alanBtnInstance.isActive();

See also

How-to: Activate the Alan 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 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
AlanManager.isActive((error, result) => {
  if (error) {
    console.error(error);
  } else {
    console.log(result);
  }
})

remove()

Removes the Alan button.

Use this method to completely remove the Alan 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 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
AlanManager.getWakewordEnabled((error, result) => {
  if (error) {
    console.error(error);
  } else {
    console.log(`getWakewordEnabled ${result}`);
  }
});

setWakewordEnabled()

Enables or disables the wake word for the Alan 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

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
AlanManager.setWakewordEnabled(true);