Skip to content

Quickstart: embed the chat

Embed the DioscHub chat widget in your frontend and connect it to an Assistant. By the end you’ll have a working chat surface on your page, talking to a running DioscHub.

  • A running DioscHub with an Assistant configured, and that Assistant’s embed key. The embed key is a public credential by design. It identifies which Assistant the widget loads and is meant to ship in frontend code.
  • Node and npm, for the install path below.

Replace these placeholders throughout:

  • YOUR_EMBED_KEY: your Assistant’s embed key.
  • https://your-hub.example.com: the public URL of your DioscHub.

Install the client package:

Terminal window
npm install @dioschub/client

Load the kit, configure it, and mount the diosc-chat element:

import { loadDiosc } from '@dioschub/client';
const { diosc, ready } = loadDiosc({
backendUrl: 'https://your-hub.example.com',
apiKey: 'YOUR_EMBED_KEY',
});
// Commands issued before the script finishes loading are buffered and replayed.
diosc('config', {
backendUrl: 'https://your-hub.example.com',
apiKey: 'YOUR_EMBED_KEY',
autoConnect: true,
});
await ready; // optional, resolves once the kit has loaded

Then place the widget element anywhere in your page:

<diosc-chat></diosc-chat>

The widget renders a floating button. Open it and send a message; responses stream in as they’re generated.

Without a build step, set up the command queue inline, configure the Assistant, then load the kit script:

<script>
(function () {
const q = [];
const diosc = function () { q.push(Array.prototype.slice.call(arguments)); };
diosc.q = q;
window.diosc = diosc;
diosc('config', {
backendUrl: 'https://your-hub.example.com',
apiKey: 'YOUR_EMBED_KEY',
autoConnect: true,
});
})();
</script>
<script type="module"
src="https://your-hub.example.com/api/embed/YOUR_EMBED_KEY/loader.js"></script>
<diosc-chat></diosc-chat>

This mirrors the storefront sample. It loads the kit once, configures it when the script is ready, then connects.

'use client';
import { useEffect, useRef, useState } from 'react';
import { loadDiosc } from '@dioschub/client';
import type { DioscConfig } from '@dioschub/client';
declare module 'react' {
// eslint-disable-next-line @typescript-eslint/no-namespace
namespace JSX {
interface IntrinsicElements {
'diosc-chat': Record<string, unknown>;
}
}
}
const BACKEND_URL = 'https://your-hub.example.com';
const API_KEY = 'YOUR_EMBED_KEY';
export function AssistantProvider() {
// loadDiosc touches `window`, so create the handle on the first client render.
const handleRef = useRef<ReturnType<typeof loadDiosc> | null>(null);
if (!handleRef.current && typeof window !== 'undefined') {
handleRef.current = loadDiosc({ backendUrl: BACKEND_URL, apiKey: API_KEY });
}
const [configured, setConfigured] = useState(false);
// Configure once the kit script is ready.
useEffect(() => {
const handle = handleRef.current;
if (!handle) return;
let cancelled = false;
handle.ready.then(() => {
if (cancelled) return;
const config: DioscConfig = {
backendUrl: BACKEND_URL,
apiKey: API_KEY,
autoConnect: false,
};
handle.diosc('config', config);
setConfigured(true);
});
return () => { cancelled = true; };
}, []);
// Connect once configured.
useEffect(() => {
const handle = handleRef.current;
if (!configured || !handle) return;
handle.diosc('connect');
return () => handle.diosc('disconnect');
}, [configured]);
return <diosc-chat />;
}

Render <AssistantProvider /> once, high in your component tree.

The example above runs anonymously. With no bindEndpoint, DioscHub binds the visitor anonymously itself when the Assistant’s anonymous mode is on, so the widget shows what the anonymous Role grants (New Chat, starter suggestions). To bind your signed-in user’s identity to the Session, add a bindEndpoint to your config, a same-origin route on your own server that authenticates the user and forwards their identity to DioscHub. Auth artifacts pass through your endpoint, never through the widget’s configuration.

diosc('config', {
backendUrl: 'https://your-hub.example.com',
apiKey: 'YOUR_EMBED_KEY',
bindEndpoint: '/api/diosc/bind',
autoConnect: false,
});

Binding is its own step. See Identity & auth for the bind route, and the BYOA security model for how identity and credentials flow through DioscHub.

The global diosc() command API controls the widget at runtime. A few useful commands:

diosc('open'); // open the chat panel
diosc('close'); // close it
diosc('toggle'); // toggle open/closed
// Connection control
diosc('connect');
diosc('disconnect');
// Move the floating button to the other corner
diosc('setPosition', 'bottom-left');

You can also subscribe to events. For example, refresh your own UI after the Assistant completes a tool call:

const off = diosc('on', 'tool:completed', () => {
// re-pull whatever the Assistant may have changed
});
// later: off();