Widget

The widget runs one of your agents inside a site you already own, as an inline component: you place a container in your page, the component renders there, and it grows with the conversation like any other content. It is part of your page flow: it never overlays your page or hovers in a corner of it. Under the hood it is an iframe on a dedicated origin, mounted by a small vanilla loader with no dependencies, under 5 KB gzipped. That shape is the security model, not an implementation detail: the agent runs in its own origin with its own storage and no access to your page, and your page has no access to it. The only thing that crosses the boundary is a versioned postMessage channel with an explicit target on both sides. The widget embeds the agent directly: the brain, not a page. It needs no project and no published page: an agent with knowledge and a site key is everything an embed requires.

What the visitor sees

The component is the wondeya ask-block, exactly as it looks on a wondeya page: a heading that invites the question, a rounded input with a send button, suggested questions to start from, and the AI disclosure notice. When the visitor asks, the agent answers with generative UI (text alongside rendered components), using the same renderer as wondeya pages. The conversation extends down your page and your page scrolls; the component never scrolls inside itself.

Install it

The loader CDN is not live yet: cdn.wondeya.com starts serving with the SDK 0.1.0 release, so you can create your site key and place the snippet now, and the widget appears the moment the loader is published.

Two tags: a container where the component should render, and the loader script with the site key of the agent you want to embed.

<div data-wondeya></div>
<script
  async
  src="https://cdn.wondeya.com/widget/v0.1/loader.js"
  data-agent="wdy_site_REPLACE_WITH_YOUR_KEY"
></script>

Put the div where the component should appear: the middle of a landing section, the end of a product page, a sidebar column. The script tag can go anywhere; before the closing body tag is the classic spot, and head is safe too, because if the loader runs before your container is parsed, it waits for DOMContentLoaded and looks once more. If [data-wondeya] does not suit your markup, point the loader at any element with data-container (see the options below). That is the whole installation, with one condition: your site’s origin must be registered on that site key. Until it is, the frame refuses to load. That is what stops somebody who copied your key from putting your agent on a page you do not control. An unregistered domain is a blank frame, by design.

Getting a site key

A site key identifies one agent and authorizes nothing. It is public by design: it ships inside your HTML where anyone can read it. What protects the endpoint is the origin allowlist plus wondeya’s anti-abuse stack, not the secrecy of the key. You create one for an agent together with the exact origins allowed to embed it. Today that happens over MCP: the create_site_key tool takes the agent and the allowlist,

{
  "agentId": "YOUR_AGENT_ID",
  "allowedOrigins": ["https://panaderialaflor.cl"]
}

and its response carries the key itself (wdy_site_…), the one place the full value appears: listings show a display prefix only. list_site_keys and rotate_site_key cover the rest of the lifecycle; the tool reference documents all three. Rules for allowedOrigins:

Up to 20 entries, each an exact origin: scheme, host, optional port. No path, no trailing slash, no wildcards. https://*.example.com is refused: one forgotten subdomain takeover on your side would otherwise become the right to frame your agent.
http:// is accepted only on loopback (http://localhost:3000), for development. A production site on plain HTTP would hand the “who may frame this” decision to whoever controls the network.
An origin that could never work is refused with an error that names it, so you can fix what you typed.
The list is fixed when the key is created and cannot be edited afterwards: to add or change an origin, create a new key with the full list and swap the snippet.

Rotating a site key issues a new one immediately and keeps the old one working for 24 hours, so already-deployed pages do not break while you update them. Rotation keeps the agent and the origins as they are.

The console screen for site keys and embed origins is on the way; until it lands, the MCP tools are how you create and manage them.

Calling the API before the loader arrives

async means the loader may not have parsed when your own code runs. Add the queue stub above the snippet and call wondeya(...) whenever you like; calls are replayed in order once the widget exists:

<script>
  window.wondeya =
    window.wondeya ||
    function () {
      (window.wondeya.q = window.wondeya.q || []).push(arguments);
    };
  wondeya('identify', { id: 'user_42', traits: { name: 'Ana', plan: 'pro' } });
  wondeya('on', 'ready', () => console.log('widget ready'));
</script>
<div data-wondeya></div>
<script
  async
  src="https://cdn.wondeya.com/widget/v0.1/loader.js"
  data-agent="wdy_site_REPLACE_WITH_YOUR_KEY"
></script>

Options

All optional, all set as attributes on the script tag.

