JavaScript¶

You can integrate a simple HTML page with Alan using JavaScript without any frameworks.

Integrating with Alan AI¶

You can add the Alan AI button to your page in two ways:

With the npm package
In the browser library mode

NPM package

In the Terminal, run the command:

Terminal¶

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

Add a <div> for appending the Alan button:
Client app¶
```
<div class="alan-btn"></div>
```

Import the alanBtn function from the @alan-ai/alan-sdk-web package and add the Alan button to the page:

Client app¶

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

var alanBtnInstance = alanBtn({
  key: "YOUR_KEY_FROM_ALAN_STUDIO_HERE",
  host: "v1.alan.app",
  onCommand: function (commandData) {
    if (commandData.command === "go:back") {
      // Call the client code that will react to the received command
    }
  },
  rootEl: document.getElementById("alan-btn"),
});

(For Alan AI Web Chat) Add a link to the font to the <head> section of the HTML page:

Client app¶

<link href="https://fonts.googleapis.com/css2?family=Poppins:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap" rel="stylesheet">

Browser library mode

Add the <script> tag to the page:

Client app¶

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

Add a <div> for appending the Alan button:
Client app¶
```
<div class="alan-btn"></div>
```

Add the Alan AI button in the <script> tag like this:

Client app¶

<script>
  var alanBtnInstance = alanBtn({
    key: "YOUR_KEY_FROM_ALAN_STUDIO_HERE",
    host: "v1.alan.app",
    onCommand: function (commandData) {
      if (commandData.command === "go:back") {
        // Call the client code that will react to the received command
      }
    },
    rootEl: document.getElementById("alan-btn"),
  });
</script>

(For Alan AI Web Chat) Add a link to the font to the <head> section of the HTML page:

Client app¶

<link href="https://fonts.googleapis.com/css2?family=Poppins:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap" rel="stylesheet">

Note

Mind the following:

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.
If you add the Alan button to a multi-page app or website, the Alan button will be reloaded on every redirect or page refresh. To store and access the data required for the dialog session, use the localStorage and sessionStorage objects. Alternatively, you can design your project as a single-page app.

Specifying the Alan AI button parameters¶

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

textChat Properties

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

Changing the Alan AI button position¶

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

left: sets the Alan AI button position from the left edge
right: sets the Alan AI button position from the right edge
top: sets the Alan AI button position from the top edge
bottom: sets the Alan AI button position from the bottom edge
zIndex: sets the z-order of the Alan AI button

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 page or 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 AI Agentic Interface about the app’s visual context. For details, see setVisualState().

Client app¶

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

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);
};

Client app¶

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

playText()¶

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

Client app¶

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

sendText()¶

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

Client app¶

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

playCommand()¶

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

Client app¶

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

activate()¶

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

Client app¶

 alanBtnInstance.activate();

deactivate()¶

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

Client app¶

alanBtnInstance.deactivate();

isActive()¶

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

Client app¶

alanBtnInstance.isActive();

remove()¶

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

Client app¶

alanBtnInstance.remove();

textChat.isAudioOutputEnabled()¶

Use the textChat.isAudioOutputEnabled() method to get the state of audio output for the Alan AI Chat. 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 Chat. For details, see textChat.setAudioOutputEnabled().

Client app¶

alanBtnInstance.textChat.setAudioOutputEnabled(true)

textChat.setFullScreenMode()¶

Use the textChat.setFullScreenMode() method allows switching the Alan AI Chat 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 Chat interface. For details, see textChat.open().

Client app¶

alanBtnInstance.textChat.open(); // Opens the Alan AI Chat interface

textChat.close()¶

Use the textChat.close() method to close the Alan AI Chat interface. For details, see textChat.close().

Client app¶

alanBtnInstance.textChat.close(); // Closes the Alan AI Chat interface

textChat.minimize()¶

Use the textChat.minimize() method to minimize the Alan AI Chat interface. For details, see textChat.minimize().

Client app¶

alanBtnInstance.textChat.minimize(); // Minimizes the Alan AI Chat interface

textChat.clear()¶

Use the textChat.clear() method to clear the Alan AI Chat interface. For details, see textChat.clear().

Client app¶

alanBtnInstance.textChat.clear(); // Clears the chat history in the Alan AI Chat interface

theme.setTheme(theme)¶

Use the theme.setTheme(theme) method to set the Alan AI Chat 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 Chat 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 page or 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¶

alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onCommand: (commandData) => {
    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 button state changes. For details, see onButtonState handler.

Client app¶

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 AI Agentic Interface project. For details, see onConnectionStatus handler.

Client app¶

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, AI Agentic Interface responses and so on. For details, see onEvent handler.

Client app¶

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

textChat parameter¶

Use the textChat to provide additional configuration options and handlers for managing the Alan AI Chat interface in “inlined” mode. For details, see textChat parameter.

What’s next?¶

Example apps

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