Skip to content

Web component API

The widget is one custom element, <diosc-chat>. The embed loader mounts it for you; in a framework app you render it yourself. Configuration beyond the attributes below is set with diosc('config', …).

AttributeDescription
api-keyYour embed key.
backend-urlThe DioscHub backend URL.
assistant-idThe assistant to load. Resolved from the embed key when omitted.
bind-endpointThe host’s BYOA bind endpoint. The kit POSTs here when it needs to bind identity. Optional for an anonymous-only page: without it the hub binds the connection anonymously when the Assistant allows anonymous use (details).
modefab (default) for the floating launcher, or embed for an inline, container-anchored panel.
positionbottom-right (default) or bottom-left. Ignored in embed mode.
theme-modelight, dark, or system (follows the OS prefers-color-scheme, live). Picks which of the Assistant’s two color sets is active; unset uses the Assistant’s own theme mode. Can be changed at any time, re-themes in place. Same as diosc('setThemeMode', …); a command wins over the attribute and is reflected back to it. See Theming.
embed-min-width-pxMinimum container width (default 320) below which the embed frame shows a too-narrow placeholder. Ignored in fab mode.
<diosc-chat api-key="YOUR_EMBED_KEY" backend-url="https://your-hub.example.com"></diosc-chat>

When you embed via the loader script, you don’t set these by hand. The loader resolves them from your embed key and mounts the element for you.

Most of these can also be set with diosc('config', …). Set bind-endpoint as an attribute rather than through config: an attribute lands before auto-connect dispatches the bind, so it avoids a config/connect race.

mode="embed" requires the embeddedPanelMode capability. Every standard plan grants it, and so does a hub with no license key; without custom branding (a Pro capability) the panel keeps the “Powered by DioscHub” attribution. A custom plan that turns the capability off makes the element render nothing.

Subscribe with diosc('on', event, handler), or to all events with diosc('onAny', handler).

EventFires whenPayload
authenticatedThe connection is authenticated.
disconnectedThe connection drops.
reconnectedThe connection is re-established.
rate_limitedA request is rate-limited.
auth:refreshedThe session credential is refreshed.
auth:failedAuthentication fails.
auth:requiredThe server asks the kit to (re)bind identity via the host bind endpoint (with no bind endpoint, the kit asks the hub for an anonymous binding instead).{ reason: 'initial' | 'host_invalidate' | 'expired' | 'mcp_auth_fail' }
bind:readyA bind landed: the host’s, or the hub’s own anonymous binding on a page with no bind endpoint. Carries the bound identity (or null for anonymous), role feature flags, and the REST token (null for anonymous).{ identity, features, suggestions?, restToken, restTokenExpiresAt }
features:updateThe bound role’s feature flags change while connected (e.g. an admin edits the role).{ features, suggestions? }
rest_token:rotateThe server pushes a fresh REST token before the current one expires.{ restToken, restTokenExpiresAt }
EventFires when
session:startedA new session begins.
session:joinedThe client joins a session.
session:loadedA session is loaded.
session:restored / session:restore_failedA prior session is (or isn’t) restored.
session:invalidA restore is rejected because the session isn’t owned by the bound identity — the kit drops the persisted token and starts fresh. Payload: { code, message }.
session:listThe session list arrives.
session:renamed / session:pinnedA session is renamed or (un)pinned.
session:path_changedThe session’s page context changes.
session:state_changedSession state changes.
session:user_changedThe session’s user identity changes.
session:upgradedAn anonymous session is promoted in place to an authenticated one (the visitor signed in).
session:start_refusedDioscHub refused to start a chat, or the widget could not start one. Payload: { code, message, retryAfterMs?, scope? }. message is the plain sentence the widget shows the visitor; retryAfterMs and scope ('device' or 'ip') come with RATE_LIMITED. See When a chat can’t start.
session:errorA session-level error occurs. A refused chat start fires session:start_refused instead.
EventFires when
stream:startThe assistant begins responding.
stream:chunkA chunk of the response arrives.
stream:endThe response completes.
EventFires when
tool:started / tool:completed / tool:failedA tool call starts, completes, or fails.
approval:requestA gated tool call is awaiting approval.
EventFires when
content_blockedA response is blocked by content rules.
files:statusA file in the user’s library changes status or progress. Payload: { fileId, filename, mimeType, status, reason, warnings, progress, canRead, canSearch, isIndexed } (isIndexed is deprecated). See Chat files & indexing.
files:updatedA file the session uploaded finished indexing. Payload: { fileId, filename }.
EventFires whenPayload
quota:statusThe message quota state updates.{ used, limit, windowExpiresAt, percentUsed, blocked, warning }
quota:exceededA request is refused because the quota is spent.{ used, limit, windowExpiresAt, percentUsed, blocked, warning }
context:statusThe model’s context-window fill updates.{ used, limit, percentUsed, warning, critical, modelId }

These events drive client-side tools — the kit runs the request against the host page and returns the result.

EventFires whenPayload
browser:read_pageThe assistant requests the current page.
browser:navigateThe assistant requests a navigation.{ params: { path } }
browser:browser_intentThe assistant calls a host-declared browser adapter intent.{ intentName, args? }