Attribute	Default	What it does
`data-agent`	(none)	Required. The site key (`wdy_site_…`).
`data-container`	first `[data-wondeya]`	CSS selector of the element the component mounts into. Unset, the loader mounts into the first element matching `[data-wondeya]`.
`data-locale`	the agent’s own	BCP-47 tag (`es`, `en`, `es-419`). Sets the language of the widget’s own interface.
`data-origin`	`https://widget.wondeya.com`	Only for local development.

Appearance

The widget ships with wondeya’s look; these attributes override it for this embed. They travel to the frame in the iframe URL and are validated on both sides: an invalid value is one console warning and that key falling back to its default, never a broken widget.

Attribute	Values	What it does
`data-primary`	`#rrggbb` (or `rrggbb`)	Primary brand color. Paints the send button, among other things.
`data-accent`	`#rrggbb`	Highlights and links inside the conversation.
`data-surface`	`#rrggbb`	Background of the component’s surfaces.
`data-ink`	`#rrggbb`	Text color.
`data-muted`	`#rrggbb`	Secondary text color.
`data-radius`	`none` `sm` `md` `lg` `full`	Corner rounding of the component’s UI. Default `lg`.
`data-font`	`montserrat` `inter` `source-serif` `inherit`	The widget’s typeface. `inherit` adopts your page’s; see below.

Colors are 6-digit hex and nothing else; radii and typefaces are closed lists. There is no way to pass free CSS to the widget, on purpose: the same closed vocabulary that guards a wondeya page guards the embed. data-font="inherit" cannot use your web fonts. The widget is an iframe, a separate document, and fonts loaded by your page never cross into it. inherit reads your page’s computed font stack off body and forwards it, so the widget matches your site wherever that stack resolves to system or locally installed fonts, and falls back to the widget’s default typeface where it does not.

How it sizes itself

The component behaves like a block of your own page, and the two dimensions come from two different places:

Width follows the container. The iframe is always 100% of the element it mounted into, so you control width the way you control any layout: size the container. A 360px column gives you a narrow component; a full-width section gives you a wide one.
Height follows the conversation. The frame measures its own document and reports the height over the postMessage channel; the loader applies it to the iframe. As answers arrive and components render, the component grows and the content below it moves down: your page scrolls, the component does not. There is nothing to configure. The loader sanity-checks every reported height before applying it, so even a compromised frame could not paint your page into a mile-long iframe.

The iframe carries loading="lazy": a component below the fold costs your page nothing until the visitor scrolls near it.

The JavaScript API

wondeya('init', { agent: 'wdy_site_…' }); // only if you skipped data-agent
wondeya('identify', { id: 'user_42', traits: { plan: 'pro' } });
wondeya('on', 'ready', handler);
wondeya('destroy');                       // removes everything it added

init accepts every option in the two tables above, under the same names without the data- prefix and with the same validation; container may be a CSS selector string or the DOM element itself. Anything the loader does not recognize (an unknown command, a malformed argument) is one console.warn prefixed [wondeya] and a no-op, never an exception in your page.

Events

Event	When it fires
`ready`	The frame finished its handshake. The frame loads with your page; with `loading="lazy"`, a component below the fold loads when the visitor scrolls near it, and `ready` fires then.
`turn-started` / `turn-completed`	A question is being answered. `turn-completed` fires when the turn ends, even after an error; `turn-failed` is reserved in the protocol and never fires today.

If you want to know the loader itself is live before any of that, read window.wondeya.loaded.

`identify` is not authentication

It is display data. Any script on your page, such as an analytics tag or a browser extension, can send it, so nothing is ever authorized by it and it must never carry a secret. Traits are capped at 12 keys and 120 characters each, and anything that is not a short string is dropped before it leaves your page.

React

npm install @wondeya/react

@wondeya/react is not on the npm registry yet; it publishes with the same SDK 0.1.0 release as the loader.

import { WondeyaWidget } from '@wondeya/react';

export const AskSection = () => (
  <section>
    <h2>Ask us anything</h2>
    <WondeyaWidget
      siteKey="wdy_site_…"
      identify={{ traits: { plan: 'pro' } }}
      appearance={{ primary: '#0f172a', radius: 'full', font: 'inherit' }}
      onEvent={(event) => console.log('[widget]', event)}
      className="ask-block"
    />
  </section>
);

The component renders a plain div at its position in your tree and mounts the widget inside it. className and style land on that div; that is how you control width and placement, exactly as for any other block. appearance takes the same values as the data-* attributes above, with the same validation and the same inherit limitation; onEvent receives every event from the table above. On unmount it removes everything it added, which is the part a plain script tag cannot do in a single-page app. The wrapper is deliberately thin: every behaviour lives in the loader, so a React app and a script tag get the same widget rather than two that drift.

Content-Security-Policy

