Instance methods

Overview

When your AI chat loads, it returns an instance object for runtime interaction with the chat. The initialized AI chat instance supports runtime utility methods your code uses to render the AI chat widget, send a message, or subscribe to events.

List of methods and properties

The following list shows all the available instance methods and properties.

Instance method and property details

instance.messaging.addMessage(message)

This method adds a new incoming/received message to the chat. Use this method when a new message has been constructed and should be displayed to the user. It can only be used to display messages "received" by the user. It cannot be used to display user created or "sent" messages. It should not be used to add old historical messages into the chat; insertHistory should be used for that.

When you call this method, it fires the pre:receive and receive events as well as the userDefinedResponse event for any user_defined items in the message.

The message expected here is a MessageResponse. If an id is not included in the message, the AI chat generates one.

This method returns a Promise which resolves after the message has been added and the receive events have been completed.

Example

await instance.messaging.addMessage({
  output: {
    generic: [
      {
        response_type: 'text',
        text: 'This is a message to the user',
      },
    ],
  },
});

instance.messaging.addMessageChunk(chunk)

This method adds a new incoming/received message chunk to the chat for a streaming message. A message has a response_id. This message can contain individual message items, which also have their own unique IDs.

The instance.messaging.addMessageChunk method takes chunks of the following three different types:

partial_item

The partial_item type is an individual message item chunk. It is the latest chunk of an individual message item and the AI chat handles joining with previous chunks. The chunk is a PartialItemChunk with a partial GenericItem inside it. For more information, see FinalResponseChunk.

complete_item

The complete_item type is the final complete message item. This does not have to match the total values of the partial_item chunks that have been sent. For more information, see CompleteItemChunk.

final_response

The final_response type is the full message with all individual completed message items. The content of this response does not have to match the original stream. For more information, see FinalResponseChunk.

The AI chat expects an additional streaming_metadata: { response_id: 'xyz' } object at the root of the chunk for partial_item and complete_item chunks which contain the unique ID assigned to the final completed response. This is different from the IDs assigned to each individual item in the response that each chunk represents. The final_response chunk provides the ID as the id property on the final response object.

If the chunk is a final_response, it also fires the same events that fire when the AI chat receives a message response in the case of addMessage.

This method returns a Promise which resolves after the AI chat adds the chunk. If the chunk is a final_response, the Promise resolves after the pre:receive and receive events complete.

Canceling a stream

If you include streaming_metadata.cancellable on the PartialItemChunk it will enable the button to stop streaming. If the button is pressed, the stopStreaming event will be thrown.

When the stream is cancelled, streaming_metadata.stream_stopped should be set to true on the CompleteItemChunk and FinalResponseChunk.

For more information, see ItemStreamingMetadata.

Example

// Add the first partial_item chunk when streaming starts.
await instance.messaging.addMessageChunk({
  partial_item: {
    response_type: 'text',
    text: 'Streaming',
    streaming_metadata: {
      id: '1',
      cancellable: true, // marks it able to be cancelled which turns on the stop streaming button.
    },
  },
  streaming_metadata: {
    response_id,
  },
});

// Add a second partial_item chunk that adds more content to the message item.
await instance.messaging.addMessageChunk({
  partial_item: {
    response_type: 'text',
    text: ' is cool!',
    streaming_metadata: {
      id: '1',
      cancellable: true,
    },
  },
  streaming_metadata: {
    response_id,
  },
});

// When the item is complete, add a complete_item chunk to show a full version
// of the item. Note that this allows the item content to be changed.
await instance.messaging.addMessageChunk({
  complete_item: {
    response_type: 'text',
    text: 'Streaming is cool! (complete)',
    streaming_metadata: {
      id: '1',
      stream_stopped: false,
    },
  },
  streaming_metadata: {
    response_id,
  },
});

// When the entire stream is done, use a final_response chunk to display the
// final complete response that has all the items in it. Note that this allows
// the item content to be changed again.
await instance.messaging.addMessageChunk({
  final_response: {
    id: response_id,
    output: {
      generic: [
        {
          response_type: 'text',
          text: 'Streaming is cool! (final)',
          streaming_metadata: {
            id: '1',
            stream_stopped: false,
          },
        },
      ],
    }
  },
});

