Skip to Content
🚀 Orga AI is in open beta.

Types

The Widget SDK exports TypeScript interfaces and enums for configuration, theming, and branding. These types are used when calling initWidget() and customizing the widget appearance.


Core Types

WidgetInitOptions

Main configuration object passed to initWidget().

export type WidgetInitOptions = { /** * HTMLElement or selector that will host the widget UI. * Defaults to the first element with `[data-orga-widget]`. */ target?: HTMLElement | string; /** * Function that returns the session configuration (ephemeral token + ICE servers). * Mirrors the existing React SDK requirement so we can reuse backends. */ fetchSessionConfig: () => Promise<SessionConfigResponse>; /** * Optional session configuration endpoint to seed OrgaAI.init. * Used only for logging / diagnostics. */ sessionConfigEndpoint?: string; /** * Optional voice/model configuration to seed OrgaAI.init. */ voice?: OrgaAIVoice; /** * Logging verbosity override. */ logLevel?: 'disabled' | 'error' | 'warn' | 'info' | 'debug'; /** * Theme/layout preset for the widget shell. */ theme?: WidgetThemeName; /** * Controls whether the transcript panel is visible. */ transcript?: TranscriptMode; /** * Controls camera preview behavior. */ videoPreview?: VideoPreviewMode; /** * UI branding: name, tagline, and color palette. */ branding?: Partial<WidgetBranding>; };
FieldTypeRequiredDescription
targetHTMLElement | stringNoDOM element or CSS selector where the widget mounts.
fetchSessionConfig() => Promise<SessionConfigResponse>YesAsync function that returns session credentials from your backend.
sessionConfigEndpointstringNoHuman-readable endpoint label for logging.
voiceOrgaAIVoiceNoDefault voice/model for the session.
logLevel"disabled" | "error" | "warn" | "info" | "debug"NoControls internal logging verbosity.
themeWidgetThemeNameNoLayout preset for the widget shell.
transcriptTranscriptModeNoWhether to show the transcript panel.
videoPreviewVideoPreviewModeNoControls camera preview behavior.
brandingPartial<WidgetBranding>NoBranding configuration (merged with defaults).

SessionConfigResponse

Response shape expected from your backend’s fetchSessionConfig function.

export type SessionConfigResponse = { ephemeralToken: string; iceServers: Array<{ urls: string | string[]; username?: string; credential?: string; }>; };
FieldTypeRequiredDescription
ephemeralTokenstringYesShort-lived JWT token for authenticating the WebRTC session.
iceServersArray<{ urls, username?, credential? }>YesArray of STUN/TURN server configurations for WebRTC.

Theme & Layout Types

WidgetThemeName

Layout preset for the widget shell.

export type WidgetThemeName = 'floating-badge' | 'panel' | 'full';
ValueDescription
"floating-badge"Widget appears as a docked badge in the corner that expands into a panel (default).
"panel"Widget renders as a panel at the point where you place the host element.
"full"Large, full-panel experience intended for dedicated assistant pages.

TranscriptMode

Controls whether the transcript panel is visible.

export type TranscriptMode = 'hidden' | 'panel';
ValueDescription
"hidden"Hide the transcript panel entirely.
"panel"Show a live transcript panel alongside the widget (default).

VideoPreviewMode

Controls camera preview and toggle behavior.

export type VideoPreviewMode = 'hidden' | 'optional' | 'always';
ValueDescription
"hidden"Camera preview is completely hidden.
"optional"Camera preview is available but can be toggled on/off (default).
"always"Camera preview is always visible when the camera is enabled.

Branding Types

WidgetBranding

Complete branding configuration for the widget UI.

export type WidgetBranding = { brandName: string; tagline?: string; accentColor: string; backgroundColor: string; borderColor: string; textColor: string; secondaryTextColor: string; badgeIconUrl?: string; logoUrl?: string; logoAlt?: string; };
FieldTypeRequiredDefaultDescription
brandNamestringYes"Orga Assistant"Product or company name shown in the header.
taglinestringNo"Your realtime copilot"Short subtitle beneath the brand name.
accentColorstringYes"#2D9FBC"Main accent color used for buttons and badge.
backgroundColorstringYes"#ffffff"Widget body background.
borderColorstringYes"#e2e8f0"Border color for panels and transcript boxes.
textColorstringYes"#0f172a"Primary text color.
secondaryTextColorstringYes"#475569"Secondary / muted text.
badgeIconUrlstringNoOrga logo data URIURL or data:image/* URI for the floating badge icon. Non-HTTPS URLs are ignored.
logoUrlstringNoundefinedOptional logo shown in the header. Non-HTTPS URLs are ignored.
logoAltstringNobrandNameAlt text for the header logo.

WidgetFeatureConfig

Feature configuration for transcript and video preview.

export type WidgetFeatureConfig = { transcript: TranscriptMode; videoPreview: VideoPreviewMode; };
FieldTypeDescription
transcriptTranscriptModeWhether to show the transcript panel.
videoPreviewVideoPreviewModeControls camera preview behavior.

Re-exported Core Types

For convenience, the Widget SDK re-exports types from @orga-ai/core so you don’t need a second import.

TypeDescription
OrgaAIVoiceSupported voice presets (e.g., "fable", "alloy").
ConnectionStateConnection lifecycle states: "disconnected", "connecting", "connected".
OrgaAIModelSupported model names (e.g., "orga-1-beta").

Foundational types originate in @orga-ai/core; they are re-exported here so a second import is rarely necessary.


Example Usage

import type { WidgetInitOptions, WidgetThemeName, WidgetBranding, } from '@orga-ai/widget'; import { initWidget } from '@orga-ai/widget'; const options: WidgetInitOptions = { fetchSessionConfig: () => fetch('/api/orga-session').then((res) => res.json()), theme: 'floating-badge' as WidgetThemeName, branding: { brandName: 'My App', tagline: "Your app's assistant", accentColor: '#2D9FBC', backgroundColor: '#ffffff', borderColor: '#e2e8f0', textColor: '#0f172a', secondaryTextColor: '#475569', } as Partial<WidgetBranding>, }; initWidget(options);

This example shows how to use the provided types to safely configure the widget in a TypeScript app.


Default Values

When you don’t provide certain options, the widget uses these defaults:

const DEFAULT_BRANDING: WidgetBranding = { brandName: 'Orga Assistant', tagline: 'Your realtime copilot', accentColor: '#2D9FBC', backgroundColor: '#ffffff', borderColor: '#e2e8f0', textColor: '#0f172a', secondaryTextColor: '#475569', }; const DEFAULT_FEATURES: WidgetFeatureConfig = { transcript: 'panel', videoPreview: 'optional', }; const defaultTheme: WidgetThemeName = 'floating-badge'; const defaultVoice: OrgaAIVoice = 'fable'; const defaultLogLevel = 'info';

All branding fields are optional when passed via branding; they are merged with DEFAULT_BRANDING and sanitized.


Last updated on