Skip to Content
🚀 Orga AI is in open beta.
ReferenceClient SDKsWidget SDK

Widget SDK Reference

This is the definitive source for everything exposed by @orga-ai/widget—the initWidget() function and all configuration options. Use it when you need parameter names, type signatures, or integration details; tutorials and walkthroughs live elsewhere.

Sections

  • Types — WidgetInitOptions, WidgetThemeName, WidgetBranding, and all widget-specific TypeScript interfaces and enums.

💡 Tip:
The widget SDK is built on top of @orga-ai/react and provides a simpler, configuration-based API. It handles provider setup, component mounting, and UI rendering automatically.

Structure

Each reference page includes:

  1. Concise descriptions of the API surface.
  2. Code examples using TypeScript / JavaScript.
  3. Detailed tables describing parameters, options, and return values.
  4. Implementation notes around initialization, lifecycle, and customization.

initWidget()

The main entry point for initializing the Orga widget. Works identically whether you use the CDN global (OrgaWidget.initWidget) or the npm import (import { initWidget } from '@orga-ai/widget').

function initWidget(options: WidgetInitOptions): void;

Parameters

ParameterTypeRequiredDescription
optionsWidgetInitOptionsYesConfiguration object that controls widget behavior, appearance, and session setup.

Returns

void — The function mounts the widget into the DOM and does not return a value.

WidgetInitOptions

Complete configuration object passed to initWidget().

import type { WidgetInitOptions } from '@orga-ai/widget';
 
const options: WidgetInitOptions = {
  fetchSessionConfig: () => fetch('/api/orga-session').then((res) => res.json()),
  theme: 'floating-badge',
  branding: {
    brandName: 'My App',
    accentColor: '#2D9FBC',
  },
};
 
initWidget(options);

Options Table

OptionTypeRequiredDefaultDescription
targetHTMLElement | stringNoFirst [data-orga-widget] elementDOM element or CSS selector where the widget shell is mounted.
fetchSessionConfig() => Promise<SessionConfigResponse>Yes–Async function that calls your backend and returns { ephemeralToken, iceServers }.
sessionConfigEndpointstringNoundefinedHuman-readable endpoint label for logging and error messages.
voiceOrgaAIVoiceNo"fable"Default voice/model to use for the session.
logLevel"disabled" | "error" | "warn" | "info" | "debug"No"info"Controls internal logging verbosity.
themeWidgetThemeNameNo"floating-badge"Layout preset for the widget shell.
transcriptTranscriptModeNo"panel"Whether to show the transcript panel.
videoPreviewVideoPreviewModeNo"optional"Controls camera preview and toggle behavior.
brandingPartial<WidgetBranding>NoSee defaults belowBranding configuration (merged with safe defaults).

Usage Examples

CDN Usage

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My Site</title>
  </head>
  <body>
    <script src="https://orga-cdn.vercel.app/init.global.js" async></script>
    <script>
      OrgaWidget.initWidget({
        fetchSessionConfig: () =>
          fetch('https://your-backend.com/api/orga-session').then((res) =>
            res.json(),
          ),
        theme: 'floating-badge',
        branding: {
          brandName: 'My App',
          accentColor: '#2D9FBC',
        },
      });
    </script>
    <div data-orga-widget></div>
  </body>
</html>

npm / React Usage

app/components/OrgaWidgetClient.tsx
'use client';
 
import { useEffect } from 'react';
import { initWidget } from '@orga-ai/widget';
 
export const OrgaWidgetClient = () => {
  useEffect(() => {
    initWidget({
      fetchSessionConfig: () =>
        fetch('/api/orga-session').then((res) => res.json()),
      theme: 'floating-badge',
      transcript: 'panel',
      videoPreview: 'optional',
      branding: {
        brandName: 'My App',
        tagline: "Your app's assistant",
        accentColor: '#2D9FBC',
        backgroundColor: '#ffffff',
        textColor: '#0f172a',
      },
    });
  }, []);
 
  return <div data-orga-widget />;
};

Configuration Details

fetchSessionConfig

Required function that must return a Promise resolving to a SessionConfigResponse:

type SessionConfigResponse = {
  ephemeralToken: string;
  iceServers: Array<{
    urls: string | string[];
    username?: string;
    credential?: string;
  }>;
};

The widget calls this function when a session is started. Your backend should:

  1. Hold your Orga API key securely (environment variable or secret store).
  2. Call Orga to create a session using @orga-ai/node or direct API calls.
  3. Return { ephemeralToken, iceServers } JSON to the frontend.

Never expose your Orga API key in browser code. The widget never receives your API key directly—it only calls your backend endpoint to get short-lived session credentials.

Theme Options

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.

Transcript Mode

ValueDescription
"panel"Show a live transcript panel alongside the widget (default).
"hidden"Hide the transcript panel entirely.

Video Preview Mode

ValueDescription
"optional"Camera preview is available but can be toggled on/off (default).
"hidden"Camera preview is completely hidden.
"always"Camera preview is always visible when the camera is enabled.

Branding Defaults

If you don’t provide branding, 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',
};

All branding fields are optional and merge with these defaults. See the Types reference for the complete WidgetBranding interface.

Runtime Requirements

RequirementDescription
Browser supportUses WebRTC (RTCPeerConnection, MediaStream) and the Permissions API. Requires HTTPS (or localhost) for media access.
Backend integrationA backend service (Server SDK or REST proxy) must issue ephemeral tokens for every session.
CDN usageFor CDN usage, the script must load before calling OrgaWidget.initWidget(). Use the async attribute and wait for script load.
npm usageFor npm usage, requires React 18+ and the peer dependencies: @orga-ai/react and @orga-ai/core.

Error Handling

The widget wraps your fetchSessionConfig with safety helpers that:

  • Enforce secure contexts (HTTPS or localhost) for media access.
  • Apply a timeout and small retry policy.
  • Validate that the session config payload contains the required fields.

In case of issues, the user sees clear UI feedback instead of a permanently spinning widget, and the console includes descriptive messages to help you debug misconfigured backends.

Versioning

All Orga SDKs follow semantic versioning (SemVer).
Breaking API changes correspond to major version bumps (e.g., 1.x → 2.x).

The Widget SDK’s current stable version is v1.0.0 (open beta).

Next Steps

Last updated on
TypesTypes