Skip to Content
🚀 Orga AI is in open beta.
TutorialsWidget

Widget: Getting Started

This tutorial shows you how to embed the Orga AI widget into any website or app. You can choose between a simple CDN snippet for static sites or an npm package for React/TypeScript projects. Both approaches give you a fully functional voice and video assistant with minimal setup.

What you will build

  • A secure backend endpoint that returns session credentials.
  • A working Orga widget embedded in your site (via CDN or npm).
  • A customizable widget UI that matches your brand.

Prerequisites

  • Node.js 18+ and a Next.js 13+ app (App Router) for the backend example.
  • An Orga AI account plus an API key from the Orga dashboard .
  • Basic HTML knowledge for CDN usage, or React/TypeScript familiarity for npm usage.

The widget never receives your Orga API key directly. Instead, you’ll create a backend endpoint that securely exchanges your API key for short-lived session credentials.

Create a secure backend endpoint

Your API key must never live in browser code. Create an API route that fetches an ephemeral token and ICE servers using the Orga Node SDK.

Add your API key to .env:

.env
ORGA_API_KEY=sk_orga_ai_*****************************

Create the backend route:

app/api/orga-session/route.ts
import { NextResponse } from 'next/server';
import { OrgaAI } from '@orga-ai/node';
 
const orgaAI = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY!,
});
 
export async function GET() {
  try {
    const sessionConfig = await orgaAI.getSessionConfig();
    return NextResponse.json(sessionConfig);
  } catch (error) {
    console.error('OrgaAI session error', error);
    return NextResponse.json(
      { error: 'Failed to fetch session config' },
      { status: 500 },
    );
  }
}

Keep your API key on the server only. The widget will call this endpoint to get session credentials, but it never sees your API key directly.

Choose your integration method

The widget supports two integration styles: CDN for simple HTML sites and npm for React/TypeScript projects. Both use the same backend endpoint you just created.

Add the widget script

Include the CDN script in your HTML page:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My Site with Orga Widget</title>
  </head>
  <body>
    <h1>Welcome to my site</h1>
    
    <!-- Load the Orga AI widget from the CDN -->
    <script src="https://orga-cdn.vercel.app/init.global.js" async></script>
    
    <!-- Initialize the widget -->
    <script>
      OrgaWidget.initWidget({
        fetchSessionConfig: () =>
          fetch("http://localhost:3000/api/orga-session").then((res) =>
            res.json(),
          ),
      });
    </script>
    
    <!-- Mount point for the widget -->
    <div data-orga-widget></div>
  </body>
</html>

The widget will automatically mount into the <div data-orga-widget></div> element.

Replace http://localhost:3000 with your actual backend URL in production. For local development, make sure your Next.js dev server is running on port 3000.

Customize the widget appearance

Both CDN and npm integrations support the same configuration options. Here’s how to customize the widget to match your brand:

<script>
  OrgaWidget.initWidget({
    fetchSessionConfig: () =>
      fetch("http://localhost:3000/api/orga-session").then((res) =>
        res.json(),
      ),
    theme: 'floating-badge', // or 'panel' or 'full'
    transcript: 'panel', // or 'hidden'
    videoPreview: 'optional', // or 'hidden' or 'always'
    branding: {
      brandName: 'My App',
      tagline: "Your app's assistant",
      accentColor: '#2D9FBC',
      backgroundColor: '#ffffff',
      borderColor: '#e2e8f0',
      textColor: '#0f172a',
      secondaryTextColor: '#475569',
      logoUrl: '/logo.png',
    },
  });
</script>

Theme options:

  • floating-badge — Widget appears as a docked badge that expands into a panel (default)
  • panel — Widget renders as a panel at the mount point
  • full — Large, full-panel experience for dedicated assistant pages

Branding fields: All branding fields are optional and merge with safe defaults. The widget uses your colors for buttons, badges, and UI elements automatically.

Test your integration

  1. Start your backend server (if using Next.js, run pnpm dev or npm run dev).
  2. Open your page in a browser.
  3. Look for the widget — it should appear as a floating badge (if using floating-badge theme) or as a panel.
  4. Click to start a session — the widget will call your backend endpoint, establish a WebRTC connection, and you’ll see the AI assistant.

Make sure your backend is running and accessible. If the widget can’t reach /api/orga-session, you’ll see an error message in the widget UI.

Validate and iterate

  • Check the browser console for any connection errors or warnings.
  • Verify media permissions are requested when you start a session.
  • Test the widget on different pages to ensure it persists across navigation (for React/Next.js apps).
  • Customize the branding colors and theme to match your product’s design system.

Next steps

Last updated on
NodeHow-to Guides