@realtalk-ai/react-native

React Native hooks for Real Talk voice and text conversations. Built on @realtalk-ai/core.

Quick start

npm install @realtalk-ai/react-native @realtalk-ai/core

import { RealTalkProvider, useConversation } from "@realtalk-ai/react-native";

const App = () => {
  return (
    <RealTalkProvider tokenUrl="https://your-server.com/api/token">
      <Chat />
    </RealTalkProvider>
  );
};

const Chat = () => {
  const {
    connectionStatus,
    status,
    messages,
    startConversation,
    endConversation,
  } = useConversation();

  return (
    <View>
      {messages.map((msg) => (
        <Text key={msg.id}>{msg.text}</Text>
      ))}

      {status === "not_started" || status === "finished" ? (
        <Button
          title="Start"
          onPress={() => startConversation({ agentId: "your-agent-id" })}
        />
      ) : (
        <Button title="End" onPress={endConversation} />
      )}
    </View>
  );
};

See the example Expo app for a complete working project.

Setup

Expo

Add the config plugin to your app.json:

{
  "plugins": ["@realtalk-ai/react-native/app.plugin.cjs"]
}

Bare React Native

The native module auto-links. On iOS, run pod install after installing:

cd ios && pod install

Platform permissions

iOS — add to Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for voice conversations.</string>

Android — add to AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

The SDK requests this permission at runtime before starting recording.

Token endpoint

The SDK needs a server-side endpoint that you host that creates a session via the Real Talk API and returns a short-lived session token.

@app.get("/api/token")
async def get_token():
    response = await httpx.AsyncClient().post(
        "https://api.realtalk.ml/api/v1/sessions/",
        headers={"X-Realtalk-Api-Key": REALTALK_API_KEY},
        json={"agent_id": REALTALK_AGENT_ID},
    )
    data = response.json()
    return {"token": data["token"], "conversation_id": data["conversation_id"]}

See the example server for a complete implementation.

Provider

Wrap your app with RealTalkProvider and pass your token endpoint:

<RealTalkProvider tokenUrl="https://your-server.com/api/token">
  {children}
</RealTalkProvider>

You can also pass a getToken callback or a custom baseUrl — see the provider source for all options.

useConversation

The main hook — combines connection, messages, and audio controls.

State

| Field | Type | Description | | ------------------ | --------------------------- | ----------------------------------------------------------------------- | | connectionStatus | ConnectionStatus | "disconnected" | "connecting" | "connected" | "reconnecting" | | status | ConversationStatus | "not_started" | "active" | "finished" | | conversationId | string \| null | Current conversation ID | | messages | Message[] | Conversation messages | | error | ConversationError \| null | Current errors | | agentState | AgentState | "idle" | "thinking" | "speaking" | | userState | UserState | "idle" | "speaking" | | volume | number | Audio playback volume (0–1) | | isMicMuted | boolean | Microphone mute state | | isAudioMuted | boolean | Audio output mute state |

Methods

| Method | Description | | ---------------------------- | --------------------------------------- | | startConversation(options) | Start a conversation session | | endConversation() | Send hangup and end the current session | | sendMessage(text) | Send a text message | | sendDTMF(digit) | Send a DTMF tone | | sendEvent(payload) | Send a custom event | | toggleMic() | Toggle microphone mute | | toggleAudio() | Toggle audio output mute | | setVolume(volume) | Set playback volume |

Session options

startConversation({
  agentId: "your-agent-id",
  mode: "voice", // "voice" | "text"
});

Callbacks

useConversation({
  onMessage: (message) => {},
  onError: (error) => {},
  onStatusChange: (status) => {},
  onConnectionStatusChange: (connectionStatus) => {},
  onEvent: (event) => {},
});

The onEvent callback receives server events like message_created, message_updated, vad, and others. Use sendEvent to send custom events to the server. See the core package events reference for the full list of event types and their payloads.

Lower-level hooks

| Hook | Description | | ------------------- | -------------------------------------------------------- | | useConnection | WebSocket transport, session lifecycle, and reconnection | | useMessages | Message array and user/agent state tracking | | useAudioControls | Microphone mute and volume control | | useRealTalkConfig | Access provider configuration from context |

Audio

Audio capture and playback use the RealTalkAudio native module. The AudioRecorder and AudioPlayer classes are exported if you need direct access, but useConversation manages them automatically.

Development

pnpm test         # run tests

License

MIT