Get started

Installation

Which packages to install for each integration style, plus peer requirements and the stylesheet.

Choose your packages

Integration	Install
Styled drop-in	`@dialogueai/react-ui` + `@dialogueai/react`
Headless / custom UI	`@dialogueai/react`
Non-React page	`@dialogueai/loader` (or the CDN script)
Non-React framework, direct core	`@dialogueai/web-sdk-core`

bash

pnpm add @dialogueai/react @dialogueai/react-ui

@dialogueai/react re-exports the core’s public contract (types, DialogueError, phases), so a React integrator rarely installs @dialogueai/web-sdk-core directly. The core is the framework-agnostic orchestrator (DialogueCore) for non-React hosts and tests; it has no dedicated guide yet, so start from Architecture and the Types reference if you need to drive it directly.

Peer dependencies

react and react-dom 18 — peer of @dialogueai/react and @dialogueai/react-ui.
livekit-client is bundled and driven internally. Never import it directly. Host code reaches the connection only through useConnection().

Importing styles

The styled layer ships a precompiled stylesheet. Import it once, anywhere in your app (importing it more than once is harmless):

import '@dialogueai/react-ui/styles.css';

By default the UI also mounts inside a Shadow DOM root and injects the same styles there, so it is isolated from your page’s CSS. You can opt out via appearance.shadowRoot; see Appearance & theming.

The CDN loader

For non-React pages, drop the hosted stub. It installs window.Dialogue, stays tiny, and lazy-loads the React tree on the first open().

index.htmlhtml

<script async src="https://sdk.dialogue.ai/v1/dialogue.js"></script>
<script>
  window.Dialogue = window.Dialogue || function () { (Dialogue.q = Dialogue.q || []).push(arguments) };
  Dialogue('init', { publishableKey: 'pk_live_…' });
  Dialogue('open', { studyId: '019e16c4-…' });
</script>

SSR & Next.js

The SDK is browser-only (it touches navigator.mediaDevices, WebRTC, the DOM). In the App Router, mount it from a Client Component ('use client') so it never runs during server rendering. The packages are consumed as their built dist, so you don’t need transpilePackages.

Live media requires a secure context (HTTPS or localhost) and, inside an iframe, an explicit allow="camera; microphone; display-capture". Check support up front with usePreflight().

Same-origin proxy (baseUrl)

By default the SDK calls the Dialogue REST API at its own origin (cross-origin from your page). The optional baseUrl prop points those REST calls at a path on your origin instead, which you proxy to Dialogue. Reach for it when:

a strict connect-src CSP only allows same-origin requests;
ad/tracker blockers interfere with the third-party API origin; or
you want all REST traffic to appear first-party in your logs.

next.config.mjsts

// Proxy /dlg/* on your origin to the Dialogue API.
export default {
  async rewrites() {
    return [{ source: '/dlg/:path*', destination: 'https://api.dialogueai.com/:path*' }];
  },
};

tsx

<DialogueProvider baseUrl="/dlg" bootstrapTokenProvider={getToken}>
  <Interview studyId={studyId} />
</DialogueProvider>

A proxy only covers the REST traffic. The live interview is WebRTC to LiveKit and connects to LiveKit’s own origins directly — it does not route through baseUrl. If a CSP is the reason you need a proxy, you must still allow the LiveKit origins in connect-src/media-src or you’ll hit host.csp-blocks-livekit.