Speko Docs

React Native

Run a Speko voice conversation in a React Native or Expo app on iOS and Android with @spekoai/react-native.

@spekoai/react-native joins a Speko voice session from a phone. It captures the mic, plays the agent, and streams a reconciled transcript. The API matches @spekoai/client, plus a useVoiceConversation() hook.

import { useVoiceConversation } from '@spekoai/react-native';
import { Button } from 'react-native';

export function VoiceButton() {
  const call = useVoiceConversation();
  const start = async () => {
    const creds = await fetch('https://your-backend.example/api/voice-session', {
      method: 'POST',
    }).then((r) => r.json());
    await call.start(creds); // { transport, transportToken, transportUrl }
  };
  return call.status === 'connected' ? (
    <Button title="End" onPress={() => call.end()} />
  ) : (
    <Button title="Talk to the agent" onPress={start} />
  );
}

Install

npx expo install @spekoai/react-native @livekit/react-native @livekit/react-native-webrtc livekit-client

0.1.0 is not on npm yet. Until it is, build packages/client-react-native from the platform repo and install it from a local path.

The LiveKit packages are peer dependencies. Your app owns their versions. @livekit/react-native 3.x needs livekit-client 2.20 or newer.

Platform setup

The SDK uses native WebRTC, so it does not run in Expo Go. Use a development build (expo-dev-client) or a bare React Native app.

Expo

Add the two config plugins and the permission strings to app.json, then run npx expo prebuild:

{
  "expo": {
    "plugins": ["@livekit/react-native-expo-plugin", "@config-plugins/react-native-webrtc"],
    "ios": {
      "infoPlist": { "NSMicrophoneUsageDescription": "Talk to the voice agent." }
    },
    "android": {
      "permissions": [
        "android.permission.RECORD_AUDIO",
        "android.permission.MODIFY_AUDIO_SETTINGS",
        "android.permission.BLUETOOTH_CONNECT"
      ]
    }
  }
}

Install the plugins with npx expo install @livekit/react-native-expo-plugin @config-plugins/react-native-webrtc.

Bare React Native

On iOS, add NSMicrophoneUsageDescription to Info.plist and run pod install. On Android, add RECORD_AUDIO and MODIFY_AUDIO_SETTINGS to AndroidManifest.xml. Follow the native steps in the LiveKit React Native guide.

Microphone permission and audio session

You do not request the mic yourself. On Android, start() asks for RECORD_AUDIO at runtime. On iOS, the system prompts on first capture. A denial throws MICROPHONE_FAILED before the room is joined, so the same credentials still work for a text-only retry with micEnabled: false.

The SDK registers the LiveKit globals on first use. It also starts the native audio session for the call and stops it afterwards. iOS uses playAndRecord with voiceChat mode and prefers the speaker. Android uses communication mode with audio focus. Pass manageAudioSession: false to drive AudioSession from @livekit/react-native yourself.

Calls do not continue in the background by default. To keep one alive with the screen off, add the audio background mode on iOS (UIBackgroundModes) and a foreground service on Android.

Quickstart

Your backend mints the session. The app receives only transport, transportToken and transportUrl; the endpoint is on Mint a session on your backend.

import { useVoiceConversation } from '@spekoai/react-native';
import { Button, FlatList, Text, View } from 'react-native';

export function VoiceScreen() {
  const call = useVoiceConversation({ onError: (err) => console.warn(err) });

  const start = async () => {
    const creds = await fetch('https://your-backend.example/api/voice-session', {
      method: 'POST',
    }).then((r) => r.json());
    await call.start(creds);
  };

  return (
    <View style={{ flex: 1, padding: 16 }}>
      <Text>{call.status} · agent {call.mode}</Text>
      {call.status === 'connected' ? (
        <>
          <Button title={call.isMuted ? 'Unmute' : 'Mute'} onPress={call.toggleMute} />
          <Button title="End" onPress={call.end} />
        </>
      ) : (
        <Button title="Start" onPress={start} />
      )}
      <FlatList
        data={[...call.transcript]}
        keyExtractor={(m, i) => `${m.source}:${m.segmentId ?? i}`}
        renderItem={({ item }) => <Text>{item.source}: {item.text}</Text>}
      />
    </View>
  );
}

The hook ends the call when the component unmounts. Outside React, use VoiceConversation.create() directly:

import { VoiceConversation } from '@spekoai/react-native';

const conversation = await VoiceConversation.create({
  transport,
  transportToken,
  transportUrl,
  onTranscript: (messages) => render(messages),
});
await conversation.endSession();

