Keural Kit

Keural Kit places Keural screens on your page with a single script. The screens are drawn inside a Shadow DOM, so they do not mix with your page's CSS. Kit is updated when the Keural web app is deployed. If an old screen still appears after deployment, clear the browser and CDN caches and check the build time with window.KeuralKit.__build.

LoadingCopy Anchor Link

Kit loads from the web address of the Keural environment you use. For keural.ai, it is https://keural.ai. For an on-premises or dedicated environment, use that environment's Keural web address. Before the script, set the server addresses that Kit will call in window.__KEURAL_ENV__. All three addresses must belong to the same environment. Get them from your Keural contact during adoption.

<script>
  window.__KEURAL_ENV__ = {
    NEXT_PUBLIC_API_BASE_URL: '<KEURAL_API_URL>',
    NEXT_PUBLIC_FAST_API_BASE_URL: '<KEURAL_AGENT_URL>',
    NEXT_PUBLIC_MODE: 'prd',
  };
</script>
<script src="<KEURAL_WEB_URL>/plugin/kit/keural.js" async></script>

To use the same Kit on a second domain, set all three values NEXT_PUBLIC_ADDITIONAL_FRONTEND_URL, NEXT_PUBLIC_ADDITIONAL_API_BASE_URL, and NEXT_PUBLIC_ADDITIONAL_FAST_API_BASE_URL. If any one is missing, an error occurs. Each value is an https:// address without a path.

When the script loads, window.KeuralKit is created. In SPAs such as React, use a loader so that the script is loaded only once.

export function loadKeuralKit(src = '<KEURAL_WEB_URL>/plugin/kit/keural.js') {
  if (window.KeuralKit) return Promise.resolve(window.KeuralKit);
  return new Promise((resolve, reject) => {
    const s = document.createElement('script');
    s.src = src;
    s.async = true;
    s.onload = () => resolve(window.KeuralKit);
    s.onerror = () => {
      s.remove();
      reject(new Error('Keural Kit failed to load'));
    };
    document.head.appendChild(s);
  });
}

Mount chatCopy Anchor Link

const el = document.getElementById('keural-chat')!;

window.KeuralKit.mountChat(el, {
  userInfo: { userId: user.id, name: user.name },
  colorMode: 'light',
  initialData: { message: "Summarize this quarter's revenue", room_name: 'Quarterly report' },
  onSessionCreated: (roomId) => router.push(`/c/${roomId}`),
  onError: () => router.push('/'),
});

// When leaving the screen
window.KeuralKit.unmount(el);

• To open an existing conversation, put its conversation ID in sessionId.
• initialData is included only when opening a new conversation. If it is included when opening an existing conversation, the same message is sent again.
• If userInfo.userId is missing, the user is treated as signed out. Mount the chat after the sign-in information is ready.

MethodsCopy Anchor Link

The mount* and update* methods take colorMode and userInfo, and unmount(el) takes only the element. update* redraws the same element with new options. To open and close the window, change the open value and call update*. Calling mount* again on the same element reuses the existing screen.

mountChat optionsCopy Anchor Link

initialDataCopy Anchor Link

Screen languageCopy Anchor Link

Kit screens are displayed in Korean.

Settings and sign-inCopy Anchor Link

• User settings are changed in the Keural web app or app, and the Kit screen follows those settings.
• Your service handles sign-in, and Kit receives only the signed-in user's information.