feat(embed): add topInset, bottomInset, and safe-area delivery v1.2.0

Author: tharindu20118

dist/ChattyEmbedView.d.ts

@@ -3,6 +3,8 @@ export declare const chattyDefaultEmbedBaseUrl = "https://chatty.personaliai.com
 export declare const BRIDGE_SHIM_JS = "\n(function() {\n  if (window.__chattyBridgeInstalled) { return true; }\n  window.__chattyBridgeInstalled = true;\n  // MessageEvent's constructor only accepts a Window or MessagePort for\n  // 'source' (not a generic EventTarget, and definitely not a plain object\n  // literal) \u2014 a MessagePort from a throwaway MessageChannel is the only\n  // one of those we can actually construct standalone. Its native\n  // postMessage is shadowed with our own override (own-property lookup\n  // beats the prototype's), so the port itself is never really used to\n  // send anything, only to satisfy the type check and as a stable\n  // identity for the page's own 'e.source !== window.parent' filter.\n  var fakeParent = new MessageChannel().port1;\n  fakeParent.postMessage = function(data) {\n    try { window.ReactNativeWebView.postMessage(JSON.stringify(data)); } catch (e) {}\n  };\n  try {\n    Object.defineProperty(window, 'parent', { get: function() { return fakeParent; }, configurable: true });\n  } catch (e) {}\n  window.__chattyDeliver = function(json) {\n    try {\n      var data = JSON.parse(json);\n      window.dispatchEvent(new MessageEvent('message', { data: data, source: fakeParent }));\n    } catch (e) {}\n  };\n  // Suppress raw browser window.alert() calls (e.g. \"Browser push notifications\n  // are not supported on this browser\" from EmbedClient.tsx) which would otherwise\n  // render as a jarring browser dialog.\n  try {\n    window.alert = function(msg) {\n      try { console.log('[ChattyBridge] alert suppressed: ' + msg); } catch (e) {}\n    };\n  } catch (e) {}\n  // Intercept getUserMedia so native host knows mic access was requested.\n  try {\n    if (navigator.mediaDevices && navigator.mediaDevices.getUserMedia) {\n      var _origGUM = navigator.mediaDevices.getUserMedia.bind(navigator.mediaDevices);\n      navigator.mediaDevices.getUserMedia = function(constraints) {\n        try { fakeParent.postMessage({ type: 'chatty:mic-requested' }); } catch (e) {}\n        return _origGUM(constraints);\n      };\n    }\n  } catch (e) {}\n  // Intercept geolocation so native host knows location access was requested.\n  try {\n    if (navigator.geolocation && navigator.geolocation.getCurrentPosition) {\n      var _origGCP = navigator.geolocation.getCurrentPosition.bind(navigator.geolocation);\n      navigator.geolocation.getCurrentPosition = function(success, error, options) {\n        try { fakeParent.postMessage({ type: 'chatty:location-requested' }); } catch (e) {}\n        return _origGCP(success, error, options);\n      };\n    }\n  } catch (e) {}\n  true;\n})();\n";
 export interface ChattyEmbedViewProps {
     botId: string;
+    /** Opens the standalone LiveKit voice surface instead of the normal chat surface. */
+    voiceOnly?: boolean;
     /** Overrides the embed page's own host (defaults to the production site). */
     baseUrl?: string;
     /** Called once the embed page has finished loading and is interactive (chatty:ready). */
@@ -25,6 +27,10 @@ export interface ChattyEmbedViewProps {
     /** Called when the visitor taps the attach menu's "Location" option and location permission
      * is not yet granted. Follows the same "reflect, never request" contract. */
     onLocationPermissionNeeded?: () => void;
+    /** Optional override for the safe area top inset in points (e.g. status bar / notch height). */
+    topInset?: number;
+    /** Optional override for the safe area bottom inset in points (e.g. home indicator bar height). */
+    bottomInset?: number;
 }
 /**
  * Loads the bot's own web widget page (the exact code chatty.personaliai.com

dist/ChattyEmbedView.js

@@ -84,8 +84,20 @@ function OfflineView({ onRetry, bg, fg }) {
  * for zero parity drift; see ChattyChatView for the native-components version.
  */
 export function ChattyEmbedView(props) {
-    const { botId, baseUrl = chattyDefaultEmbedBaseUrl, onReady, onMessage, onClose, onRequestNotificationPermission, onMicPermissionNeeded, onLocationPermissionNeeded, } = props;
-    const embedUrl = useMemo(() => `${baseUrl.replace(/\/$/, "")}/embed/${botId}`, [baseUrl, botId]);
+    const { botId, voiceOnly = false, baseUrl = chattyDefaultEmbedBaseUrl, onReady, onMessage, onClose, onRequestNotificationPermission, onMicPermissionNeeded, onLocationPermissionNeeded, topInset, bottomInset, } = props;
+    const embedUrl = useMemo(() => {
+        const base = `${baseUrl.replace(/\/$/, "")}/embed/${botId}`;
+        const params = new URLSearchParams();
+        params.set("platform", "react-native");
+        params.set("safeArea", "true");
+        if (voiceOnly)
+            params.set("voice", "only");
+        if (typeof topInset === "number")
+            params.set("topInset", String(Math.round(topInset)));
+        if (typeof bottomInset === "number")
+            params.set("bottomInset", String(Math.round(bottomInset)));
+        return `${base}?${params.toString()}`;
+    }, [baseUrl, botId, voiceOnly, topInset, bottomInset]);
     const embedOrigin = useMemo(() => new URL(embedUrl).origin, [embedUrl]);
     const webviewRef = useRef(null);
     const [pageReady, setPageReady] = useState(false);
@@ -137,6 +149,15 @@ export function ChattyEmbedView(props) {
         if (pageReady)
             deliver({ type: "chatty-notification-status", granted: notifGranted });
     }, [pageReady, notifGranted, deliver]);
+    useEffect(() => {
+        if (pageReady && (typeof topInset === "number" || typeof bottomInset === "number")) {
+            deliver({
+                type: "chatty-safe-area",
+                top: topInset ?? 0,
+                bottom: bottomInset ?? 0,
+            });
+        }
+    }, [pageReady, topInset, bottomInset, deliver]);
     const handleWebViewMessage = useCallback((event) => {
         let msg = null;
         try {

dist/ChattyVoiceView.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+import { ChattyEmbedViewProps } from "./ChattyEmbedView";
+/** Standalone LiveKit voice-agent UI backed by the official Chatty embed. */
+export declare function ChattyVoiceView(props: Omit<ChattyEmbedViewProps, "voiceOnly">): React.JSX.Element;

dist/ChattyVoiceView.js

@@ -0,0 +1,6 @@
+import React from "react";
+import { ChattyEmbedView } from "./ChattyEmbedView";
+/** Standalone LiveKit voice-agent UI backed by the official Chatty embed. */
+export function ChattyVoiceView(props) {
+    return <ChattyEmbedView {...props} voiceOnly/>;
+}

dist/api.d.ts

@@ -45,6 +45,13 @@ export interface ChattyTheme {
      * the text (poll-sourced messages are always human — see useChattyChat). */
     show_sender_tag?: boolean;
     color_scheme?: ChattyColorScheme;
+    voice_enabled?: boolean;
+}
+export interface ChattyVoiceToken {
+    serverUrl: string;
+    participantToken: string;
+    roomName: string;
+    participantName: string;
 }
 export interface ChattyChatResponse {
     reply: string;
@@ -106,6 +113,12 @@ export declare class ChattyClient {
         name: string;
         type: string;
     }): Promise<string>;
+    /**
+     * Create a short-lived LiveKit participant token. API keys and provider
+     * credentials never leave Chatty's backend. Connect the returned values with
+     * the official `@livekit/react-native` client in the host application.
+     */
+    createVoiceToken(sessionId: string, participantName?: string, visitorTimezone?: string): Promise<ChattyVoiceToken>;
     /** Poll for new messages (e.g. from a human agent) since the given ISO timestamp. */
     poll(sessionId: string, after: string): Promise<ChattyPollResponse>;
 }

dist/api.js

@@ -146,6 +146,30 @@ export class ChattyClient {
         const data = await res.json();
         return data.text ?? "";
     }
+    /**
+     * Create a short-lived LiveKit participant token. API keys and provider
+     * credentials never leave Chatty's backend. Connect the returned values with
+     * the official `@livekit/react-native` client in the host application.
+     */
+    async createVoiceToken(sessionId, participantName = "Visitor", visitorTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone) {
+        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,
+                participant_name: participantName,
+                visitor_timezone: visitorTimezone,
+            }),
+        });
+        if (res.status === 429)
+            throw new ChattyRateLimitError();
+        if (res.status === 403)
+            throw new ChattyDomainNotAllowedError();
+        if (!res.ok)
+            throw new Error(`createVoiceToken failed: ${res.status}`);
+        return res.json();
+    }
     /** Poll for new messages (e.g. from a human agent) since the given ISO timestamp. */
     async poll(sessionId, after) {
         const url = buildUrl(this.baseUrl, "/api/widget/poll", {

dist/index.d.ts

@@ -1,5 +1,5 @@
 export { ChattyClient, DEFAULT_BASE_URL, ChattyRateLimitError, ChattyDomainNotAllowedError } from "./api";
-export type { ChattyTheme, ChattyColorScheme, ChattyChatResponse, ChattyMediaResponse, ChattyPollMessage, ChattyPollResponse, ChattyClientOptions, } from "./api";
+export type { ChattyTheme, ChattyColorScheme, ChattyChatResponse, ChattyMediaResponse, ChattyPollMessage, ChattyPollResponse, ChattyClientOptions, ChattyVoiceToken, } from "./api";
 export { useChattyChat } from "./useChattyChat";
 export type { ChattyMessage, ChattyRole, UseChattyChatOptions, UseChattyChatResult } from "./useChattyChat";
 export { ChattyChatView } from "./ChattyChatView";
@@ -8,6 +8,7 @@ export { ChattyLauncher } from "./ChattyLauncher";
 export type { ChattyLauncherProps } from "./ChattyLauncher";
 export { ChattyEmbedView, chattyDefaultEmbedBaseUrl } from "./ChattyEmbedView";
 export type { ChattyEmbedViewProps } from "./ChattyEmbedView";
+export { ChattyVoiceView } from "./ChattyVoiceView";
 export { getOrCreateSessionId, newSession } from "./session";
 export { CHATTY_DESIGN_TOKENS, chattyNormalizeWidgetStyle, chattyLogoBgColor, chattyLauncherRadii, chattyBubbleRadii } from "./designTokens";
 export type { ChattyDesignTokens } from "./designTokens";

dist/index.js

@@ -6,6 +6,7 @@ export { ChattyLauncher } from "./ChattyLauncher";
 // guaranteeing exact parity with it. See ChattyChatView above for the
 // native-components alternative (more native feel, manually kept in parity).
 export { ChattyEmbedView, chattyDefaultEmbedBaseUrl } from "./ChattyEmbedView";
+export { ChattyVoiceView } from "./ChattyVoiceView";
 export { getOrCreateSessionId, newSession } from "./session";
 export { CHATTY_DESIGN_TOKENS, chattyNormalizeWidgetStyle, chattyLogoBgColor, chattyLauncherRadii, chattyBubbleRadii } from "./designTokens";
 export { ChattyMarkdown, extractMath, formatLatexForDisplay, parseInlineTokens } from "./ChattyMarkdown";

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@personaliai/react-native",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Official React Native SDK for Chatty AI chatbots — loads the web widget in a WebView for guaranteed parity, with native components as an alternative",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/ChattyEmbedView.tsx

@@ -129,6 +129,10 @@ export interface ChattyEmbedViewProps {
   /** Called when the visitor taps the attach menu's "Location" option and location permission
    * is not yet granted. Follows the same "reflect, never request" contract. */
   onLocationPermissionNeeded?: () => void;
+  /** Optional override for the safe area top inset in points (e.g. status bar / notch height). */
+  topInset?: number;
+  /** Optional override for the safe area bottom inset in points (e.g. home indicator bar height). */
+  bottomInset?: number;
 }
 
 function OfflineView({ onRetry, bg, fg }: { onRetry: () => void; bg: string; fg: string }) {
@@ -161,11 +165,19 @@ export function ChattyEmbedView(props: ChattyEmbedViewProps) {
     onRequestNotificationPermission,
     onMicPermissionNeeded,
     onLocationPermissionNeeded,
+    topInset,
+    bottomInset,
   } = props;
   const embedUrl = useMemo(() => {
-    const url = `${baseUrl.replace(/\/$/, "")}/embed/${botId}`;
-    return voiceOnly ? `${url}?voice=only` : url;
-  }, [baseUrl, botId, voiceOnly]);
+    const base = `${baseUrl.replace(/\/$/, "")}/embed/${botId}`;
+    const params = new URLSearchParams();
+    params.set("platform", "react-native");
+    params.set("safeArea", "true");
+    if (voiceOnly) params.set("voice", "only");
+    if (typeof topInset === "number") params.set("topInset", String(Math.round(topInset)));
+    if (typeof bottomInset === "number") params.set("bottomInset", String(Math.round(bottomInset)));
+    return `${base}?${params.toString()}`;
+  }, [baseUrl, botId, voiceOnly, topInset, bottomInset]);
   const embedOrigin = useMemo(() => new URL(embedUrl).origin, [embedUrl]);
 
   const webviewRef = useRef<WebView>(null);
@@ -222,6 +234,16 @@ export function ChattyEmbedView(props: ChattyEmbedViewProps) {
     if (pageReady) deliver({ type: "chatty-notification-status", granted: notifGranted });
   }, [pageReady, notifGranted, deliver]);
 
+  useEffect(() => {
+    if (pageReady && (typeof topInset === "number" || typeof bottomInset === "number")) {
+      deliver({
+        type: "chatty-safe-area",
+        top: topInset ?? 0,
+        bottom: bottomInset ?? 0,
+      });
+    }
+  }, [pageReady, topInset, bottomInset, deliver]);
+
   const handleWebViewMessage = useCallback(
     (event: WebViewMessageEvent) => {
       let msg: OutboundBridgeMessage | null = null;