instance.messaging.clearConversation()

This method removes all messages from the chat. It performs the same operations as restartConversation except that it does not attempt to reload any initial state for the chat; in particular, it does not display the home screen or make a request for the welcome message and leaves the chat empty.

Example

await instance.messaging.clearConversation();

instance.messaging.insertHistory(historyItems[])

This method inserts the historical messages into the chat. It fires the history:begin and history:end events. Any existing messages in the chat are inserted before them.

The array of messages contains messages following the format:

interface HistoryItem {
  /**
   * The v2 message request or response object.
   */
  message: MessageRequest | MessageResponse;

  /**
   * Time this interaction occurred in ISO Format (e.g 2020-03-15T08:59:56.952Z).
   */
  time: string;
}

Example

await instance.messaging.insertHistory([
  {
    message: {
      id: crypto.randomUUID(),
      input: {
        text: 'Message from user',
      }
    },
    time: new Date().toISOString(),
  },
  {
    message: {
      id: crypto.randomUUID(),
      output: {
        generic: [
          {
            response_type: 'text',
            text: 'Response from the server',
          },
        ],
      },
    },
    time: new Date().toISOString(),
  },
]);

instance.messaging.removeMessages(ids[])

This instance removes the messages from the chat. The array passed to this method contains the string IDs associated with messages that the AI chat removes from the chat. The IDs are full message responses or requests, not the individual message items in (streaming_metadata.id).

No events fire from this method.

Example

await instance.messaging.removeMessages(['aefbe9c7-72ec-443e-ad3d-3666dc57f039']);

instance.agentEndConversation()

This method ends the conversation with a human agent. It does not request confirmation from the user first. This function has no effect, if the user does not connect or is not connecting to a human agent. You can determine if the user connects or is connecting by calling getState. Note that this function returns a Promise that only resolves when the conversation has ended; this includes after the agent:pre:endChat and agent:endChat events have been fired and resolved.

Example

const state = instance.getState();
if (state.serviceDesk.isConnected || state.serviceDesk.isConnecting) {
  await instance.agentEndConversation();
}

instance.serviceDesk.endConversation()

This method ends the conversation with a human agent. It does not request confirmation from the user first. This function has no effect, if the user does not connect or is not connecting to a human agent. You can determine if the user connects or is connecting by calling getState. Note that this function returns a Promise that only resolves when the conversation has ended; this includes after the agent:pre:endChat and agent:endChat events have been fired and resolved.

Example

const state = instance.getState();
if (state.serviceDesk.isConnected || state.serviceDesk.isConnecting) {
  await instance.serviceDesk.endConversation();
}

instance.changeView()

Changes the current view state. You can use it to open or close the main window or to open or close a tour.

This function has the following two forms:

1. First form: Passes the name of the view as a string to open. The view opens and all other views close.

2. Second form: Passes an object with the names of the views to change. The state of each included view changes to the state, while others views stay the same. Any views that do not pass don't change.

The current view names:

• launcher: The button at the bottom of the screen that opens the main window.
• mainWindow: The main window of AI chat that displays messages with the user.
• tour: The window that displays the contents of an active tour.

This method fires the view:pre:change and view:change events.

Example

// Opens the main window and closes all the other views.
instance.changeView('mainWindow');

// Opens the main window and closes the launcher. The tour view remains unchanged.
instance.changeView({ mainWindow: true, launcher: false });

instance.closeWindow()

This method closes the chat window if it is currently open, and fires the window:close event.

Example

instance.closeWindow();

instance.destroy()

This method destroys the AI chat widget, including the chat window and chat launcher. It removes all event subscriptions and all methods on the instance.

Also, to keep a subsequently created AI chat from trying to continue the previous session, you should also call instance.destroySession before calling this method.

Example

instance.destroy();

instance.destroySession()

AI chat stores information about the current session in the browser. This method removes all browser storage related to the current AI chat session. It also issues a call to the server to remove the session from the server. You can call this method as part of your logout sequence to avoid a user's AI chat from trying to reconnect to the previous user's session.

