Skip to Content
🚀 Orga AI is in open beta.
ReferenceClient SDKsReact SDKHooks

Hooks

The React SDK currently exports one primary hook, useOrgaAI(), which exposes methods and state for creating, managing, and interacting with Orga sessions.

useOrgaAI()

Access Orga SDK methods and session state directly in your components.

import { useOrgaAI } from "@orga-ai/react";
 
const {
  startSession,
  endSession,
  enableMic,
  disableMic,
  toggleMic,
  enableCamera,
  disableCamera,
  toggleCamera,
  connectionState,
  aiAudioStream,
  userVideoStream,
  conversationItems,
  isCameraOn,
  isMicOn,
  conversationId,
  model,
  voice,
  temperature,
  instructions,
  modalities,
  updateParams,
} = useOrgaAI();

useOrgaAI() must be used within an <OrgaAIProvider>.

Returns

NameTypeDescription
startSession(config?: SessionConfig) => Promise<void>Starts a new real-time session with optional configuration. Use this to begin an AI interaction.
endSession() => Promise<void>Gracefully closes the active session and releases all streams.
enableMic() => Promise<void>Enables the user’s microphone for input.
disableMic() => Promise<void>Disables the microphone, muting input audio.
toggleMic() => Promise<void>Toggles the microphone’s enabled state.
enableCamera() => Promise<void>Enables the user’s camera for video input.
disableCamera() => Promise<void>Disables the camera, stopping video input.
toggleCamera() => Promise<void>Toggles the camera’s enabled state.
connectionStateConnectionStateCurrent connection state — "disconnected", "connecting", or "connected".
aiAudioStreamMediaStream | nullAI audio output stream. Feed into <OrgaAudio>.
userVideoStreamMediaStream | nullLocal video stream. Feed into <OrgaVideo>.
conversationItemsConversationItem[]All conversation messages exchanged within the current session, including transcriptions and responses.
isCameraOnbooleanWhether the camera is currently active.
isMicOnbooleanWhether the microphone is currently active.
conversationIdstring | nullUnique ID of the current conversation.
modelOrgaAIModel | nullCurrent AI model (e.g. "orga-1-beta").
voiceOrgaAIVoice | nullCurrent AI voice.
temperaturenumber | nullCurrent temperature value for model sampling.
instructionsstring | nullCustom instructions or persona text set for the current session.
modalitiesModality[]Enabled modalities for the session (e.g., audio, video).
updateParams(params: { model?: OrgaAIModel; voice?: OrgaAIVoice; temperature?: number; instructions?: string; modalities?: Modality[] }) => voidUpdates session parameters dynamically during a live session.

Example Usage

app/page.tsx
'use client'
import { useOrgaAI, OrgaVideo, OrgaAudio } from "@orga-ai/react";
 
export default function Home() {
  const {
    startSession,
    endSession,
    toggleMic,
    toggleCamera,
    connectionState,
    userVideoStream,
    aiAudioStream,
    isMicOn,
    isCameraOn,
    updateParams,
  } = useOrgaAI();
 
  const handleStart = async () => {
    await startSession({
      onSessionConnected: () => console.log("Connected!"),
    });
    updateParams({ model: "orga-1-beta", voice: "alloy" });
  };
 
  return (
    <div className="p-6">
      <p>Connection: {connectionState}</p>
      <p>Mic: {isMicOn ? "On" : "Off"}</p>
 
      <div className="mt-4 space-x-2">
        <button onClick={toggleMic}>Toggle Mic</button>
        <button onClick={toggleCamera}>Toggle Camera</button>
        <button onClick={handleStart}>Start Session</button>
        <button onClick={endSession}>End Session</button>
      </div>
 
      <OrgaVideo stream={userVideoStream} className="w-full h-64 rounded bg-black mt-4" />
      <OrgaAudio stream={aiAudioStream} />
    </div>
  );
}

The example demonstrates the canonical interaction loop: request a session, toggle devices, update parameters, and bind the resulting media streams to the packaged components.

Notes

  • Hooks consume context from <OrgaAIProvider>; render the provider once near your root layout.
  • Session configuration values (model, voice, temperature, instructions) are global to the provider instance.
  • Enable verbose diagnostics during development by setting logLevel: 'debug' in OrgaAI.init().
Last updated on
ComponentsTypes