If your site sends a CSP (and it should), add these three sources:

script-src  https://cdn.wondeya.com;
frame-src   https://widget.wondeya.com;
connect-src https://api.wondeya.com;

script-src: the loader itself. With a nonce-based policy, put your nonce on the script tag; the loader adds no inline scripts of its own.
frame-src: the widget’s iframe. Without it the frame is blocked and your container stays empty.
connect-src: the chat request. It is made by the iframe, from its own origin, so strictly it is governed by the iframe’s policy and not yours. Some CSP linters and older browsers still flag it; adding it costs nothing and prevents a confusing report.

You do not need style-src 'unsafe-inline'. The loader styles only the elements it created, using element style attributes, which a CSP does not govern. It loads no fonts, no images and no analytics from your page.

wondeya’s side of the deal

The embed document ships its own policy, built per site key on the server before the document exists:

default-src 'none', then only what the page genuinely needs;
connect-src is the frame’s own origin plus wondeya’s API;
img-src is the frame’s own origin, data: URIs and wondeya’s CDN;
object-src 'none' and base-uri 'none';
when bot protection is on, Cloudflare Turnstile’s challenge origin (https://challenges.cloudflare.com) joins script-src and frame-src;
frame-ancestors lists only the origins you registered. No wildcards are accepted, and an empty allowlist becomes 'none' rather than *. If any registered origin fails to validate, the whole list collapses to 'none' instead of silently serving a weaker policy than you configured.

So even somebody holding your site key cannot frame your agent on their own site.

Versioning and the SRI trade-off

Every release is published to two URLs:

URL	Cache	Use it when
`…/widget/v0.1/loader.js`	5 minutes	You want fixes automatically. The default, and what the snippet above uses.
`…/widget/0.1.0/loader.js`	immutable, 1 year	You pin versions and upgrade deliberately.

Subresource Integrity is incompatible with the auto-updating channel, and that is not a bug in either. integrity="sha384-…" tells the browser to refuse a file whose bytes changed, which is exactly what the auto-updating channel does when a fix ships. Pick one:

auto-update, no SRI: you get security fixes without touching your site, and you trust wondeya’s CDN. The right default for almost everyone.
pinned plus SRI: a byte-exact guarantee, so a compromise of the CDN cannot reach your visitors. In exchange, a fix reaches you when you deploy, not before.

<script
  async
  src="https://cdn.wondeya.com/widget/0.1.0/loader.js"
  integrity="sha384-…"
  crossorigin="anonymous"
  data-agent="wdy_site_…"
></script>

Every release publishes its hash next to the artifact. A channel URL never changes what it promises: while wondeya is pre-1.0 the channel is v0.1 and the next breaking release opens v0.2, with the old one kept alive. From 1.0.0 onwards it is v1, and every 1.x fix arrives on it.

Troubleshooting

The loader never throws into your page: a widget must not be able to break the site it is on. Everything it complains about is a console.warn prefixed [wondeya].

Symptom	Cause
`[wondeya] missing or malformed data-agent`	The site key is wrong or truncated. Copy it again.
The component does not appear, and the console shows a `[wondeya]` warning about the container	There is no `<div data-wondeya></div>` on the page, or your `data-container` selector matched nothing. Add the container where the component should render.
The component’s space stays blank, no container warning	Your origin is not registered on that site key, or the key was revoked.
Nothing at all, no warning	The script never loaded. Check `script-src` and your ad blocker.
`[wondeya] … was called before init`	You called the API without the queue stub. Add it, or call `wondeya('init', …)` first.
`[wondeya] already initialized`	Two snippets on one page. Remove one, or call `wondeya('destroy')` first.

Get Started

Build Your Page

Add It To Your Site

Under The Hood

Trust

What the visitor sees

Install it

Getting a site key

Calling the API before the loader arrives

Options

Appearance

How it sizes itself

The JavaScript API

Events

`identify` is not authentication

React

Content-Security-Policy

wondeya’s side of the deal

Versioning and the SRI trade-off

Troubleshooting

​What the visitor sees

​Install it

​Getting a site key

​Calling the API before the loader arrives

​Options

​Appearance

​How it sizes itself

​The JavaScript API

​Events

​identify is not authentication

​React

​Content-Security-Policy

​wondeya’s side of the deal

​Versioning and the SRI trade-off

​Troubleshooting

What the visitor sees

Install it

Getting a site key

Calling the API before the loader arrives

Options

Appearance

How it sizes itself

The JavaScript API

Events

`identify` is not authentication

React

Content-Security-Policy

wondeya’s side of the deal

Versioning and the SRI trade-off

Troubleshooting