Stop using the AI chat instance after making the call if the call does not occur during the window unload process. Call instance.destroy to destroy the AI chat instance and remove it from the page.

Example

instance.destroySession();

instance.doAutoScroll()

This method automatically scrolls to the most recent message in the list. It helps when you render a user_defined response type after the AI chat has already completed its autoscroll behavior, and you need the AI chat to correct itself.

Example

instance.doAutoScroll();

instance.getIntl()

This method returns the object that the AI chat uses for displaying static translated strings. It is an instance of a IntlShape that the Format.JS library provides. You can find the out-of-the-box strings that the AI chat uses in the languages folder. Make sure to access the files for the version of the AI chat that you use.

Note: A new IntlShape object generates every time the locale or language pack updates.

Example

const placeholderText = instance.getIntl().formatMessage({ id: 'input_placeholder' });

instance.getLocale()

This method returns the current locale in use by the widget. It returns a string containing the language code or the language and region codes (for example, ja or en-gb).

Example

console.log(instance.getLocale());

instance.getState()

Returns properties representing the current state of the AI chat.

Example

instance.getState();

instance.getWidgetVersion()

This method returns the version number of the widget code.

Example

instance.getWidgetVersion();

instance.off()

This method removes a subscription to an event type. After you remove a subscription, the callback handler does not call for the event type. It returns the instance itself, for chaining purposes.

Example

// Your handler
function handler(event) {
  console.log(event);
}

instance.on({ type: 'receive', handler: handler });
instance.on({ type: 'send', handler: handler });

instance.off({ type: 'receive', handler: handler });
instance.off({ type: 'send', handler: handler });

// You can also pass AN ARRAY of objects to the method

instance.on([
  { type: 'receive', handler: handler },
  { type: 'send', handler: handler }
]);

instance.off([
  { type: 'receive', handler: handler },
  { type: 'send', handler: handler }
]);

// You can also just "unsubscribe from all" by not passing a handler
instance.on({ type: 'send', handler: handler });
instance.off({ type: 'send' });

instance.on()

This method subscribes to a type of event using a callback that calls whenever it fires a specified event type. You can register as many subscriptions to an event type as you want. Subscriptions are called in order, starting with the first registered.

This method returns the instance itself, for chaining purposes.

Example

// Your handler
function handler(event) {
  console.log(event);
}

instance.on({ type: 'receive', handler: handler });
instance.on({ type: 'send', handler: handler });

// You can also pass AN ARRAY of objects to the method

instance.on([
  { type: 'receive', handler: handler },
  { type: 'send', handler: handler }
]);

instance.once()

This method subscribes an event handler as a listener for only one occurrence of the specified event type. After handling one event of the specified type, this handler automatically unsubscribes.

This method returns the instance itself, for chaining purposes.

Example

function handler(event) {
  console.log(event);
}

const mockSendObject = {
  input: {
    message_type: 'text',
    text: 'get human agent'
  }
};;

instance.once({ type: 'send', handler: handler });

instance.send(mockSendObject);

// The subscription is now removed.

// You can also pass AN ARRAY of objects to the method

instance.once([
  { type: 'receive', handler: handler },
  { type: 'send', handler: handler }
]);

instance.openWindow()

This method opens the chat window if it is currently closed, and fires the window:open event.

Example

instance.openWindow();

instance.requestFocus()

When the application is open, an appropriate focusable and visible element gets focus.

Example

instance.requestFocus();

instance.render()

This method renders the AI chat widget on your page. It returns a Promise that succeeds if the widget successfully renders.

Example

instance.render().then(function() {
  console.log('It worked!')
}).catch(function(e) {
  console.error(e);
});

instance.restartConversation()

This method restarts the conversation with the assistant and ends any conversation with a human agent. It clears all of the current assistant messages from the main bot view and cancel any outstanding messages. This also deletes the current assistant session which forces a new session to start on the next message.

This method also fires the pre:restartConversation and restartConversation events.

Once the restart is complete, the AI chat switches to the home screen or request the welcome message to be displayed again.

Example

