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

React: Getting Started

This tutorial takes you from an empty Next.js project to a working Orga session with live audio/video streaming. You will finish with a secure backend route, a configured SDK provider, and UI controls that prove the round-trip connection works.

What you will build

  • A backend route that exchanges your Orga API key for ephemeral client secrets.
  • A React provider that initializes the Orga SDK and shares connection state.
  • A simple dashboard with buttons, <OrgaVideo />, and <OrgaAudio /> to validate the session.

Prerequisites

  • Node.js 18+ and a Next.js 13+ app (App Router) with React 18.
  • An Orga AI account plus an API key from the Orga dashboard .
  • HTTPS available for local testing (Next.js dev server is fine).

The steps assume Next.js for clarity, but any React framework works as long as you can host a backend endpoint that returns the session configuration.

Install the SDK

Install the React SDK (it bundles @orga-ai/core). Pick your package manager:

pnpm add @orga-ai/react

React itself (and Next.js) are the only peer dependencies you need.

Create a secure backend proxy

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 secrets to .env.local:

ORGA_API_KEY=sk_orga_ai_*****************************

Create the route (App Router example):

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 client should request /api/orga-session and never touch the secret directly.

Initialize the client SDK

Set up a provider that runs once and shares the Orga context across your app.

app/providers/OrgaClientProvider.tsx
'use client'
 
import { OrgaAI, OrgaAIProvider } from '@orga-ai/react';
 
OrgaAI.init({
  logLevel: 'debug',
  model: 'orga-1-beta',
  voice: 'alloy',
  fetchSessionConfig: async () => {
    const res = await fetch('/api/orga-session');
    if (!res.ok) throw new Error('Failed to fetch session config');
    const { ephemeralToken, iceServers } = await res.json();
    return { ephemeralToken, iceServers };
  },
});
 
export function OrgaClientProvider({ children }: { children: React.ReactNode }) {
  return <OrgaAIProvider>{children}</OrgaAIProvider>;
}

Wrap your root layout:

app/layout.tsx
import type { ReactNode } from 'react';
import { OrgaClientProvider } from './providers/OrgaClientProvider';
 
export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <OrgaClientProvider>{children}</OrgaClientProvider>
      </body>
    </html>
  );
}

Start a session from the UI

Use the useOrgaAI() hook plus <OrgaVideo /> and <OrgaAudio /> components to prove everything works.

app/page.tsx
'use client'
 
import {
  useOrgaAI,
  OrgaVideo,
  OrgaAudio,
} from '@orga-ai/react';
 
export default function Home() {
  const {
    startSession,
    endSession,
    connectionState,
    toggleCamera,
    toggleMic,
    isCameraOn,
    isMicOn,
    userVideoStream,
    aiAudioStream,
  } = useOrgaAI();
 
  const isConnected = connectionState === 'connected';
  const isIdle = connectionState === 'disconnected';
 
  return (
    <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
      <header>
        <h1 className="text-3xl font-bold">Orga React SDK Quick Start</h1>
        <p className="text-gray-600">Status: {connectionState}</p>
      </header>
 
      <section className="grid grid-cols-2 gap-4">
        <button
          className="rounded bg-blue-600 px-4 py-2 text-white disabled:opacity-50"
          disabled={!isIdle}
          onClick={() => startSession()}
        >
          Start Session
        </button>
        <button
          className="rounded bg-red-600 px-4 py-2 text-white disabled:opacity-50"
          disabled={!isConnected}
          onClick={() => endSession()}
        >
          End Session
        </button>
        <button
          className="rounded border px-4 py-2 disabled:opacity-50"
          disabled={!isConnected}
          onClick={toggleCamera}
        >
          {isCameraOn ? 'Camera On' : 'Camera Off'}
        </button>
        <button
          className="rounded border px-4 py-2 disabled:opacity-50"
          disabled={!isConnected}
          onClick={toggleMic}
        >
          {isMicOn ? 'Mic On' : 'Mic Off'}
        </button>
      </section>
 
      <OrgaVideo stream={userVideoStream} className="h-64 w-full rounded bg-black" />
      <OrgaAudio stream={aiAudioStream} />
    </main>
  );
}

When you click Start Session, the SDK:

  1. Calls your backend /api/orga-session route to fetch an ephemeral token and ICE servers.
  2. Negotiates a secure WebRTC connection with Orga.
  3. Streams the AI participant’s audio/video back into your React component tree.

Validate and iterate

  • Watch the browser console and server logs for WebRTC negotiation events.
  • Confirm media permissions fire only after startSession().
  • When everything looks good, tailor the layout to your product’s UX.

Next steps

Last updated on
TutorialsReact Native