Skip to Content
🚀 Orga AI is in open beta.
DocumentationClient SDKsReactQuick Start

Quick Start

Follow these steps to get Orga running securely in your React (Next.js) app.
You’ll create a secure backend route, initialize the SDK, and start a real‑time AI session.

This guide shows a Next.js setup for clarity, but the same concepts apply to any React project.
You simply need a backend endpoint that returns the session configuration.

Install

pnpm add @orga-ai/react

The React SDK pulls in @orga-ai/core automatically. No extra peer installs required beyond React itself.

Set Up a Secure Backend Proxy

You’ll need a backend endpoint that fetches an ephemeral token and ICE servers using your Orga API key.
Never expose your API key client‑side.

Add your secrets

.env

ORGA_API_KEY=sk_orga_ai_*****************************
USER_EMAIL=your_email_here

Get your API key from your Orga AI Dashboard .

Create the route

Install the Server SDK and create a route to fetch the session config.

app/api/orga-client-secrets/route.ts
import { OrgaAI } from '@orga-ai/node';
import express from 'express';
 
const app = express();
const orgaAI = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY,
  userEmail: process.env.ORGA_USER_EMAIL
});
 
app.get('/api/orga-session', async (req, res) => {
  try {
    const sessionConfig = await orgaAI.getSessionConfig();
    res.json(sessionConfig);
  } catch (error) {
    console.error('OrgaAI error:', error);
    res.status(500).json({ error: 'Failed to get session config' });
  }
});

Your API key should only live in this backend route — never in client code.

Initialize the SDK

Initialize Orga once near startup.
You can do this inside a provider component that wraps your app layout.

app/providers/OrgaClientProvider.tsx
'use client'
import { OrgaAI, OrgaAIProvider } from '@orga-ai/react'
 
OrgaAI.init({
  logLevel: 'debug',
  fetchSessionConfig: async () => {
    const res = await fetch('/api/orga-client-secrets');
    const { ephemeralToken, iceServers } = await res.json();
    return { ephemeralToken, iceServers };
  },
  // model and voice can be customized globally
  model: 'orga-1-beta',
  voice: 'alloy',
});
 
export function OrgaClientProvider({ children }: { children: React.ReactNode }) {
  return <OrgaAIProvider>{children}</OrgaAIProvider>;
}

Then wrap your root layout with this provider:

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

Start a Session

Now use the hook (useOrgaAI()) to initialize a real‑time session with audio/video and AI streaming.

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

When you click Start Session, the SDK:

  1. Calls your backend route to get a short‑lived token and ICE servers.
  2. Negotiates a secure WebRTC connection with Orga.
  3. Streams the AI’s audio/video response back to your component tree.

Next Steps

  • Architecture → Understand how each layer (UI → SDK → core → backend) works together.
  • API Reference → Reference for the OrgaAI class.
  • Troubleshooting → Troubleshooting guide.
Last updated on
IntroductionArchitecture