Skip to main content
The Karta chat widget is a prebuilt launcher + chat panel you embed with a single async <script> tag. It renders into a Shadow DOM (so host-page CSS cannot bleed in and the widget’s CSS cannot leak out), streams replies from your deployed Karta agent, and needs no backend of your own to get started. This page gets a widget live in under five minutes. For driving it from your page, see the command API; for who the end user is, see identity.
This page is for the deployed, drop-in widget. If you want to test a local frontend against karta dev before deploying, use the support-bot tutorial or point your own custom UI at the local session API printed by karta dev.

​
What you need

  • A deployed Karta agent (see the Quickstart).
  • A publishable embed key (pk_live_...) from the agent’s Embed tab.
The embed key is publishable - it is meant to ship in your page’s HTML. It is not a secret like a kt_live_... API key. Its blast radius is fenced by the allowed-origins allowlist you set in the dashboard, not by hiding the key. See Security & privacy.

​
Get an embed key

1

Open the agent's Embed tab

In the dashboard, open your agent and go to the Embed tab.
2

Create an embed key

Create a key. The full pk_live_... value is shown once - copy it now (afterward only the prefix is shown; rotate to recover). The tab also gives you a ready-to-paste <script> snippet with the key and agent filled in.
3

Add your site's origin to the allowlist

Add every origin the widget will run on (scheme + host + port, e.g. https://example.com) to Allowed origins. A browser request from an origin not on the list is refused at token mint. There are no wildcards - list each origin explicitly.

​
Add the script tag

Paste this once, near the end of your <body>. Replace the key and agent with your own (or use the snippet the dashboard generated).
That is the whole drop-in. The tag is async, so it never blocks your page; the loader reads its own data-* attributes, lazily fetches the UI on demand, and mounts a launcher in the corner.

​
Expected result

A chat launcher appears in the bottom-right corner. Clicking it opens the panel and starts a session against your agent; messages stream back token by token. The look and copy (accent color, greeting, suggested prompts) are pulled from the agent’s Embed-tab config at runtime - so you can restyle the widget without touching this tag. The displayed identity is the named Karta’s name when the key or URL selects one, and the underlying agent’s name otherwise. See Theming & config.

​
Hosted surfaces

If you want an agent-bound URL instead of the generic CDN loader, use one of the surfaces served from the agent host: Use the generic CDN loader when you want all configuration on your own page. Use the agent-bound loader when the agent coordinate should come from the URL itself.

​
Customize inline

You can override any theme field on the tag with data-theme-*:
See the full attribute list in Theming & config.

​
Where to go next

Command API & events

Open the widget from your own button, identify the user, and react to events with karta(...).

Identity

Anonymous, soft, and verified (HMAC) identity - and which one to use.

Authenticated agent

Server-side recipe for signed-in users and step-up.

Theming & config

The Embed-tab fields, runtime config, and the consent option.

Security & privacy

CSP directives, the origin allowlist, and the data path.