Skip to content

React SDK (@rymi/react) ​

Put a Rymi voice agent in a React app with one provider and one hook. RymiProvider connects the browser to a call, plays the agent's audio and publishes the microphone. useRymiAgent gives you the live transcript, the connection state and the call controls.

@rymi/react is built on @rymi/web and LiveKit Components React. It needs React 18 or later.

Install ​

bash
npm install @rymi/react

react and react-dom are peer dependencies. @rymi/web, livekit-client and @livekit/components-react install with the package.

Quick start ​

1. Create a call and get its access details ​

Create a call with a webrtc participant, from your backend with a secret key or from the browser with a publishable key. The response carries the room URL and token for that participant, under participants[].access:

bash
curl -X POST https://api.rymi.live/v1/calls \
  -H "Authorization: Bearer sb_publishable_..." \
  -H "Content-Type: application/json" \
  -d '{ "participants": [{ "transport": "webrtc", "identity": "browser" }] }'
json
{
  "participants": [
    {
      "transport": "webrtc",
      "identity": "browser",
      "access": { "url": "wss://livekit.rymi.live", "token": "eyJ..." }
    }
  ]
}

2. Wrap your call UI in RymiProvider ​

tsx
import { RymiProvider, useRymiAgent } from '@rymi/react';

function CallControls() {
  const { isConnected, isMicrophoneEnabled, toggleMic, disconnect, transcriptEntries, callError } = useRymiAgent();

  return (
    <div>
      <p>{isConnected ? 'Connected' : 'Connecting…'}</p>
      {callError && <p role="alert">{callError.message}</p>}
      <button onClick={toggleMic}>{isMicrophoneEnabled ? 'Mute' : 'Unmute'}</button>
      <button onClick={disconnect}>Hang up</button>
      <ul>
        {transcriptEntries.map((entry) => (
          <li key={entry.id}>{entry.role}: {entry.text}</li>
        ))}
      </ul>
    </div>
  );
}

export function VoiceCall({ url, token }: { url: string; token: string }) {
  return (
    <RymiProvider serverUrl={url} token={token}>
      <CallControls />
    </RymiProvider>
  );
}

useRymiAgent only works inside a RymiProvider. When serverUrl or token is empty, the provider renders its children without connecting, so you can mount your UI before the call exists.

RymiProvider ​

PropTypeDefaultDescription
serverUrlstringThe room URL from participants[].access.url
tokenstringThe participant token from participants[].access.token
connectbooleantrueConnect when the component mounts
audiobooleantrueAsk for the microphone and publish it
audioCaptureDefaultsAudioCaptureOptionsecho cancellation, noise suppression, auto gain and voice isolation onMicrophone constraints, merged over the defaults. Pass { echoCancellation: false } to opt out of echo cancellation
childrenReactNodeYour UI

The provider also plays the agent's audio. You don't render an audio element yourself.

useRymiAgent() ​

FieldTypeDescription
stateConnectionStateThe room connection state. ConnectionState is re-exported from the package
isConnectedbooleantrue once the connection is up
isMicrophoneEnabledbooleanWhether the microphone is publishing
toggleMic()() => Promise<void>Mute or unmute the microphone
disconnect()() => voidLeave the call
transcriptEntriesLiveTranscriptEntry[]The live transcript, ready to render in order
thinkingEntriesLiveThinkingEntry[]Short status lines the agent sends while it works
toolActivityLiveToolActivity | nullThe tool the agent is running now (tool, label), cleared when it finishes
callErrorLiveCallError | nullThe last call error (code, message)
clearCallError()() => voidDismiss the error
clearLiveConversation()() => voidReset the transcript, status lines, tool activity and error

If the microphone is blocked or missing, callError.code is microphone_unavailable. An error the agent reports during the call arrives with the code and message it sent, or agent_error and "The call failed." when it sends none.