Angular

Integrating with Alan AI

To integrate an Angular app with Alan AI:

1. Add the Alan AI Web SDK to your app. You can do it in two ways:

   • With the npm package

   • In the browser library mode

   NPM package

   To install the Alan Web SDK with the npm package:

   1. In the Terminal, run the command:

      Terminal

      npm install @alan-ai/alan-sdk-web --save
      

   2. Import alanBtn to your Angular component:

      Client app

      import alanBtn from "@alan-ai/alan-sdk-web";
      

   Browser library mode

   To load the Alan AI Web SDK in the browser library mode, add the alan_lib.min.js library to the index.html file using the <script> tag:

   Client app

   <script type="text/javascript" src="https://studio.alan.app/web/lib/alan_lib.min.js"></script>
   

2. Add the Alan AI agentic interface to your component:

   Client app

   export class AppComponent {
   
     alanBtnInstance;
   
     constructor(){
       this.alanBtnInstance = alanBtn({
         key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
         host: 'v1.alan.app',
         onCommand: (commandData) => {
           if (commandData.command === 'go:back') {
             // Call the client code that will react to the received command
           }
         },
       });
     }
   }
   

Note

Regularly update the @alan-ai/alan-sdk-web package your project depends on. To check if a newer version is available, run npm outdated. To update the alan package, run npm update @alan-ai/alan-sdk-web. For more details, see npm documentation.

Specifying the Alan AI agentic interface parameters

You can specify the following parameters for the Alan AI agentic interface added to your app:

Name	Type	Description
key	string	The Alan AI SDK key for a project in Alan AI Studio.
host	string	The Alan AI Studio host to which the AI assistant button must connect, for example: 'v1.alan.app'.
theme	string	The default theme to be used for the Alan AI agentic interface and Text Chat, for example: 'light' or 'dark'.
authData	JSON object	The authentication or configuration data to be sent to the dialog script. For details, see authData.
rootEl	HTMLElement	The element where Alan AI agentic interface will be added. If no rootEl is provided, the Alan AI agentic interface is added to the body.
mode	string	Specifies how the Agentic Interface should be rendered. Use 'inlined' to render the Agentic Interface inline in the div. If not specified, the Agentic Interface will be rendered as popup.
chatEl	HTMLElement	The element where the Agentic Interface should be added if the mode is set to 'inlined'. This is a required parameter when mode is 'inlined'.
showOverlayOnMicPermissionPrompt	Boolean	The property signaling whether the overlay fade effect must be used when the microphone permission prompt in the browser is displayed. The overlay effect makes the prompt more noticeable and helps make sure users provide microphone access to the Agentic Interface.
onCommand	function	A callback for handling commands from the dialog script. In this callback, you can set up logic on how your app must react to commands received from the dialog script. For details, see onCommand handler.
onButtonState	function	A callback for receiving the connection state of the Alan AI agentic interface. For details, see onButtonState handler.
onConnectionStatus	function	A callback for receiving the connection state of the Agentic Interface project run in the Alan AI Cloud. For details, see onConnectionStatus handler.
onEvent	function	A callback responsible for handling events received from Alan AI. For details, see onEvent handler.
textChat	object	Provides additional configuration options and handlers for managing the Alan AI Agentic Interface. For details, see the table below.

textChat Properties

Name	Type	Description
closeDelay	number	Specifies the delay (in milliseconds) for the close animation in inline mode.
showBtnIfChatOpen	boolean	Determines whether the Agentic Interface should be shown in inline mode.
openByDefault	boolean	Indicates whether the Agentic Interface should be open or closed by default when rendered in inline mode.
onOpen	function	A callback function that is triggered when the Agentic Interface is opened.
onClose	function	A callback function that is triggered when the Agentic Interface is closed.
onMinimize	function	A callback function that is triggered when the Agentic Interface is minimized.

Changing the Alan AI agentic interface position

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

• left: sets the Alan AI agentic interface position from the left edge

• right: sets the Alan AI agentic interface position from the right edge

• top: sets the Alan AI agentic interface position from the top edge

• bottom: sets the Alan AI agentic interface position from the bottom edge