instance.restartConversation();

instance.scrollToMessage()

This method scrolls the AI chat messages list to the message. The top of the message scrolls to the top of the message list. The ID of the message can be obtained using one of the receive, pre:receive, send, pre:send, history:begin or history:end events depending on where the message came from.

Example

instance.scrollToMessage('8cf22fcd-f3d1-4eee-9aea-26d14e87e481');

instance.send()

This method sends the specified message to the assistant. This results in pre:send and send events being fired.

This method returns a Promise that resolves successfully when the message is successfully sent.

Examples

A simple text message.

instance.send('get a human agent');

A message request using the message request object format and with a silent option so the message request is not visible to the user. Note, send always returns a Promise but it's particularly important when a silent message is sent to catch any errors from the Promise and notify the user about them since it may not be obvious in the chat that the message has failed.

const sendObject = {
  input: {
    message_type: 'text',
    text: 'get a human agent'
  }
};
const sendOptions = {
  silent: true
}
instance.send(sendObject, sendOptions).catch(console.error);

A message that sets a context variable. Replace ['main skill'].user_defined with ['actions skill'].skill_variables if you are using Actions instead of Dialog.

const sendObject = {
  input: {
    message_type: 'text',
    text: 'get a human agent'
  },
  context: {
    skills: {
      ['main skill']: {
        user_defined: {
          custom_var: 'My custom variable',
        }
      }
    }
  }
};
instance.send(sendObject);

instance.showLauncherGreetingMessage()

This method controls the timing of when the greeting message appears. The default behavior is that the greeting message appears after 15 seconds. If the greeting message is already visible, then it ignores any new set times. If the greeting message is visible to the user when the page changes or reloads, the greeting message remains visible when reloading. The updated timing does not save in the session storage, if the user changes pages or reloads the page before the greeting message appears. The updated timing needs to be set again. This can not be used to change the greeting text of the launcher. If you want to change the text use instance.updateLauncherGreetingMessage()

Example

// To show the desktop launcher in 4s (the mobile launcher shows at the original 15s interval).
instance.showLauncherGreetingMessage(4000, 'desktop')
// To show the mobile launcher in 6s (the desktop launcher would still plan to show in 4s).
instance.showLauncherGreetingMessage(6000, 'mobile')
// To show both the desktop and mobile launcher 8s from now (the previous timers would be cleared).
instance.showLauncherGreetingMessage(8000)

instance.toggleOpen()

This method toggles the current open or closed state of the window.

Example

instance.toggleOpen();

instance.tours.endTour() Beta

This method clears all tour data, closes the tour, and switches to the launcher. When the user clicks the launcher, the main chat window opens. The user can start the tour again with the tour card from the chat window.

instance.tours.goToNextStep() Beta

This method moves to the next step in the tour. When the next step is switched to the tour:step event fires.

instance.tours.goToStep() Beta

This method accepts a string for the stepId that the tour goes to. This tour json defines the step_id as a step_id string. When the tour switches to the new step, the tour:step event fires.

Example

// Switch to the step in the tour that is labeled as step_id: "welcome_3" in the tour json.
instance.tours.goToStep('welcome_3');

instance.tours.startTour() Beta

This method accepts a message string that sends data to the back end to get a new tour. Once the tour data returns, the tour view switches automatically. When the tour switches, the tour:start event fires.

Example

// Send a message that corresponds to a "welcome tour" action and returns to show the tour data.
instance.tours.startTour('welcome tour');

instance.updateAssistantInputFieldVisibility()

This method allows you to hide or show the input field when conversing with the assistant. It applies when your assistant requires input via buttons or other constrained input. This does not apply to the input field for conversing with a human agent.

Example

instance.updateAssistantInputFieldVisibility(true); // Shows input field.
instance.updateAssistantInputFieldVisibility(false); // Hides input field.

instance.updateBotUnreadIndicatorVisibility()

This method updates the visibility of the custom unread indicator that appears on the launcher. It appears as an empty circle on the launcher and remains visible until the AI chat opens.

This indicator is in addition to the indicator for unread messages from a human agent. If there are any unread agent messages, a circle appears with the unread count inside of it and it appears regardless if you call this method.

