Web Plugin

Use the Web Plugin when a Siesta AI agent should live on a website, customer portal, documentation site, or internal tool. This page gives developers the runtime contract, safe test flow, and rollout checks needed to embed the widget without exposing API keys or breaking an existing page.

The product settings for the agent live in Agents > Interfaces. Developers use this page after the agent is configured and the embed needs to be added, tested, or handed to a customer.

Runtime Contract

The widget has a small browser contract:

Load chat-widget.js from the Siesta app environment.
Mount one <siestaai-chat-widget> custom element.
Pass the public or authenticated agent ID as data-chatbot-id.
Pass the matching app host as data-base-url.
Use data-environment="dev" only for dev or preview agents.
Keep API keys and organization secrets out of browser code.

The widget can run on a normal website without the External API. It uses the selected agent's public or authenticated widget configuration from Siesta AI.

Playground Flow

Use the Widget Playground when you want a dedicated docs-hosted sandbox for one widget bubble without colliding with the support widget that runs across the rest of the docs site.

Quick Embed

Production embed:

<script
  src="https://app.siesta.ai/chat-widget/chat-widget.js"
  defer>
</script>

<siestaai-chat-widget
  data-chatbot-id="<agent-id>"
  data-base-url="https://app.siesta.ai">
</siestaai-chat-widget>

Development preview embed:

<script
  src="https://app-dev.siesta.ai/chat-widget/chat-widget.js"
  defer>
</script>

<siestaai-chat-widget
  data-chatbot-id="3481f077-b4e2-4760-7531-08de5443a751"
  data-base-url="https://app-dev.siesta.ai"
  data-environment="dev">
</siestaai-chat-widget>

Use the dev agent for internal checks. Use the production agent only after prompts, allowed origins, privacy links, feedback settings, file upload settings, and public access rules have been reviewed.

Where To Get Values

Value	Source	Notes
`data-chatbot-id`	Agents > Interfaces	Copy the agent ID from the agent that should answer visitors.
`data-base-url`	Siesta app environment	Use `https://app.siesta.ai` for production and `https://app-dev.siesta.ai` for dev.
`data-environment`	Deployment target	Omit for production. Use `dev` for the dev widget bundle.
Auth client ID	Agents > Interfaces authenticated widget settings	Required only when the widget should force Google sign-in.
Privacy link	Public chat settings	Must be set before using the widget on public pages.

Test Flow

Do not mount a second live test widget directly inside this documentation page. The docs site already runs a Siesta support widget, and two widgets on the same page can make validation misleading.

Use this flow instead:

Configure the agent in Agents > Interfaces.
Copy the generated snippet or build one from the contract above.
Test the snippet on the Widget Playground, a neutral local HTML page, staging website, or another dedicated widget preview surface.
If the target website blocks iframe previews, open the real target page and use the DevTools injector below.
Confirm the widget opens, sends a message, receives a useful answer, respects allowed files/feedback/realtime settings, and shows the correct privacy link.

DevTools Injector

Use this snippet when a customer website blocks iframe previews or when you need to validate the widget on the real DOM before code is deployed. Paste it into the browser DevTools Console on the target page.

(() => {
  const botId = '06b4e39c-56b7-47e1-2a91-08de539d8b24';
  const env = 'prod';
  const baseUrl = 'https://app.siesta.ai';
  const scriptSrc = baseUrl + '/chat-widget/chat-widget.js';

  const mountWidget = () => {
    document
      .querySelectorAll('siestaai-chat-widget[data-siesta-preview="true"]')
      .forEach((el) => el.remove());

    const widget = document.createElement('siestaai-chat-widget');
    widget.setAttribute('data-chatbot-id', botId);
    widget.setAttribute('data-base-url', baseUrl);
    widget.setAttribute('data-environment', env);
    widget.setAttribute('data-siesta-preview', 'true');
    document.body.appendChild(widget);
  };

  if (customElements.get('siestaai-chat-widget')) {
    mountWidget();
    return;
  }

  const existingScript = Array.from(document.scripts).find((script) => script.src === scriptSrc);
  if (existingScript) {
    customElements.whenDefined('siestaai-chat-widget').then(mountWidget);
    return;
  }

  const script = document.createElement('script');
  script.src = scriptSrc;
  script.defer = true;
  script.onload = () => customElements.whenDefined('siestaai-chat-widget').then(mountWidget);
  script.onerror = () => console.error('Siesta widget script failed to load:', scriptSrc);
  document.head.appendChild(script);
})();

Change botId, env, and baseUrl before sharing the snippet with another developer.

Page Context Injection

The widget can be paired with lightweight public page context when the assistant should understand where the visitor is. Keep this context safe: do not include cookies, tokens, hidden form values, account IDs, or private user data.

<script>
  window.siestaWidgetContext = {
    pageUrl: window.location.href,
    pageTitle: document.title,
    selectedText: '',
    purpose: 'Help the visitor understand this page and answer product questions.'
  };
</script>

Use page context for lightweight page assistance, documentation support, onboarding, or lead qualification. For reliable answers across a full website, use a data collection, scraper-backed source, or connected knowledge tool instead of relying only on the current DOM.

Use authenticated widget mode for customer portals, intranets, or partner areas where the agent should avoid anonymous access. Configure the authenticated widget in Agents > Interfaces, then use the generated script from the product UI. The current developer playground focuses on the manifest-backed public widget contract, so authenticated widget validation should still happen in a dedicated customer or internal test surface.

Authenticated deployments should verify:

the Google OAuth client ID belongs to the correct customer or environment,
allowed origins include the target website,
the agent prompt explains what user identity means in this portal,
public access is disabled when anonymous visitors should not use the agent,
privacy and retention settings match the customer's policy.

Runtime Options

Attribute	Required	Use
`data-chatbot-id`	Yes	Selects the Siesta AI agent.
`data-base-url`	Recommended	Pins the widget to the intended Siesta app host.
`data-environment`	Dev only	Marks preview widgets that use the dev environment.
`data-siesta-preview`	Test only	Makes injected preview widgets easy to remove.
Auth-specific attributes	When enabled	Use the generated authenticated widget snippet from Agents > Interfaces.

Rollout Checklist

Before customer handoff:

The widget loads without console errors.
The launcher appears in the intended position on desktop and mobile.
The first answer matches the selected agent, not another environment.
Public chat settings allow only the intended capabilities.
File upload, feedback, reasoning visibility, and realtime audio match the product decision.
The privacy link opens the correct customer policy.
The page is not sending secrets through window.siestaWidgetContext.
The target site CSP allows chat-widget.js from the selected Siesta app host.
The support team knows which agent ID and environment were deployed.

Runtime Contract​

Playground Flow​

Quick Embed​

Where To Get Values​

Test Flow​

DevTools Injector​

Page Context Injection​

Authenticated Widget​

Runtime Options​

Rollout Checklist​