Controlling the PerfectAI Chat widget with JavaScript

In this article, you will learn how to control the PerfectAI Chat widget on your website with JavaScript, which options are available, how they interact with the chat configuration and which limits apply.

Available from 4 November 2026.

Contents

• Quick Guide
• Prerequisites
• Getting started example
• Configuration options
• How your settings interact with the chat configuration
• Limits to be aware of
• Practical examples
• Related articles

Quick Guide

1. Embed the chat widget on your website with the code from the Code snippet card.
2. In your own script, call window.SpaChatWidget?.configure({ ... }) with only the options you want to change.
3. Check the return value: true means the values were accepted, false means nothing was applied.
4. Use window.SpaChatWidget?.open() and window.SpaChatWidget?.close() to open or close the chat.

Prerequisites

• Published chat configuration: a configuration in draft mode does not provide embed code.
• Widget embedded: the code from the Code snippet card is in place on your website. It loads the widget script with the identifier of your chat configuration. How to embed it and which technical requirements apply is described in Setting up PerfectAI Chat.
• Your script runs after the widget: the methods below are available only once the widget script has loaded. If your code runs earlier, the call is skipped and nothing changes.

Getting started example

Once the widget script has loaded, your page can use the object window.SpaChatWidget. It offers three methods: configure(), open() and close().

window.SpaChatWidget?.configure({
  teaserMessage: 'How can we help you?',
  teaserVisible: true,
  suggestions: [
    { buttonText: 'View memberships', message: 'What memberships are available?' }
  ]
});

window.SpaChatWidget?.open();  // Open the chat
window.SpaChatWidget?.close(); // Close the chat

The operator ?. makes the call safe: if the widget has not loaded yet, the call is skipped instead of causing a script error.

configure() returns true when the values are accepted and false when they are invalid. You can use the return value to check your call:

const accepted = window.SpaChatWidget?.configure({ teaserVisible: false });

if (accepted === false) {
  console.warn('The chat widget rejected the settings.');
}

If the widget has not loaded yet, the call is skipped and the return value is undefined rather than true or false.

Configuration options

All options are optional. Pass only the ones you want to change.

When a visitor clicks a suggestion, the chat starts with the message text as the visitor's first message. If an entry has no message, the buttonText is sent instead.

How your settings interact with the chat configuration

Without settings from your website, the widget uses the teaser and the suggestions from the chat configuration. You can maintain these without code in the chat configuration under Settings / PerfectAI / Chat, card General information.

• Content is replaced: teaserMessage replaces the configured teaser text, suggestions replaces the complete configured suggestion list.
• Visibility is controlled separately: visible, teaserVisible, suggestionsVisible and startscreenSuggestionsVisible work independently of the content. If you do not pass a visibility option, the widget shows what the chat configuration provides.
• Visible needs content: setting a visibility option to true does not create teaser text or suggestions. If neither your website nor the chat configuration provides any, nothing is shown.
• Calls are merged: a later call keeps the options from earlier calls and only changes the options it contains. For example, a call with only teaserVisible: false leaves a teaserMessage you set earlier in place.
• Delay: teaser text and suggestions appear next to the chat button about three seconds after the widget has loaded.
• Dismissed teaser: if a visitor dismisses the teaser, teaser and suggestions stay hidden for the rest of that browser session. A call with visible: true, teaserVisible: true or suggestionsVisible: true clears this and shows them again, so it also overrides the visitor's choice.

Limits to be aware of

• Teaser text: max. 500 characters.
• Suggestions: max. 3, each button text max. 40 characters and must not be empty, each message max. 500 characters.
• Invalid call: configure() returns false if a value has the wrong type, a limit is exceeded or the argument is not a plain object. In that case none of the values in the call are applied.
• Accepted is not loaded: a return value of true only confirms that the values are valid. It does not mean that the chat has finished loading or that a conversation has started.
• Hiding does not close: visible: false hides the chat button but does not close a chat that is already open. To close it, use close() or isOpen: false.

Practical examples

The following snippets are examples. Adapt texts and element IDs to your website and run the code after the widget script has loaded.

Example: open the chat from your own button

<button type="button" id="open-chat">Chat with us</button>

<script>
  document.getElementById('open-chat').addEventListener('click', function () {
    window.SpaChatWidget?.open();
  });
</script>

Example: show a page-specific teaser

On a page about courses, for example, you can replace the configured teaser text with a matching one:

window.SpaChatWidget?.configure({
  teaserMessage: 'Questions about our courses? Just ask us.',
  teaserVisible: true
});

Example: hide the chat button on a page

On a page where the chat button should not appear, for example a checkout page:

window.SpaChatWidget?.configure({ visible: false });

Run the call on each page where the setting should apply.

Related articles

• Setting up PerfectAI Chat

Note: This article was created with the help of artificial intelligence and editorially reviewed.