Embed an Agent in Your Site

Put a live, talking agentic avatar on any web page

Once you have built an agentic avatar, the KonAI widget puts it on your website as a real-time conversational agent. Visitors talk to it out loud and it answers with synchronized voice and lipsync video — no downloads, no plugins, and no separate app to open. It is the same avatar you configured in the studio, now embedded wherever your customers already are.

The widget is a single script tag. It handles the microphone, voice activity detection, the streaming connection, and the entire on-screen interface for you, so a working embed is roughly ten lines of HTML. Beyond the basics it can show images, videos, 360° panoramas, virtual tours, and interactive maps whenever your agent decides they would help the conversation.

⭐

Key Highlights

• Drop a live voice-and-video agent onto any page with one script tag
• Float it in a corner or mount it inside a container you size yourself
• Works for websites, kiosks, exhibition screens, and installed PWAs
• Show or hide every piece of on-screen chrome to match your product
• Your agent can present media, panoramas, tours, and maps mid-conversation
• Configure the agent in KonPro Studio, or automate it through the API and SDK

What It Looks Like

An embedded agent mid-conversation. The buttons across the top switch fullscreen, captions, and typed input, and let the guest choose between always-listening voice and push-to-talk. The transcript sits across the bottom of the stage, with the mic-mute and end-call buttons below it.

How It Works

Build your agent. Create the avatar, give it a voice, and set up its persona, knowledge, and tools in KonPro Studio. Copy its agentic avatar ID when you are done.
Add a session endpoint to your backend. The widget needs a short-lived session token to connect. Your server exchanges your API key for one using the Create Widget Session endpoint, so the key never reaches the browser.
Drop the widget on the page. Add a container element, load the script from the CDN, and call KonAI.init() pointing at your session endpoint.

Never put your API key in front-end code. The widget does support an apiKey option, but it exposes your credentials to anyone who views the page source — keep it for local prototyping only and use session tokens everywhere else.

The Embed Code

This is the whole thing — a container, the script, and one call:

html

<div id="konpro-avatar"></div>
<script src="https://cdn.konpro.ai/widget/index.min.js"></script>
<script>
  KonAI.init({
    sessionEndpoint: '/api/widget-session',
    agenticAvatarId: 'af1250af-5de6-4730-a079-32d96705f8c1',
    containerId: 'konpro-avatar',
  });
</script>

Drop the containerId line and the widget floats over your page in the bottom-right corner instead of filling an element.

Customizing Your Agent

There are two ways to shape what your agent knows, says, and shows — a visual one and a programmatic one. Both drive the same avatar, so you can start in the studio and automate later without rebuilding anything.

In KonPro Studio

Visit studio.konpro.ai to build and tune your agent visually — no code required:

Pick a public avatar or upload your own under My Avatars, and assign a stock or cloned voice
Write the persona and prompt that set its tone, scope, and behavior
Attach a knowledge base so it answers from your own content
Fill the Display Library with the images and videos it can show while it talks
Enable tools such as panoramas, virtual tours, city maps, and the kiosk menu on the Tools tab

Through the API and SDK

Everything the studio does is also reachable programmatically, which is what you want for provisioning agents per customer, per tenant, or per campaign:

Create and manage avatars and sessions from your own backend with the KonPro API
Set session limits and lock the agent to specific domains via Create Widget Session settings
Build custom front ends with the KonPro JS SDK when the widget is not the shape you need
Theme the widget, hide any control, and switch conversation modes through the config you pass to KonAI.init()
Hook the widget's callbacks into your analytics or business logic to capture what was said on both sides

Placement Options

Floating: the agent hovers in a corner of the page, like a support bubble. This is the default when you omit a container.
Inline: the agent fills a container element you position and size yourself — good for a dedicated "talk to us" section or a landing page hero.
Kiosk or exhibition screen: run it portrait and full-bleed with push-to-talk, so a held button rather than open-mic listening decides when the agent hears someone. Much more reliable in a noisy hall.
Installed PWA: the widget detects standalone mode and adapts its fullscreen behavior automatically, which covers kiosk hardware and home-screen installs.

Before You Go Live

Serve the page over HTTPS — browsers only grant microphone access on secure origins, though localhost works while developing.
Allow the microphone in your Permissions Policy header. If it is blocked, the mic request fails silently and the guest is left staring at a loading state with nothing in the console.
If your site sends a strict Content Security Policy, allowlist the widget's origins, or the bundle and its voice-detection dependencies will be refused.
Restrict sessions to your own domains using the allowed_domains setting so nobody can lift your embed onto another site.
Embedding inside an iframe? It needs allow="microphone", and the parent page must permit it too.

Next Steps

The Widget Integration reference covers the full picture: every config option, the three authentication methods with backend examples, all the tools and UI controls, the React pattern, instance methods, CSP and Permissions Policy headers, and troubleshooting.

For session handling specifically, see Create Widget Session, Get Widget Session, and Delete Widget Session.

My Avatars Widget Integration Reference