• zIndex: sets the z-order of the Alan AI agentic interface

Client app

alanBtn({
   key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
   bottom: '50px',
   left: '50px',
   zIndex: 10
});

Using client API methods

You can use the following client API methods in your Angular app:

• setVisualState()

• callProjectApi()

• playText()

• sendText()

• playCommand()

• activate()

• deactivate()

• isActive()

• remove()

• textChat.isAudioOutputEnabled()

• textChat.setAudioOutputEnabled()

• textChat.setFullScreenMode()

• textChat.open()

• textChat.close()

• textChat.minimize()

• textChat.clear()

• theme.setTheme(theme)

• theme.getTheme()

setVisualState()

Use the setVisualState() method to inform the Agentic Interface about the app’s visual context. For details, see setVisualState().

app.component.ts

export class AppComponent {

  alanBtnInstance;

  constructor(){
    this.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }

  public setVisualState() {
    this.alanBtnInstance.setVisualState({data: "your data"});
  }
}

app.component.html

<div>
  <a class="card" (click)="setVisualState()">
    <span>Set visual state</span>
  </a>
</div>

callProjectApi()

Use the callProjectApi() method to send data from the client app to the dialog script and trigger activities without voice and text commands. For details, see callProjectApi().

Dialog script

projectAPI.setClientData = function(p, param, callback) {
  console.log(param);
};

app.component.ts

export class AppComponent {

  alanBtnInstance;

  constructor(){
    this.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }

  public callProjectApi() {
    this.alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
      // handle error and result here
    });
  }
}

app.component.html

<div>
  <a class="card" (click)="callProjectApi()">
    <span>Call setClientData method</span>
  </a>
</div>

playText()

Use the playText() method to play specific text in the client app. For details, see playText().

app.component.ts

export class AppComponent {

  alanBtnInstance;

  constructor(){
    this.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }

  public playText() {
    this.alanBtnInstance.playText("Hello, I am Alan!");
  }
}

app.component.html

<div>
  <a class="card" (click)="playText()">
    <span>Play text</span>
  </a>
</div>

sendText()

Use the sendText() method to send a text message to Alan as the user’s input. For details, see sendText().

app.component.ts

export class AppComponent {

  alanBtnInstance;

  constructor(){
    this.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }

  public sendText() {
    this.alanBtnInstance.sendText("Hello Alan, can you help me?");
  }
}

app.component.html

<div>
  <a class="card" (click)="sendText()">
    <span>Send text</span>
  </a>
</div>

playCommand()

Use the playCommand() method to execute a specific command in the client app. For details, see playCommand().

app.component.ts

export class AppComponent {

  alanBtnInstance;

  constructor(){
    this.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
      onCommand: (commandData: any) => {
        if (commandData.command === 'goBack') {
          // Call client code that will react to the received command
        }
      },
    });
  }

  public playCommand() {
    this.alanBtnInstance.playCommand({command: "goBack"});
  }
}

app.component.html

<div>
  <a class="card" (click)="playCommand()">
    <span>Play command</span>
  </a>
</div>

activate()

Use the activate() method to activate the Alan AI agentic interface programmatically. For details, see activate().

app.component.ts

export class AppComponent {

  alanBtnInstance;

  constructor(){
    this.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }

  public activateButton() {
    this.alanBtnInstance.activate();
  }
}

app.component.html

<div>
  <a class="card" (click)="activateButton()">
    <span>Activate Alan AI agentic interface</span>
  </a>
</div>

deactivate()

Use the deactivate() method to deactivate the Alan AI agentic interface programmatically. For details, see deactivate().

app.component.ts

export class AppComponent {

  alanBtnInstance;

  constructor(){
    this.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }

  public deactivateButton() {
    this.alanBtnInstance.deactivate();
  }
}

app.component.html

<div>
  <a class="card" (click)="deactivateButton()">
    <span>Deactivate Alan AI agentic interface</span>
  </a>
</div>

isActive()

Use the isActive() method to check the Alan AI agentic interface state: active or not. For details, see isActive().

app.component.ts

export class AppComponent {

  alanBtnInstance;

