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-client0.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.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
transportToken | string | Yes | Short-lived media token from your backend. | |
transportUrl | string | Yes | Media URL from your backend. Pass it unchanged. | |
transport | 'livekit' | 'daily' | 'livekit' | From the session response. 'daily' throws UNSUPPORTED_TRANSPORT. | |
micEnabled | boolean | true | false joins text-only: no mic, no permission prompt. | |
audioConstraints | AudioConstraints | all true | echoCancellation, noiseSuppression, autoGainControl. | |
manageAudioSession | boolean | true | Configure, start and stop the native audio session around the call. | |
on* callbacks | Same 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
| Member | Description |
|---|---|
transcript | Current 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. |
canPlaybackAudio | true 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?)
| Field | Type | Description |
|---|---|---|
status, mode | ConversationStatus, ConversationMode | Live call state. Starts disconnected, listening. |
transcript | readonly ConversationMessage[] | Reconciled transcript. |
isMuted | boolean | Mic mute state. |
conversationId | string | null | Set once connected. |
error | Error | null | Last 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. |
conversation | VoiceConversation | null | The 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_FAILEDis thrown before the room is joined, so you can retry with the same credentials andmicEnabled: false. A mid-call mic loss goes toonErrorinstead.UNSUPPORTED_TRANSPORTis mobile-only. The session asked fortransport: 'daily'. Use an agent on the LiveKit transport.SESSION_REQUEST_FAILED,INVALID_MESSAGEandDISCONNECTEDdo 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
| Symptom | Fix |
|---|---|
registerGlobals or WebRTCModule errors at launch | You are in Expo Go, or the native code is stale. Run npx expo prebuild and a dev build. |
MICROPHONE_FAILED on iOS with no prompt | NSMicrophoneUsageDescription is missing, or the user denied it before. Send them to Settings. |
| Agent audio comes from the earpiece | Another library changed the audio session. Leave manageAudioSession on, or call AudioSession.selectAudioOutput. |
CONNECTION_FAILED on the second call | Tokens are single-use. Mint a new session per call. |
| Transcript rows duplicate | You 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.