Powered by Algolia

Alan Web SDK

Alan Web SDK can bring voice to any website. It's a lightweight JavaScript library for adding a voice experience to your website or web application.


The Alan button can be added to your application as an NPM package or a javascript library. Check the instructions on how you can add the Alan button to the page:

NPM module

  1. Install @alan-ai/alan-sdk-web using NPM.

    $ npm install @alan-ai/alan-sdk-web --save
  2. Add div for appending the Alan button:

    <div class="alan-btn"></div>
  3. Import alanBtn function from the @alan-ai/alan-sdk-web package and add the Alan button to the page:

    import alanBtn from "@alan-ai/alan-sdk-web";
      key: "ALAN_STUDIO_API_KEY",
      rootEl: document.getElementById("alan-btn")

Browser library mode

Alan Web SDK can be also added to the page via the script tag. To do this:

  1. Add the script to the page:

      <script type="text/javascript"
  2. Add a div for appending the Alan button:

    <div class="alan-btn"></div>
  3. It will now be available as a global variable named alanBtn

    var alanBtnInstance = alanBtn({
      key: "ALAN_STUDIO_API_KEY",
      rootEl: document.getElementById("alan-btn"),

Alan button parameters

Name Type Description
key string The Alan SDK key for the Alan Studio project.
rootEl HTMLElement The element where Alan button will be added. If no rootEl is provided, the Alan button is added to the body.
onCommand function A callback for handling commands from the Alan voice script. In this callback, you can set up logic on how your app must react to commands received from the voice script. For details, see Sending commands to the application.
onConnectionStatus function Callback for receiving the connection status of the Alan button. For details, see Alan button status.

Example of using the onCommandCb callback:

  // Voice script
  intent("go back","go back to the previous screen", (p) => {"Navigating to the previous screen");{command:"go:back"});

  // Client-side script
  var alanBtnInstance = alanBtn({
    key: "0717498b05e694d0b083b897e50a49102e956eca572e1d8b807a3e2338fdd0dc/stage",
    onCommand: function (commandData) {
      if (commandData.command === "go:back") {
        // Call client code that will react to the received command
     rootEl: document.getElementById("alan-btn"),

Example of using the onConnectionStatus callback:

  var alanBtnInstance = alanBtn({
    key: "0717498b05e694d0b083b897e50a49102e956eca572e1d8b807a3e2338fdd0dc/stage",
    onConnectionStatus: function (status) {
       // status could be connected or disconnected
     rootEl: document.getElementById("alan-btn"),

Alan button methods

setVisualState (visualStateData: object)

Method for setting the visual state. For details, see Visual state.

visualStateData - data that represents a visual state

  //this is how you can set up a visual state
  alanBtnInstance.setVisualState({data:"your data"});

callProjectApi (method:string, data:object, callback:function)

Method for calling a project API defined in the script in the Alan Studio project. For details, see projectAPI.

method - projectAPI method name that was defined in the voice script

data - data that should be passed

callback - callback that could be called from project API method

  // Voice script
  projectAPI.setClientData = function(p, param, callback) {
    p.userData.value = param.value;

  // this is how you can call clientAPI.setClientData function
  alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
    //handle error and result here


Method for playing voice

text - text that should be played

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


Method for sending a command

command - object that represents a command

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


Method for turning on the Alan button programmatically



Method for turning off the Alan button programmatically



Method for checking 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.


Alan button status

When the user launches an app with the Alan button, Alan connects to the project in the Alan Cloud. Once the connection is established, the authorized status of the button is returned. If you need to perform any activities in the app after the connection is set, you can use the onConnectionStatus callback for the Alan button.

In the example below, onConnectionStatus is used to check the button status. When the status is set to authorized, the Alan button is activated programmatically with the activate() method and playText is invoked to play the greeting to the user.

useEffect(() => {
    let alanBtnInstance = alanBtn({
        key: 'ALAN_STUDIO_API_KEY',
        onCommand: (commandData) => {
            if (commandData.command === 'go:back') {
                // Call the client code that will react to the received command
        onConnectionStatus: async function(status) {
            if (status === 'authorized') {
                await alanBtnInstance.activate();
                alanBtnInstance.playText('Hey, this is Alan');
}, []);

Alan button position

By default, the Alan button is placed in the bottom right corner of the window. To change the Alan button position, you can use the following options for the alanBtn variable:

  • left: sets the Alan button position from the left edge
  • right: sets the Alan button position from the right edge
  • top: sets the Alan button position from the top edge
  • bottom: sets the Alan button position from the bottom edge
  • zIndex: sets the z-order of a the Alan button
var alanBtnInstance = alanBtn({
    key: "0717498b05e694d0b083b897e50a49102e956eca572e1d8b807a3e2338fdd0dc/stage",
    onConnectionStatus: function(status) {
        // status could be connected or disconnected
    rootEl: document.getElementById("alan-btn"),
    bottom: '50px',
	left: '50px',
    zIndex: 10

Microphone access for local deployments

If you embed the Alan button to a webpage or website stored locally, for example, for debugging purposes, you need to allow microphone access every time you activate the Alan button. To give microphone access permanently, in Safari, go to Safari > Preferences > Websites, select Microphone and change the microphone permission to Allow.