  constructor(){
    this.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }

  public isActive() {
    console.log("The button is active: " + this.alanBtnInstance.isActive());
  }
}

app.component.html

<div>
  <a class="card" (click)="isActive()">
    <span>Check button state</span>
  </a>
</div>

remove()

Use the remove() method to remove the Alan AI agentic interface from the parent element. For details, see remove().

app.component.ts

export class AppComponent {

  alanBtnInstance;

  constructor(){
    this.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }

  public removeButton() {
    this.alanBtnInstance.remove();
  }
}

app.component.html

<div>
  <a class="card" (click)="removeButton()">
    <span>Remove Alan AI agentic interface</span>
  </a>
</div>

textChat.isAudioOutputEnabled()

Use the textChat.isAudioOutputEnabled() method to get the state of audio output for the Alan AI Agentic Interface. For details, see textChat.isAudioOutputEnabled().

Client app

alanBtnInstance.textChat.isAudioOutputEnabled()

textChat.setAudioOutputEnabled()

Use the textChat.setAudioOutputEnabled() method to enable or disable audio output for the Alan AI Agentic Interface. For details, see textChat.setAudioOutputEnabled().

Client app

alanBtnInstance.textChat.setAudioOutputEnabled(true)

textChat.setFullScreenMode()

Use the textChat.setFullScreenMode() method allows switching the Alan AI Agentic Interface between full-screen and normal view. For details, see textChat.setFullScreenMode().

Client app

alanBtnInstance.textChat.setFullScreenMode(true);

textChat.open()

Use the textChat.open() method to open the Alan AI Agentic Interface. For details, see textChat.open().

Client app

alanBtnInstance.textChat.open(); // Opens the Alan AI Agentic Interface

textChat.close()

Use the textChat.close() method to close the Alan AI Agentic Interface. For details, see textChat.close().

Client app

alanBtnInstance.textChat.close(); // Closes the Alan AI Agentic Interface

textChat.minimize()

Use the textChat.minimize() method to minimize the Alan AI Agentic Interface. For details, see textChat.minimize().

Client app

alanBtnInstance.textChat.minimize(); // Minimizes the Alan AI Agentic Interface

textChat.clear()

Use the textChat.clear() method to clear the Alan AI Agentic Interface. For details, see textChat.clear().

Client app

alanBtnInstance.textChat.clear(); // Clears the Agentic Interface history.

theme.setTheme(theme)

Use the theme.setTheme(theme) method to set the Alan AI Agentic Interface theme to either light and dark. For details, see theme.setTheme(theme).

Client app

alanBtnInstance.theme.setTheme('light');

theme.getTheme()

Use the theme.getTheme() method to retrieve the current theme of the Alan AI Agentic Interface. For details, see theme.getTheme().

Client app

alanBtnInstance.theme.getTheme(); // returns 'light' or 'dark'

Using handlers

You can use the following Alan AI handlers in your Angular app:

• onCommand handler

• onButtonState handler

• onConnectionStatus handler

• onEvent handler

onCommand handler

Use the onCommand handler to handle commands sent from the dialog script. For details, see onCommand handler.

Client app

this.alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onCommand: (commandData: any) => {
    if (commandData.command === 'go:back') {
      // Call client code that will react to the received command
    }
  },
});

onButtonState handler

Use the onButtonState handler to capture and handle the Alan AI agentic interface state changes. For details, see onButtonState handler.

Client app

this.alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onButtonState: function (e) {
    console.info('onButtonState', e);
  },
});

onConnectionStatus handler

Use the onConnectionStatus handler to capture and handle the connection status for the Agentic Interface project. For details, see onConnectionStatus handler.

Client app

this.alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onConnectionStatus: function(status) {
    console.log("The status is " + status);
  },
});

onEvent handler

Use the onEvent handler to capture and handle events emitted by Alan AI: get user’s utterances, Agentic Interface responses and so on. For details, see onEvent handler.

Client app

this.alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onEvent: function (e) {
    console.info('onEvent', e);
  },
});

What’s next?

Example apps

Find and explore examples of Agentic Interfaces in Alan AI GitHub.