Render the transcript

Render transcript from the hook, or onTranscript from create(). Both carry the full reconciled list on every update. Each entry is one speaker turn with streaming segments merged, sorted by startedAt. Key rows by source plus segmentId. An entry with isFinal: false is still being spoken.

onMessage carries raw cumulative segment updates. Use it only if you build your own reconciler.

API reference

VoiceConversation.create(options)

Resolves once the mic is published and the call is connected.

OptionTypeRequiredDefaultDescription
transportTokenstringYesShort-lived media token from your backend.
transportUrlstringYesMedia URL from your backend. Pass it unchanged.
transport'livekit' | 'daily''livekit'From the session response. 'daily' throws UNSUPPORTED_TRANSPORT.
micEnabledbooleantruefalse joins text-only: no mic, no permission prompt.
audioConstraintsAudioConstraintsall trueechoCancellation, noiseSuppression, autoGainControl.
manageAudioSessionbooleantrueConfigure, start and stop the native audio session around the call.
on* callbacksSame as @spekoai/client, minus onAudioPlaybackBlocked.

Callbacks

Same callbacks as the browser SDK: see Callbacks. onAudioPlaybackBlocked does not exist on mobile: native apps have no autoplay block.

VoiceConversation members

MemberDescription
transcriptCurrent reconciled transcript.
getId()Conversation (room) id.
isOpen()true while connected.
setMicMuted(muted)Mute or unmute the mic. No-op on a text-only call.
setVolume(volume)Agent volume, clamped to 0..1.
sendChatMessage(text)Send a typed user turn. The agent replies with voice and transcript.
canPlaybackAudiotrue while connected. Mobile has no autoplay block.
startAudioPlayback()No-op on mobile. Kept so code shared with the web SDK compiles.
endSession()Hang up and release the mic and audio session.

useVoiceConversation(callbacks?)

FieldTypeDescription
status, modeConversationStatus, ConversationModeLive call state. Starts disconnected, listening.
transcriptreadonly ConversationMessage[]Reconciled transcript.
isMutedbooleanMic mute state.
conversationIdstring | nullSet once connected.
errorError | nullLast error from start() or the call. Cleared by the next start().
start(options)Promise<void>create() options without callbacks. Rejects with the same errors.
end(), setMuted(m), toggleMute(), sendChatMessage(t)Promise<void>Call controls. end() during connecting hangs up as soon as the call connects.
conversationVoiceConversation | nullThe live instance, for setVolume and other members.

VoiceConversationController is the same state machine without React. It exposes subscribe and getSnapshot.

Errors

Failures throw SpekoClientError with a code. The codes and handling match Errors. Differences on mobile:

  • MICROPHONE_FAILED is thrown before the room is joined, so you can retry with the same credentials and micEnabled: false. A mid-call mic loss goes to onError instead.
  • UNSUPPORTED_TRANSPORT is mobile-only. The session asked for transport: 'daily'. Use an agent on the LiveKit transport.
  • SESSION_REQUEST_FAILED, INVALID_MESSAGE and DISCONNECTED do not exist. The app never calls the Speko API, and malformed data packets are ignored.

Missing transportToken or transportUrl throws a TypeError.

Limitations

v0.1 runs LiveKit sessions only. Pipecat agents return transport: 'daily', which throws UNSUPPORTED_TRANSPORT. Pipecat's React Native Daily transport needs @daily-co/react-native-webrtc, a second native WebRTC module that cannot ship next to @livekit/react-native-webrtc in one app.

RealtimeVoiceConversation (provider-direct speech-to-speech), CallListener and the embed element are not yet available on mobile. Device pickers are replaced by OS audio routing. AudioSession.selectAudioOutput from @livekit/react-native switches output.

Troubleshooting

SymptomFix
registerGlobals or WebRTCModule errors at launchYou are in Expo Go, or the native code is stale. Run npx expo prebuild and a dev build.
MICROPHONE_FAILED on iOS with no promptNSMicrophoneUsageDescription is missing, or the user denied it before. Send them to Settings.
Agent audio comes from the earpieceAnother library changed the audio session. Leave manageAudioSession on, or call AudioSession.selectAudioOutput.
CONNECTION_FAILED on the second callTokens are single-use. Mint a new session per call.
Transcript rows duplicateYou are rendering onMessage. Render transcript or onTranscript.

Next step

Run the Expo example in packages/client-react-native/example, or read Mint a session on your backend.

On this page