Website widget

The widget is the fastest channel to ship: one snippet on your site and visitors can chat with your AI agent immediately. The webchat channel is created automatically for every workspace, so there’s nothing to “connect” — just paste the snippet.

Install

Grab your snippet

Go to AI agents, open the agent, select the Channels tab and click Copy snippet under Embed snippet in the Web widget card. Each AI agent has its own widget and snippet. It looks like this:

<script>
(function(){
window.Keloa=typeof window.Keloa==='function'?window.Keloa:(function(o){var f=function(){f.q.push(arguments)};f.q=(o&&o.q)||[];f.init=function(c){f.q.push(c)};return f})(window.Keloa);
var s=document.createElement('script');
s.src='https://YOUR_WIDGET_HOST/widget/v1/loader.js?agent=YOUR_AGENT_ID';
if(document.readyState==='complete'){document.body.appendChild(s)}
else{window.addEventListener('load',function(){document.body.appendChild(s)})}
})();
</script>

Always copy the snippet from Keloa: it holds the exact loader URL. The agent value in that URL is your agent ID. The first line defines Keloa(…), so your page can call it before the widget has loaded.

Paste before </body>

Drop the snippet just before the closing </body> tag of your site. Every page that includes it will show the widget.Framework-specific notes:

WordPress — Appearance → Theme File Editor → footer.php, or any insert-header plugin.
Webflow / Squarespace / Wix — Settings → Custom code → Footer.
Next.js — app/layout.tsx inside <body>, or use next/script with strategy="afterInteractive".
Shopify (theme) — theme.liquid before </body>.

Test

Open your site in an incognito window. A chat bubble appears in the bottom-right (or bottom-left, if you changed it). Click it, say hi, and watch the conversation arrive in your Inbox.

Don’t want to touch your site yet? The Live preview in the agent’s Web widget card runs the widget on a sandboxed host page that mirrors your saved settings.

Configuration

Each AI agent has its own widget. Everything below is set per agent: go to AI agents, open the agent and select the Channels tab. The settings live in the Web widget card. Changes save automatically (the card shows Auto-saving, then Saved) and reach your site on the next loader fetch (CDN cache 60 seconds).

Appearance

Brand color — bubble and header background. Pick a colour or paste a hex value.
Launcher position — Right (default) or Left.
Header display name — the name in the widget header. Falls back to the AI agent’s name.
Welcome message — the greeting shown when no intro bubbles are set. Leave it empty to use the built-in greeting.
Quick questions — up to 6 chips that visitors can tap on a fresh chat instead of typing. Auto-seeded from your onboarding site scan and editable any time.
Business-hours message — shown when the team is offline.

The widget avatar comes from the agent’s Profile tab, with the brand logo as fallback.

Intro bubbles

Up to 5 short “hello” bubbles shown when the widget opens. If the list is empty, the Welcome message is used instead.

Privacy policy URL

Optional link in the small footer of the widget. Use it to point at your privacy policy.

Allowed origins

Set per AI agent, under AI agents → your agent → Channels → Web widget → Allowed origins. Empty means the widget loads on any site that includes the snippet. Add hosts to restrict it, which helps when a third party copies your snippet onto an unrelated site.

Enter a host without https://, a port or a path: www.acme.com. An exact host matches only itself, so acme.com doesn’t cover www.acme.com.
*.acme.com matches every subdomain of acme.com, but not acme.com itself.
Only add a wildcard for a domain you control. Keloa refuses wildcards over public suffixes (from the Public Suffix List) and over known shared-hosting platforms, such as *.com, *.nl, *.co.uk, *.vercel.app, *.github.io or *.myshopify.com. Keloa can’t know every hosting platform, so a wildcard it accepts isn’t proof that you control every site under it. For a site on a hosting platform, add its exact address (acme.vercel.app).
A host with non-ASCII letters is saved in its punycode form, which is what browsers send: *.bücher.de becomes *.xn--bcher-kva.de.

With identity verification on, at least one allowed origin is required, and only https pages of these sites, on the standard https port (443), can show the widget. For development, localhost, 127.0.0.1, *.test and *.localhost also work over http and on any port.

Working hours (Business+)

Working hours configured in Settings → Workspace → Business hours are visible to the AI via the system prompt and surfaced in the widget when the customer asks about availability. Outside hours, the AI sets expectations on response time rather than promising live help. The hours field is a per-day window with a workspace timezone (Europe/Amsterdam by default). Enabling and editing this field requires the working_hours cap, available on Business and Scale plans.

Proactive triggers (Business+)

Track availability on the Keloa roadmap.

