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', …).

Attributes

Attribute	Description
api-key	Your embed key.
backend-url	The DioscHub backend URL.
assistant-id	The assistant to load. Resolved from the embed key when omitted.
bind-endpoint	The host’s BYOA bind endpoint. The kit POSTs here when it needs to bind identity.
mode	fab (default) for the floating launcher, or embed for an inline, container-anchored panel.
position	bottom-right (default) or bottom-left. Ignored in embed mode.
embed-min-width-px	Minimum 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 (Enterprise tier). Without it the element renders nothing.

Events

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

Connection / auth

Event	Fires when	Payload
authenticated	The connection is authenticated.
disconnected	The connection drops.
reconnected	The connection is re-established.
rate_limited	A request is rate-limited.
auth:refreshed	The session credential is refreshed.
auth:failed	Authentication fails.
auth:required	The server asks the kit to (re)bind identity via the host bind endpoint.	{ reason: 'initial' | 'host_invalidate' | 'expired' | 'mcp_auth_fail' }
bind:ready	A host bind landed. Carries the bound identity (or null for anonymous), role feature flags, and the REST token.	{ identity, features, suggestions?, restToken, restTokenExpiresAt }
features:update	The bound role’s feature flags change while connected (e.g. an admin edits the role).	{ features, suggestions? }
rest_token:rotate	The server pushes a fresh REST token before the current one expires.	{ restToken, restTokenExpiresAt }

Session lifecycle

Event	Fires when
session:started	A new session begins.
session:joined	The client joins a session.
session:loaded	A session is loaded.
session:restored / session:restore_failed	A prior session is (or isn’t) restored.
session:invalid	A 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:list	The session list arrives.
session:renamed / session:pinned	A session is renamed or (un)pinned.
session:path_changed	The session’s page context changes.
session:state_changed	Session state changes.
session:user_changed	The session’s user identity changes.
session:upgraded	An anonymous session is promoted in place to an authenticated one (the visitor signed in).
session:error	A session-level error occurs.

Streaming

Event	Fires when
stream:start	The assistant begins responding.
stream:chunk	A chunk of the response arrives.
stream:end	The response completes.

Tools & approvals

Event	Fires when
tool:started / tool:completed / tool:failed	A tool call starts, completes, or fails.
approval:request	A gated tool call is awaiting approval.

Content & files

Event	Fires when
content_blocked	A response is blocked by content rules.
files:updated	The session’s files change.

Quota & context

Event	Fires when	Payload
quota:status	The message quota state updates.	{ used, limit, windowExpiresAt, percentUsed, blocked, warning }
quota:exceeded	A request is refused because the quota is spent.	{ used, limit, windowExpiresAt, percentUsed, blocked, warning }
context:status	The model’s context-window fill updates.	{ used, limit, percentUsed, warning, critical, modelId }

Browser surface

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

Event	Fires when	Payload
browser:read_page	The assistant requests the current page.
browser:navigate	The assistant requests a navigation.	{ params: { path } }
browser:browser_intent	The assistant calls a host-declared browser adapter intent.	{ intentName, args? }