feat: voice calls via LiveKit (ChattyVoiceCallView)

Adds a ready-to-render call screen — token fetch from the same
/api/widget/voice/token endpoint the web widget uses, LiveKit Room
connect, mic enable, live transcript (RoomEvent.TranscriptionReceived),
active-speaker-driven status (connecting/listening/agent-speaking),
mute/hangup, and per-design theming via CHATTY_DESIGN_TOKENS — same
states and structure as the web widget's voice-call-widget.tsx.

Opt-in, not wired into ChattyChatView automatically: render it
yourself from the existing onVoiceCallPress callback (see README).
livekit-client/@livekit/react-native/@livekit/react-native-webrtc are
optional peer dependencies — apps that never use voice don't pay for
them. iOS calls setupIOSAudioManagement(true) on mount, needed for the
mic/speaker routing a call requires (plain playback doesn't need it).

Verified: tsc --noEmit clean and `npm run build` succeeds against the
real installed livekit-client 2.22.1 / @livekit/react-native 2.12.0
type definitions, and the existing jest suite (33 tests) still passes.
NOT verified: an actual call on a real device/simulator — written
without any way to run React Native, LiveKit, or a device/simulator in
this environment. Build and test a real call end-to-end (mic
permission grant, actual audio, transcript rendering) before bumping
the package version or publishing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: tharindu20118

README.md

@@ -37,7 +37,9 @@ npm install @personaliai/react-native @react-native-async-storage/async-storage
 ```
 
 `react` and `react-native` are peer dependencies — install versions matching your app (`react`
-18+, `react-native` 0.72+).
+18+, `react-native` 0.72+). Voice calls (`ChattyVoiceCallView`) are the one feature that needs
+native linking — see [Voice-call button](#chattychatview) — everything else needs nothing beyond
+`@react-native-async-storage/async-storage`.
 
 ## Quick start
 
@@ -210,9 +212,39 @@ yet, it's backend work in `chatty-backend`.
 
 <br>
 
-Only shown when the bot's dashboard has voice enabled, and only fires `onVoiceCallPress` — this
-SDK doesn't bundle a voice-call implementation (a separate LiveKit integration, out of scope
-here).
+Only shown when the bot's dashboard has voice enabled, and fires `onVoiceCallPress`. This SDK now
+ships a ready-to-render call screen, `ChattyVoiceCallView` — render it yourself from that callback
+(it's opt-in, not wired in automatically, so apps that never use voice don't pay for the
+dependency):
+
+```tsx
+import { ChattyChatView, ChattyVoiceCallView, ChattyClient } from "@personaliai/react-native";
+import { registerGlobals } from "@livekit/react-native"; // once, at app startup (e.g. index.js)
+
+registerGlobals();
+
+function MyChat() {
+  const [showCall, setShowCall] = useState(false);
+  const client = useMemo(() => new ChattyClient({ botId: "YOUR_BOT_ID" }), []);
+
+  if (showCall) {
+    return (
+      <ChattyVoiceCallView
+        client={client}
+        sessionId={sessionId} // the same session id ChattyChatView/useChattyChat is using
+        widgetStyle={theme?.widget_style}
+        onClose={() => setShowCall(false)}
+      />
+    );
+  }
+  return <ChattyChatView botId="YOUR_BOT_ID" onVoiceCallPress={() => setShowCall(true)} />;
+}
+```
+
+Needs three additional peer dependencies only if you use this (`npm i @livekit/react-native
+livekit-client @livekit/react-native-webrtc` + the usual iOS `pod install` / Android autolinking) —
+apps that don't render `ChattyVoiceCallView` don't need them. See LiveKit's own React Native setup
+docs for platform permissions (`NSMicrophoneUsageDescription` on iOS, `RECORD_AUDIO` on Android).
 
 </details>
 

dist/ChattyVoiceCallView.d.ts

@@ -0,0 +1,25 @@
+import React from "react";
+import { ChattyClient } from "./api";
+export interface ChattyVoiceCallViewProps {
+    client: ChattyClient;
+    sessionId: string;
+    widgetStyle?: string | null;
+    visitorTimezone?: string;
+    onClose: () => void;
+}
+/**
+ * Full-screen (or modal) voice-call UI — present this when the chat view's
+ * phone button is tapped and `theme.voice_enabled` is true, e.g.:
+ *
+ *   {showCall && (
+ *     <ChattyVoiceCallView client={client} sessionId={sessionId}
+ *       widgetStyle={theme?.widget_style} onClose={() => setShowCall(false)} />
+ *   )}
+ *
+ * Requires (app-level, once): `import { registerGlobals } from
+ * "@livekit/react-native"; registerGlobals();` before any Room is created —
+ * typically at the top of index.js. iOS also needs an AudioSession category
+ * configured (see @livekit/react-native's AudioSession helper) for the mic
+ * to route correctly during a call.
+ */
+export declare function ChattyVoiceCallView({ client, sessionId, widgetStyle, visitorTimezone, onClose }: ChattyVoiceCallViewProps): React.JSX.Element;

dist/ChattyVoiceCallView.js

@@ -75,6 +75,20 @@ export declare class ChattyClient {
     }): Promise<string>;
     /** Poll for new messages (e.g. from a human agent) since the given ISO timestamp. */
     poll(sessionId: string, after: string): Promise<ChattyPollResponse>;
+    /**
+     * Mints a LiveKit room token + dispatches the voice agent for a call, same
+     * endpoint the web widget uses. Only meaningful when `getTheme().voice_enabled`
+     * is true. This SDK doesn't bundle the LiveKit client itself — see
+     * ChattyVoiceCallView, which needs `@livekit/react-native` + `livekit-client`
+     * as peer dependencies only apps actually using voice calls need to install.
+     */
+    getVoiceToken(sessionId: string, visitorTimezone?: string): Promise<ChattyVoiceToken>;
+}
+export interface ChattyVoiceToken {
+    token: string;
+    livekit_url: string;
+    room_name: string;
+    session_id: string;
 }
 export declare class ChattyRateLimitError extends Error {
     constructor();

dist/api.d.ts

@@ -158,6 +158,29 @@ export class ChattyClient {
             throw new Error(`poll failed: ${res.status}`);
         return res.json();
     }
+    /**
+     * Mints a LiveKit room token + dispatches the voice agent for a call, same
+     * endpoint the web widget uses. Only meaningful when `getTheme().voice_enabled`
+     * is true. This SDK doesn't bundle the LiveKit client itself — see
+     * ChattyVoiceCallView, which needs `@livekit/react-native` + `livekit-client`
+     * as peer dependencies only apps actually using voice calls need to install.
+     */
+    async getVoiceToken(sessionId, visitorTimezone = "UTC") {
+        const res = await fetch(buildUrl(this.baseUrl, "/api/widget/voice/token", {}), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ bot_id: this.botId, session_id: sessionId, visitor_timezone: visitorTimezone }),
+        });
+        if (res.status === 429)
+            throw new ChattyRateLimitError();
+        if (res.status === 403)
+            throw new ChattyDomainNotAllowedError();
+        if (!res.ok) {
+            const detail = await res.json().catch(() => ({}));
+            throw new Error(detail.detail || `getVoiceToken failed: ${res.status}`);
+        }
+        return res.json();
+    }
 }
 // The backend can't cryptographically verify a native app's identity the way
 // it verifies a browser's Referer for the web widget, so a bot with

dist/api.js

@@ -1,11 +1,13 @@
 export { ChattyClient, DEFAULT_BASE_URL, ChattyRateLimitError, ChattyDomainNotAllowedError } from "./api";
-export type { ChattyTheme, ChattyChatResponse, ChattyMediaResponse, ChattyPollMessage, ChattyPollResponse, ChattyClientOptions, } from "./api";
+export type { ChattyTheme, ChattyChatResponse, ChattyMediaResponse, ChattyPollMessage, ChattyPollResponse, ChattyClientOptions, ChattyVoiceToken, } from "./api";
 export { useChattyChat } from "./useChattyChat";
 export type { ChattyMessage, ChattyRole, UseChattyChatOptions, UseChattyChatResult } from "./useChattyChat";
 export { ChattyChatView } from "./ChattyChatView";
 export type { ChattyChatViewProps } from "./ChattyChatView";
 export { ChattyLauncher } from "./ChattyLauncher";
 export type { ChattyLauncherProps } from "./ChattyLauncher";
+export { ChattyVoiceCallView } from "./ChattyVoiceCallView";
+export type { ChattyVoiceCallViewProps } from "./ChattyVoiceCallView";
 export { getOrCreateSessionId, newSession } from "./session";
 export { CHATTY_DESIGN_TOKENS, chattyNormalizeWidgetStyle, chattyLogoBgColor, chattyLauncherRadii, chattyBubbleRadii } from "./designTokens";
 export type { ChattyDesignTokens } from "./designTokens";

dist/index.d.ts

@@ -2,5 +2,9 @@ export { ChattyClient, DEFAULT_BASE_URL, ChattyRateLimitError, ChattyDomainNotAl
 export { useChattyChat } from "./useChattyChat";
 export { ChattyChatView } from "./ChattyChatView";
 export { ChattyLauncher } from "./ChattyLauncher";
+// Voice calls (LiveKit) — only importable once the app has installed the
+// optional peer dependencies (@livekit/react-native, livekit-client,
+// @livekit/react-native-webrtc); see ChattyVoiceCallView.tsx's own comment.
+export { ChattyVoiceCallView } from "./ChattyVoiceCallView";
 export { getOrCreateSessionId, newSession } from "./session";
 export { CHATTY_DESIGN_TOKENS, chattyNormalizeWidgetStyle, chattyLogoBgColor, chattyLauncherRadii, chattyBubbleRadii } from "./designTokens";

dist/index.js

@@ -35,14 +35,25 @@
   "peerDependencies": {
     "@react-native-async-storage/async-storage": ">=1.19",
     "react": ">=18",
-    "react-native": ">=0.72"
+    "react-native": ">=0.72",
+    "livekit-client": ">=2.0.0",
+    "@livekit/react-native": ">=2.0.0",
+    "@livekit/react-native-webrtc": ">=125.0.0"
+  },
+  "peerDependenciesMeta": {
+    "livekit-client": { "optional": true },
+    "@livekit/react-native": { "optional": true },
+    "@livekit/react-native-webrtc": { "optional": true }
   },
   "devDependencies": {
     "@react-native-async-storage/async-storage": "^1.24.0",
     "@types/jest": "^30.0.0",
     "@types/react": "^18.3.31",
     "@types/react-test-renderer": "^18.3.1",
     "jest": "^30.4.2",
+    "livekit-client": "^2.22.1",
+    "@livekit/react-native": "^2.12.0",
+    "@livekit/react-native-webrtc": "^144.1.2",
     "react": "^18.2.0",
     "react-native": "^0.74.7",
     "react-test-renderer": "18.2.0",