Coming soon. Proactive triggers are not yet shipped: the Web widget card has no setting for them yet. They will auto-open the widget with a contextual greeting, for example after some time on the page, at a scroll depth or on exit intent.

Branding (Business+)

Hide the small “Powered by Keloa” badge in the widget footer with the Branding switch in the Web widget card. Two-step gate: your plan must include the widget_unbranded cap and you must turn the switch on.

Plan	Unbranded widget
Starter	No
Growth	No
Business	Yes
Scale	Yes

Loading behaviour

The loader script is small, served async, and does nothing until the bubble is hovered or clicked.
The full widget iframe is lazy-loaded the first time the visitor interacts.
A first-party session token is stored in localStorage so returning visitors keep their conversation context. No cross-site cookies.
Conversations of signed-in users are never stored in the browser; they load from Keloa after the user’s token is verified.
The public config endpoint (/widget/v1/config) is cached for 60 seconds at the edge.

What the visitor experiences

What they see	Where it comes from
Bubble color, position	The agent’s Web widget card → Appearance → Brand color, Launcher position
Header name	The agent’s Web widget card → Header display name (or the agent’s name)
Avatar	The agent’s Profile tab
Intro bubbles	The agent’s Web widget card → Intro bubbles
Quick questions	The agent’s Web widget card → Quick questions
Replies	The AI agent attached to the channel, answering from your knowledge base
Greeting language	Auto-detected from `navigator.language` (EN, NL, DE, FR, ES)
“Powered by Keloa” footer	Hidden on Business+ when the Branding switch is on

Advanced

Identify signed-in users

If your site or app has accounts, your backend can sign a short-lived token that tells the widget who the signed-in user is. Keloa verifies it on every request, so nobody can chat as one of your users. Your team sees the user’s verified details in the inbox, and their conversations follow them across devices.

<script>
  window.Keloa=typeof window.Keloa==='function'?window.Keloa:(function(o){var f=function(){f.q.push(arguments)};f.q=(o&&o.q)||[];f.init=function(c){f.q.push(c)};return f})(window.Keloa);
  Keloa('identify', { getToken: () => fetchTokenFromYourBackend() });
</script>

Keloa only accepts identity in a token signed with your secret: an identify call with just an email or name is ignored. See Identity verification for setup, server code samples and security guidance.

Cap	Starter	Growth	Business	Scale
Web chat widget	Yes	Yes	Yes	Yes
Working hours integration	—	—	Yes	Yes
Proactive triggers	—	—	Yes	Yes
Hide “Powered by Keloa”	—	—	Yes	Yes

See Billing & plans for the full picture.

Troubleshooting

Issue	Check
Bubble doesn’t appear	Right-click → Inspect → look for `loader.js` in the Network tab. Verify the `agent` value in the loader URL matches your AI agent. An unknown or paused agent returns `404`.
Widget blocked on your site	The console shows `[Keloa] Widget blocked: origin '…' is not in the allowed domains list.` Add the exact host under Allowed origins. With identity verification on, the page must also be served over https on the standard port (development hosts such as `localhost` excepted).
Signed-in users chat anonymously	Check the `reason` in the `401 identity_invalid` response. See Identity verification troubleshooting.
Bubble appears but won’t open	A CSP header is blocking the iframe. Allow `app.keloa.ai` (or your widget CDN host) as a frame source.
Messages land but no AI reply	Check that the AI agent whose ID is in the loader URL is live, not paused.
Branding toggle is greyed out	You’re not on Business or Scale, or your plan was just upgraded and the page hasn’t reloaded yet.

Getting started

Inbox

AI agents

Knowledge

Flows

Channels

Contacts & companies

Analytics

Workspace settings

Developers

Billing & plans

Account

Help & resources

Website widget

Install

Configuration

Appearance

Intro bubbles

Privacy policy URL

Allowed origins

Working hours (Business+)

Proactive triggers (Business+)

Branding (Business+)

Loading behaviour

What the visitor experiences

Advanced

Identify signed-in users

Plan caps for the widget

Troubleshooting

​Install

​Configuration

​Appearance

​Intro bubbles

​Privacy policy URL

​Allowed origins

​Working hours (Business+)

​Proactive triggers (Business+)

​Branding (Business+)

​Loading behaviour

​What the visitor experiences

​Advanced

​Identify signed-in users

​Plan caps for the widget

​Troubleshooting

Install

Configuration

Appearance

Intro bubbles

Privacy policy URL

Allowed origins

Working hours (Business+)

Proactive triggers (Business+)

Branding (Business+)

Loading behaviour

What the visitor experiences

Advanced

Identify signed-in users

Plan caps for the widget

Troubleshooting