Chatbot

Add a Keural chatbot to your organization's website. When a visitor presses the button in a corner of the screen, the chatbot window opens. Install it by pasting the install code created on the admin screen into your website.

Creating a chatbotCopy Anchor Link

1. An organization owner or admin presses ＋ Add Chatbot under Organization management → Chatbots.
2. Enter a chatbot name and a default domain (for example, https://example.com) and register it.
3. Open the chatbot and set up the three tabs.

4. Paste the install code into your website.

Install codeCopy Anchor Link

Copy the HTML or Next.js code from the Token & Install tab. The code consists of two parts.

• Loader: Creates the Keural function, and when the page has finished loading, loads the chatbot script (/plugin/keural-widget@1.0.1.js) asynchronously. Commands called before the script loads are queued and run in order.
• Start command: Keural('boot', { token: '…' }). The token starts with wgt_.

The script version is fixed in the address. When a new version is released, copy the install code again and replace it. If the install code is placed twice on the same page, the second one is ignored and an error is logged to the console.

<script id="keural-one-script">
  /* Code copied from the Token & Install tab */
</script>

In Next.js, add it with <Script id="keural-one-script" strategy="afterInteractive"> from next/script. To show the chatbot on every page, place it in the root layout.

Startup optionsCopy Anchor Link

Values passed to boot take priority over the admin screen settings. Use them to change the appearance per page.

Keural('boot', {
  token: 'wgt_…',
  theme: 'system',
  header: { enabled: true, extended: true, draggable: true, title: 'Customer support', color: '#495BD8' },
  button: { visible: true, iconUrl: 'https://example.com/icon.png', color: '#495BD8', position: 'right', offsetX: 30, offsetY: 30 },
});

The defaults for a newly created chatbot are: header display and expansion on, header and button color #495BD8, right side, offset 30px, and theme system.

Page controlCopy Anchor Link

Methods such as Keural.open() work only after the script has loaded. When you call them right after the page opens, use the function form such as Keural('open'), and the calls run in order.

<button onclick="Keural('open')">Contact us</button>

You can also hide the default button (button.visible: false) and open the chatbot from a button on your page.

Screen sizeCopy Anchor Link

The chatbot window is 390×800px, and if the screen width is 480px or less, it opens full screen. Enlarge the window with the expand button in the header.

Display domainsCopy Anchor Link

• The chatbot opens on pages with the same host as the default domain. Hosts are compared including the port, and letter case is not distinguished. Addresses with www. and subdomains are different hosts. To test on a development server, create a separate chatbot with that address as its default domain.
• The default domain cannot be changed after creation. To change it, create a new chatbot.
• If the allowed domains under Advanced are empty, the chatbot opens on all pages of the default domain. If allowed domains are entered, it opens only on pages starting with those addresses. Entering a path such as https://example.com/help narrows it to pages under that path. Allowed domains start with http:// or https://, and you can enter up to 5.
• The token in the install code is exposed on the page. Connect only content that can be made public to the chatbot.

Content Security Policy (CSP)Copy Anchor Link

If your site applies a Content-Security-Policy, allow the following. The addresses are based on keural.ai.