Agent Embed Widget

Overview

The Agent Embed Widget adds a LiveKit Cloud agent to any website without building a frontend. Paste a script tag into your page, and your users see a launcher button in the bottom-right corner. Clicking it opens a pop-up where they talk to your agent.

The same agent can run on multiple sites with different branding, and you can pass per-user data through the snippet to personalize each session.

If your agent isn't on LiveKit Cloud, or you need full control over the frontend, use the open-source Web embed starter app instead.

Adding the widget

Configure and enable the widget from the agent's page in the LiveKit Cloud dashboard. You need the Write role on the project to enable, configure, or disable the widget.

The following steps add a widget and generate a snippet you can embed on your site:

1. In the Agents dashboard , open the agent you want to embed.

2. Click Embed.

3. On the Install tab, add an entry to Allowed origins for each site where you want to install the widget.

4. On the Settings tab, configure the theme, button color, icon, and enabled capabilities.

5. Return to the Install tab, toggle Embed widget on, and click Save changes. The widget doesn't take effect until you save. You can toggle it off later from the same place without changing your snippets.

6. Copy the generated <script> snippet and paste it into your page's HTML, typically just before </body>. The snippet looks like this, with your agent's ID filled in:

   <script src="https://cloud.livekit.io/embed-popup.js" data-lk-agent="CA_abc123"></script>

Allowed origins

Add every origin where you want the widget to run. Each must use http:// or https:// and can't include a path, query string, fragment, or trailing slash. If someone copies the snippet to an unlisted site, the widget receives no token and doesn't load.

Allowed origins support:

• Exact origins, such as https://example.com, https://app.example.com:8443, or http://localhost:5500.
• Leading-subdomain wildcards, such as https://*.example.com. This matches https://app.example.com but not https://a.b.example.com and not https://example.com. A full wildcard (*) isn't supported.

Enabled capabilities

Voice is always enabled in the widget. The Settings tab also lets you turn camera input, screen share, and text chat on or off. When chat is enabled, the chat pane shows both typed messages and live conversation transcripts.

Capabilities are enforced by LiveKit Cloud, so snippet attributes can't enable a capability that's disabled in the dashboard.

Customize the snippet

The widget has two configuration layers. The dashboard sets defaults that apply to every page where this agent's widget is installed. Snippet attributes override those defaults for a specific placement, and they're the only way to pass per-user data, which the dashboard doesn't store.

For most setups, the dashboard alone is enough. Use snippet attributes when you need overrides for a specific placement or want to pass per-user context to the agent.

To embed the same agent on multiple sites with different colors, logos, or themes, hard-code cosmetic attributes in the HTML:

<script
  src="https://cloud.livekit.io/embed-popup.js"
  data-lk-agent="CA_abc123"
  data-lk-color="#0a84ff"
  data-lk-logo="https://example.com/logo.svg"
  data-lk-theme="system"
></script>

To pass context about the signed-in user to the agent, inject per-user attributes from your backend or templating engine when rendering the page:

<script
  src="https://cloud.livekit.io/embed-popup.js"
  data-lk-agent="CA_abc123"
  data-lk-identity="user_8421"
  data-lk-name="Ada Lovelace"
  data-lk-job-metadata='{"plan":"pro","account_id":"acc_123"}'
  data-lk-attrs='{"locale":"en-US"}'
></script>

All attributes

You can use the following attributes in the snippet to customize the widget:

Limitations

• Only LiveKit Cloud agents are supported.
• The snippet can't override the capabilities you set in the dashboard, the room name, or how the agent is dispatched.
• Only one widget can mount per page.

Use the Web embed starter app when you need to work around any of these.

Additional resources