Custom widget

The standard chat widget ships a complete UI. A custom widget ships none: your developers build the chat interface — in your framework, with your design system — and talk to KonvoAI through a small headless SDK. Everything behind the interface stays the same: the same inbox, the same AI agent, the same conversation history and attachments.

Use a custom widget when the standard widget's appearance options aren't enough — a chat embedded inline in your product, a fully branded experience, or a UI that mixes chat with your own features.

How it works

A custom widget is a regular widget channel with the kind set to Custom. The channel has a public channel id (live_chat_…) that identifies it — the id is not a secret, and there are no API keys to manage.

Your frontend loads the visitor SDK and creates a client with that channel id. From there the SDK handles the full visitor protocol:

1. Authentication. The SDK requests a proof-of-work challenge, solves it in the background (no CAPTCHA, nothing visible to the visitor), and exchanges the solution for a short-lived session token. Tokens expire after 15 minutes; the SDK re-mints them automatically.
2. Realtime connection. A WebSocket carries visitor messages up and agent replies, typing indicators, and read receipts down. The SDK reconnects with backoff after network drops and keeps the connection alive with heartbeats.
3. REST endpoints. Conversation history, attachment uploads, and visitor email identification run over authenticated HTTPS calls the SDK wraps in typed methods.

Your code sees a small surface: connect(), sendMessage(), a few more methods, and events for everything the server pushes. The SDK reference documents all of it.

Visitor identity

The SDK generates a random visitor id and keeps it in localStorage, so a returning visitor's conversation threads under the same identity across sessions. Call identify(email) when the visitor tells you who they are — for example after login — and the conversation is linked to that email, which also enables unseen-reply email notifications.

Security model

A custom widget goes through exactly the same doors as the standard widget:

• Origin allowlist. The channel only accepts browsers on the origins you list in the Install tab. A fresh channel allows every origin; restrict it before going live.
• Country rules. The same geo blocking/allowlisting the standard widget supports.
• Proof-of-work. Every session starts with a computational challenge that makes bulk abuse expensive, invisible to real visitors.
• Short-lived, origin-bound tokens. Session tokens expire after 15 minutes and only work from the exact origin they were minted for.
• Connection caps. Concurrent WebSocket connections are limited per channel and per organization.

What the dashboard configures

Appearance settings don't apply — the UI is yours. The configurator for a custom widget keeps:

• General — the widget's name and the AI disclosure notice. When disclosure is enabled, AI messages arrive over the wire with a localized disclosureNotice string for your UI to display.
• Install — the integration snippet, your channel id, the allowed domains list, and country rules.

Ready to build? Start with the quickstart.