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.

Prerequisites

• 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.

Fastest path: install and mount

Install the client package:

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.

Note

loadDiosc touches window, so call it in the browser only. In server-rendered frameworks, guard the call so it runs on the client.

Vanilla HTML

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>

React version

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.

Connect the signed-in user

The example above runs anonymously. 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.

Drive the widget

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();

Next steps

• Give the Assistant an action: Quickstart: add an MCP tool.
• Bind identity, declare host intents, and add approval handling: Build.