You can adjust the colors of this indicator by using the updateCSSVariables method.

Example

// Show the indicator.
instance.updateBotUnreadIndicatorVisibility(true);
// Hide the indicator.
instance.updateBotUnreadIndicatorVisibility(false);

instance.updateCSSVariables()

This method overrides the configurable CSS variables used to render the AI chat. You can pass in as many variables as you want to override. The values you specify merge with the existing settings. You can also visit the section on Theming for more information.

Warning: The AI chat provides many hooks to amend and change content, and the AI chat uses HTML, CSS, and JavaScript for its build. Avoid manipulating content outside the default configuration to prevent unintended issues when the AI chat deploys new releases.

Example

instance.updateCSSVariables({
  'BASE-z-index': '8000',
  'BASE-font-family': '"Times New Roman", Times, serif',
  '$focus': '#ff0000'
});

Customizable variables

Customizable launcher variables

You can override the pre-configured color variables for the AI chat launcher and desktop launcher expanded message.

Example

instance.updateCSSVariables({
  'LAUNCHER-color-background': '#525252',
  'LAUNCHER-color-background-hover': '#3d3d3d',
  'LAUNCHER-color-background-active': '#1f1f1f',
  'LAUNCHER-color-focus-border': '#ffffff',
  'LAUNCHER-color-avatar': '#ffffff',
  'LAUNCHER-EXPANDED-MESSAGE-color-background': '#ffffff',
  'LAUNCHER-EXPANDED-MESSAGE-color-background-hover': '#ebebeb',
  'LAUNCHER-EXPANDED-MESSAGE-color-background-active': '#cccccc',
  'LAUNCHER-EXPANDED-MESSAGE-color-focus-border': '#000000',
  'LAUNCHER-EXPANDED-MESSAGE-color-text': '#000000',
  'LAUNCHER-MOBILE-color-text': '#000000',
});
await instance.render();

Customizable theming variables

For a complete list of theming variables and their default values, see the Carbon Design System documentation. To customize the appearance of your AI chat, use the instance.updateCSSVariables() method to override the theming variables you want to change. Color values must be in hexadecimal format.

Example

instance.updateCSSVariables({ '$focus': '#ff0000' });
await instance.render();

instance.updateCustomMenuOptions()

This method updates the display of custom menu options that appear in the header. These options display in a hamburger menu that appears in the top left corner of the header. You can call this method anytime to change the current set of options. Each option is configurable with a custom callback function that calls when the option is selected.

Example

instance.updateCustomMenuOptions([
  { text: 'Bot option 1', handler: () => console.log(`Selected Bot option 1`) },
  { text: 'Bot option 2', handler: () => console.log(`Selected Bot option 2`) },
]);

instance.updateHistoryUserDefined()

This method provides a way to save state for any message response. This saved state is available in the history.user_defined section of the message response on reload. The data is only saved for the duration of the user's session; once the session expires, the data deletes.

For an example of this method in action look at the "Example with session history" in the userDefinedResponse section.

instance.addNotification() Deprecated

This method provides a way to notify the user in a way consistent with the AI chat of the results of actions that have been taken.

Example

instance.addNotification({
  kind: 'success',
  title: 'Success',
  message: 'You have successfully paid your bill.'
});

