API reference

Types

The exact public type surface, verbatim from source. This is the canonical reference — hook and prop signatures elsewhere are abbreviated for reading; when they differ, trust this page.

Where each type lives

Most types are re-exported from @dialogueai/react. A few are currently exported only from @dialogueai/web-sdk-core — import those from core, or rely on structural typing. The per-type notes below say which is which.

Import from	Types
`@dialogueai/react`	`Phase`, `DialogueLocale`, `ConnectionQuality`, `PermissionStatus`, `ErrorCode`, `DialogueEvents`, `CoreState`, `Study`, `StudyPublic`, `StudyScreener`, `ScreenerQuestion`, `TranscriptSegment`, `MediaState`, `DialogueProviderProps`, plus `DialogueError`/`isDialogueError` (values).
`@dialogueai/web-sdk-core` only	`ParticipantUpdate`, `BootstrapTokenResult`, `AbortReason`, `AnonymousNamesLocale`, `Gender`, `ScreenerOption`, `StudyConfig`.

There is no Company type. useConsent().company is the nullable StudyPublic.company shape { name: string; logoUrl: string | null } | null — not the richer Study.company (which has id/slug). Don’t import a Company name; it doesn’t exist.

Phase

The 19 journey phases. See The interview journey for meaning + transitions.

type Phase =
  | 'idle' | 'bootstrapping' | 'ready' | 'study' | 'consent'
  | 'creatingInterview' | 'profile' | 'screener' | 'deviceCheck'
  | 'connecting' | 'live' | 'ending' | 'processing' | 'completed'
  | 'aborted' | 'screenedOut' | 'studyClosed' | 'alreadyCompleted' | 'errored';

Locales

DialogueLocale (interview/UI locale, uppercase) and AnonymousNamesLocale (the anonymous-name vocabulary, lowercase, passed to useAnonymousNames). Same 17 languages, different casing — do not mix them.

type DialogueLocale =
  | 'EN' | 'ES' | 'JA' | 'PT' | 'ZH' | 'DE' | 'FR' | 'IT' | 'SW'
  | 'VI' | 'TH' | 'MS' | 'ID' | 'HI' | 'KO' | 'UK' | 'PL';

type AnonymousNamesLocale =
  | 'zh' | 'en' | 'ja' | 'pt' | 'es' | 'de' | 'fr' | 'it' | 'sw'
  | 'vi' | 'th' | 'ms' | 'id' | 'hi' | 'ko' | 'uk' | 'pl';

Default locale resolution when the locale prop is omitted: navigator.language (first segment, uppercased) if it’s a supported code, else 'EN'. Today 'EN' is fully translated; the other 16 bundles carry the complete key set but currently mirror EN as placeholders, so non-EN UIs render in English until translations land.

Status enums

type ConnectionQuality = 'excellent' | 'good' | 'poor' | 'lost' | 'reconnecting';

type PermissionStatus =
  | 'granted' | 'denied' | 'dismissed'
  | 'not-readable' | 'not-found' | 'overconstrained';

// @dialogueai/web-sdk-core only
type AbortReason = 'consent.declined' | 'unload' | 'host.abort' | 'backend.abandoned';

// @dialogueai/web-sdk-core only
type Gender = 'MALE' | 'FEMALE' | 'OTHER' | 'PREFER_NOT_TO_SAY';

useDevicePermissions() reports a narrower set — 'prompt' | 'granted' | 'denied' — not the full PermissionStatus.PermissionStatus is what the permission event carries.

Auth

// @dialogueai/web-sdk-core only — what bootstrapTokenProvider must resolve to.
interface BootstrapTokenResult {
  bootstrapToken: string;
  expiresAt: string;   // ISO 8601 UTC
}

Study & branding

// The full study record (useInterview().study, useStudy().study).
interface Study {
  id: string;
  company: { id: string; name: string; slug: string };
  projectId: string;
  name: string;
  background: string;
  objective: string;
  numInterviews: number;
  estimatedDurationSecs: number;
  primaryLocale: DialogueLocale;
  redirectUrl: string | null;
  state: string;            // 'ACTIVE' | 'PAUSED' | 'COMPLETED' | ...
  allowAnon: boolean;
  sections: Section[];
  sectionGroups: SectionGroup[];
}

// The public, device-check + branding view (useStudy().studyPublic).
interface StudyPublic {
  id: string;
  type: 'QUAL' | 'QUANT';
  estimatedDurationSecs: number;
  config: StudyConfig;
  company: { name: string; logoUrl: string | null } | null;  // useConsent().company
}

// useStudy().requirements === studyPublic.config.media
interface StudyConfig {
  privacy: { brand: { showCompany: boolean } };
  media: {
    microphone: { requirement: MediaRequirement };
    webcam: { requirement: MediaRequirement };
    screen: { requirement: MediaRequirement; audio: MediaRequirement; surfaces: ScreenSurface[] };
  };
}

type MediaRequirement = 'required' | 'preferred' | 'disabled';
type ScreenSurface = 'tab' | 'window' | 'monitor';

Screener

interface StudyScreener {
  id: string;
  studyId: string;
  questions: ScreenerQuestion[];
}

interface ScreenerQuestion {
  id: string;
  type: 'SINGLE_SELECT' | 'MULTI_SELECT';
  question: string;
  order: number;
  isRandomized: boolean;
  minOptions: number | null;
  maxOptions: number | null;
  options: ScreenerOption[];
}

// @dialogueai/web-sdk-core only
interface ScreenerOption {
  id: string;
  option: string;          // the label
  order: number;
  allowInput: boolean;     // reveals a free-text input when selected
  isExclusive: boolean;    // selecting deselects all others (MULTI_SELECT)
  isPinned: boolean;
  rule: 'MUST_SELECT' | 'MAY_SELECT' | 'REJECT';
}

Participant

The argument to useParticipantProfile().update(...). Every field is optional; null clears it.

// @dialogueai/web-sdk-core only
interface ParticipantUpdate {
  firstName?: string | null;     // max 50
  lastInitial?: string | null;   // single character — NOT a last name
  email?: string | null;         // max 254
  gender?: Gender | null;        // uppercase enum — NOT 'man' | 'woman'
  dob?: string | null;           // 'YYYY-MM-DD' — participant must be >= 18
  city?: string | null;
  state?: string | null;
  country?: string | null;
  countryCode?: string | null;   // ISO 3166-1 alpha-2
  coordinates?: { lat: number; lng: number } | null;
}

Media & agent

interface TranscriptSegment {
  text: string;
  isFinal: boolean;
}

// useMediaState() — the React-side live media store.
interface MediaState {
  quality: ConnectionQuality;
  speaking: boolean;
  sectionIndex: number;
  transcript: TranscriptSegment[];
  screenShareActive: boolean;
  micMuted: boolean;
  localCameraTrack: MediaStreamTrack | null;
}

Errors & events

The full ErrorCode union and DialogueEvents payload map live on their own pages to avoid drift: Errors and Events. Remember the two error shapes — the thrown DialogueError class vs. the { code, message, recoverable } event payload that hooks expose.

For agents: prefer importing types from @dialogueai/react. If an import fails, check the table at the top — it’s probably one of the core-only types. Never invent participantHint or a Company type; neither exists in the current surface.