instance.addNotification({
  kind: 'error',
  title: 'Error',
  message: 'Your bill was unable to be paid.',
  actionButtonLabel: 'Contact us',
  onActionButtonClick: () => { // Do something, notification closes on click. }
});

instance.updateHomeScreenConfig

This method turns the home screen feature on and off, and dynamically updates the home screen content. It applies when you want to have different conversation starters or welcome text on different pages of your website.

You can also control the home screen background. The home screen currently supports two options for background gradients; either a top corner out gradient, or a gradient that goes from the bottom up. You can choose between these two options, and whether or not to enable the background gradient, by editing the background_gradient object within the homeScreenConfig.

Example

instance.updateHomeScreenConfig({
  is_on: true,
  greeting: 'Welcome! Please ask us a question.',
  starters: {
    is_on: true,
    buttons: [
      {
        label: 'Open a new brokerage account',
      },
      {
        label: 'Open a new savings account',
      },
      {
        label: 'Open a new checking account',
      }
    ]
  },
  background_gradient: { 
    is_on: true,
    gradient_direction: 'bottom_up' 
  }
});

instance.updateIsTypingCounter()

This method changes the internal counter that controls the visibility of the "is typing" indicator. This indicator displays an animated "..." that lets the user know the assistant is "typing" a message. Based on an internal counter, this indicator increases when an action qualifies as "is typing" and decreases when the action completes. The indicator remains visible as long as this counter is greater than zero. Use this function to increase or decrease this counter (but not below zero).

To increase the counter, pass the argument increase to the method. To decrease the counter, pass the argument decrease to the method.

Ensure that if you increase the counter, you always decrease it, even in the event of an error. If you fail to decrease the counter, the indicator becomes stuck permanently.

Example

// Show the indicator.
instance.updateIsTypingCounter('increase');
// Hide the indicator.
instance.updateIsTypingCounter('decrease');

instance.updateMainHeaderAvatar()

This method lets you updates the avatar image displayed in the header of the main bot panel. By default there is no avatar image in the main header.

Example - Adding a new chat header avatar

instance.updateMainHeaderAvatar({
  source: 'CUSTOM_AVATAR_URL',
  corners: 'round',
});

Example - Setting an empty chat header avatar

instance.updateMainHeaderAvatar();

instance.updateMainHeaderTitle()

This method updates the string shown in the header of the chat to signify the name of the assistant.

Example - Adding a new title

instance.updateMainHeaderTitle('Larry the Assistant');

Example - Setting an empty title

instance.updateMainHeaderTitle();

instance.updateLanguagePack()

Updates the current language pack with the values from the provided language pack. This language pack does not need to be complete; only the strings it contains update, and all other strings remain unchanged. Variables used within a value string of the current language pack can be used in your updated strings. If you need to make an update based on the user's locale (e.g. British English vs US English), use getLocale to identify the current locale.

See Languages for more information.

Example

const customLanguagePack = {
  errors_communicating: 'Oops, something went wrong. Refresh to try again.'
};
instance.updateLanguagePack(customLanguagePack);

instance.updateLauncherAvatarURL()

This method allows you to modify the default the AI chat launcher avatar with a custom image. The avatar renders in 32 x 32 pixels.

Example

instance.updateLauncherAvatarURL('CUSTOM_AVATAR_URL');

instance.updateLauncherGreetingMessage()

This method provides a way to update the greeting text of the launcher. We recommend limiting the number of characters to 65 on desktop, and 45 on mobile, in order to avoid truncation. The updated text does not save in session storage, if the user changes pages or reloads the page then the updated text needs to be set again. This does not cause the greeting message to be displayed. If you want to show the greeting message, use instance.showLauncherGreetingMessage()

Example

// To update desktop text only.
instance.updateLauncherGreetingMessage('launcher text desktop', 'desktop')
// To update mobile text only.
instance.updateLauncherGreetingMessage('launcher text mobile', 'mobile')
// To update both desktop and mobile text.
instance.updateLauncherGreetingMessage('launcher text')

instance.updateLocale()

This method changes the current language and locale in use by the AI chat. See Languages for more information. By default, the locale is US English (en-us).

The locale controls the default language strings and the format of any dates shown by the AI chat that it generated on its own (not dates you generate in your dialog skill, for instance). If you simply want to change the AI chat to use spanish, you can update the locale to es. If you want more fine-grained control over individual strings, see instance.updateLanguagePack. If you change the locale after updating individual language strings, you lose your changes to the individual strings. It is recommended you call the updateLocale method before you call instance.render().

This method returns a Promise that succeeds if the widget successfully updates the locale.

Note: After you call this function, the context.global.system.locale context variable is set to this value on the next message that sends to the assistant.

Example

await instance.updateLocale('fr');

Instance elements

instance.elements.getMainWindow()

This method provides access to the main window of the AI chat. If you use a custom element to contain the AI chat, these functions require to show or hide the main window or to apply animations.

addClassName()

Adds the classname to the main window element.

removeClassName()

Removes the classname from the main window element. Only classnames added with addClassName can be removed.

Example

instance.elements.getMainWindow().addClassName('HideWebChat');

instance.elements.getMessageInput()

This method provides access to the input field that appears at the bottom of the main messages area of the main window. This field is a different object than the field that appears on the home screen.

getHTMLElement()

Returns the raw DOM element (text area) that is the input field. You can attach listeners to this element to provide custom behavior to the field. For example, you can add a keydown listener that could navigate through a type-ahead popup using the arrow keys. You can also access the value property of the element to get the current value in the field.

While you can add input and change listeners to this field, the listeners do not fire in some cases. For example, if the AI chat internally changes the value of the field (which happens when it clears the field after the user sends a message), these events do not fire. In order to ensure that you always get any change to the value of the field, use the addChangeListener function instead.

Setting the value property of the element directly does not work. It does not trigger the internal events that the AI chat needs to respond to the change (such as enabling the send button). You should instead use the setValue elements function instead.

Also note that you cannot access the input field before it has been rendered by the AI chat. This does not occur until after chat:ready has fired. You should wait for this event using once before attempting to access the element.

setValue()

Sets the value of the input field. You should use this instead of setting the value property directly on the HTML DOM element.

setEnableEnterKey()

This method changes whether the enter key is handled by the AI chat. By default, pressing enter in the input field sends the field's contents to the assistant or an agent. Setting this value to false disables this behavior. This allows you to add custom logic when the user presses this key (for example, if the user selects a highlighted value from a type-ahead popup).

addChangeListener()

Adds a change listener to the input field that fires whenever the value in the field changes. This fires even in cases where a change or input DOM event would not.

removeChangeListener()

Removes a change listener from the input field.

Example

instance.once({ type: 'chat:ready', handler: () => {
  const messageInput = instance.elements.getMessageInput();
  messageInput.setValue('Default value');
  messageInput.getHTMLElement().addEventListener('keydown', event => console.log('Got keydown', event));
  messageInput.addChangeListener(value => console.log('You typed', value));
}});                  

instance.elements.getHomeScreenInput()

This method provides access to the input field that appears at the bottom of the home screen. This field is a different object than the field that appears on the main message area. This function returns an object that has the same functions as getMessageInput.

Instance writeable elements

AI chat provides elements available in different parts of the AI chat for you to provide custom HTML content. You can directly write to these elements or, if you use advanced frameworks like React or Angular, you can write to these elements as portals from your own application.

Example

instance.writeableElements.welcomeNodeBeforeElement.innerHTML = '<div class="my-awesome-class">Disclaimer text...</div>';

All writeable elements inject into slots within the AI chat's ShadowRoot. This means that they can be styled from global CSS and only have a very small piece part of the CSS inherited from the AI chat (font styling, etc) styles.

Custom panels

AI chat provides access to panels that can take up the whole AI chat window and that can contain fully custom content. To get a custom panel, use the instance.customPanels.getPanel() instance method.

instance.customPanels

This method returns an object that can be used to control custom panels.

Custom Panel Instance

The following list shows all the available custom panel instance methods:

The following list shows all the available custom panel instance properties.

customPanel.open()

This method opens the custom panel and accepts configuration options for the custom panel. It also fires a customPanel:pre:open event when its opening animation has started. Once the opening animation has ended it fires a customPanel:open event.

Example

const customPanel = instance.customPanels.getPanel();
const panelOptions = {
  title: 'My custom panel',
};

customPanel.open(panelOptions);

Optional properties for the options object:

customPanel.close()

This method closes the custom panel and fires a customPanel:pre:close event when its closing animation starts. Once the closing animation has ended it fires a customPanel:close event.

Example

const customPanel = instance.customPanels.getPanel();

customPanel.close();

customPanel.hostElement

This method is the host element where you can place your content to display within the custom panel.

Example

const customPanel = instance.customPanels.getPanel();

customPanel.hostElement.innerHTML = '<div class="content-class">My awesome content!</div>';