@facepe/widget-mobile-app 1.3.1 → 1.5.0

package/README.md

@@ -246,7 +246,8 @@ const styles = StyleSheet.create({
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `avatarKey` | `string` | *(optional)* | Specific avatar key or ID assigned to your company. |
+| `agentId` | `string` | first agent assigned to the user | The agent to talk to — its id from the FacePe dashboard (SDK page) or `GET /agents`. |
+| `avatarKey` | `string` | *(deprecated)* | The same as `agentId`, for apps written before agents. |
 | `language` | `string` | `'en'` | Spoken language code (`'en'`, `'hi'`, `'es'`, `'ta'`, `'te'`, etc.). |
 | `style` | `ViewStyle` | `undefined` | Style applied to avatar container. |
 | `videoStyle` | `ViewStyle` | `undefined` | Style applied to native video view. |
@@ -312,7 +313,7 @@ when the component unmounts.
 ```json
 {
   "conversationId": "cm_usage_123",
-  "avatar": { "id": "cm_avatar_456", "name": "Dharun" },
+  "agent": { "id": "cm_agent_456", "name": "Front Desk" },
   "language": "en",
   "platform": "android",
   "sdkVersion": "1.3.0",
@@ -330,7 +331,7 @@ when the component unmounts.
 | Field | Meaning |
 |---|---|
 | `conversationId` | The conversation's FacePe id (its usage record) |
-| `avatar` | `{ id, name }` of the avatar |
+| `agent` | `{ id, name }` of the agent that held the conversation (`avatar` is the same, kept for older apps) |
 | `language` | The language requested for the conversation |
 | `platform` | `web`, `android` or `ios` |
 | `sdkVersion` | The SDK version that recorded it |
@@ -338,6 +339,27 @@ when the component unmounts.
 | `durationSec` | Length in seconds |
 | `endReason` | `ended` (the user or your code ended it), `disconnected` (the stream dropped), `unmounted` (the component went away) |
 | `transcript` | Every line in order: `{ role: "user" \| "assistant", text, at }` |
+| `form` | For a form avatar: `{ title, complete, fields: [{ label, question, required, value }], documents, uploadWhere }` — `documents` are what the avatar asked the customer to upload at the end; `null` for other avatars |
+
+For an avatar that **fills a form**, the record also carries the form as the
+conversation filled it: each question with the customer's answer (`value` is
+`null` for a question that was not answered). FacePe reads the answers from the
+conversation when it ends, so the record arrives a few seconds after the call.
+For other avatars `form` is `null`.
+
+```json
+"form": {
+  "title": "Customer Intake Form",
+  "complete": true,
+  "fields": [
+    { "label": "Name",  "question": "Could you please tell me your full name?", "required": true, "value": "Tony" },
+    { "label": "Phone", "question": "What is the best phone number to reach you?", "required": true, "value": "9659390715" },
+    { "label": "Email", "question": "May I have your email address?", "required": false, "value": "tony@gmail.com" }
+  ],
+  "documents": ["ID proof (Aadhaar / PAN)", "Address proof"],
+  "uploadWhere": "on our website"
+}
+```
 
 ---
 

package/dist/FacePeMobileAvatar.js

@@ -58,8 +58,26 @@ function ensureLiveKitGlobals(LiveKitRN) {
         console.warn('[FacePeMobileAvatar] registerGlobals warning:', err);
     }
 }
-export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', style, videoStyle, objectFit = 'cover', mirror = false, autoStart = true, enableMic = true, onTranscript, onSpeakStart, onSpeakEnd, onUserSpeakStart, onUserSpeakEnd, onOrderUpdate, onCheckout, onStatusChange, onError, onConversationEnd, posterUrl, }, ref) => {
+/**
+ * Speech recognition writes a spoken phone number in parts ("9659-3907-1526").
+ * Long numbers are shown as plain digits; short ones ("2-3") are left as said.
+ */
+const joinNumberParts = (text) => text.replace(/\d+(?:[ \t]*[-\u2010\u2011\u2013][ \t]*\d+)+/g, (m) => {
+    const digits = m.replace(/\D/g, '');
+    return digits.length >= 7 ? digits : m;
+});
+/**
+ * Calls the gateway's agent route; a FacePe server from before agents has
+ * only the avatar route (404), so that one is tried next.
+ */
+async function gatewayFetch(base, agentPath, avatarPath, init) {
+    const res = await fetch(`${base}${agentPath}`, init);
+    return res.status === 404 ? fetch(`${base}${avatarPath}`, init) : res;
+}
+export const FacePeMobileAvatar = forwardRef(({ agentId, avatarKey, language = 'en', style, videoStyle, objectFit = 'cover', mirror = false, autoStart = true, enableMic = true, onTranscript, onSpeakStart, onSpeakEnd, onUserSpeakStart, onUserSpeakEnd, onOrderUpdate, onCheckout, onStatusChange, onError, onConversationEnd, posterUrl, }, ref) => {
     const { token, loading: tokenLoading, error: tokenError, apiBaseUrl, refreshToken } = useFacePeMobileContext();
+    // The agent to talk to (`avatarKey` is its name from before agents).
+    const chosenAgent = agentId ?? avatarKey;
     // The avatar's portrait, shown until its video arrives. Looked up from the
     // avatars this token may use, unless the app gave one (or null for none).
     const [autoPoster, setAutoPoster] = useState(null);
@@ -69,13 +87,14 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
         let cancelled = false;
         void (async () => {
             try {
-                const res = await fetch(`${apiBaseUrl.replace(/\/+$/, '')}/avatars`, {
+                const res = await gatewayFetch(apiBaseUrl.replace(/\/+$/, ''), '/agents', '/avatars', {
                     headers: { Authorization: `Bearer ${token}` },
                 });
                 if (!res.ok)
                     return;
-                const avatars = (await res.json())?.data?.avatars ?? [];
-                const avatar = avatarKey ? avatars.find((a) => a.id === avatarKey) : avatars[0];
+                const data = (await res.json())?.data;
+                const agents = data?.agents ?? data?.avatars ?? [];
+                const avatar = chosenAgent ? agents.find((a) => a.id === chosenAgent) : agents[0];
                 if (!cancelled)
                     setAutoPoster(avatar?.previewUrl ?? null);
             }
@@ -86,7 +105,7 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
         return () => {
             cancelled = true;
         };
-    }, [token, apiBaseUrl, avatarKey, posterUrl]);
+    }, [token, apiBaseUrl, chosenAgent, posterUrl]);
     const poster = posterUrl !== undefined ? posterUrl : autoPoster;
     const [status, setStatus] = useState('idle');
     const [videoTrack, setVideoTrack] = useState(null);
@@ -109,7 +128,8 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
     const onTranscriptRef = useRef(onTranscript);
     onTranscriptRef.current = onTranscript;
     // A transcript line: recorded for the conversation record, and passed on.
-    const emitLine = (role, text, id) => {
+    const emitLine = (role, said, id) => {
+        const text = joinNumberParts(said);
         const conv = conversationRef.current;
         if (conv && text) {
             const same = id ? conv.lines.find((l) => l.id === id) : undefined;
@@ -120,30 +140,53 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
         }
         onTranscriptRef.current?.({ payload: { role, text, isFinal: true } });
     };
-    // Hands the whole conversation to the app, once.
+    // Hands the whole conversation to the app, once. For a form avatar it first
+    // asks FacePe for the form as the conversation filled it (a few seconds).
     const finishConversation = (endReason) => {
         const conv = conversationRef.current;
         conversationRef.current = null;
         if (!conv)
             return;
         const endedAt = new Date();
-        try {
-            onConversationEndRef.current?.({
-                conversationId: conv.conversationId,
-                avatar: conv.avatar,
-                language: conv.language,
-                platform: Platform.OS === 'ios' ? 'ios' : Platform.OS === 'android' ? 'android' : 'web',
-                sdkVersion: SDK_VERSION,
-                startedAt: conv.startedAt.toISOString(),
-                endedAt: endedAt.toISOString(),
-                durationSec: Math.max(0, Math.round((endedAt.getTime() - conv.startedAt.getTime()) / 1000)),
-                endReason,
-                transcript: conv.lines.map(({ role, text, at }) => ({ role, text, at })),
-            });
-        }
-        catch (err) {
-            console.warn('[FacePeMobileAvatar] onConversationEnd error:', err);
-        }
+        const transcript = conv.lines.map(({ role, text, at }) => ({ role, text, at }));
+        void (async () => {
+            let form = null;
+            const token = tokenRef.current;
+            if (conv.conversationId && transcript.length > 0 && token) {
+                try {
+                    const id = encodeURIComponent(conv.conversationId);
+                    const res = await gatewayFetch(apiBaseUrl.replace(/\/+$/, ''), `/agent-sessions/${id}/form`, `/avatar-sessions/${id}/form`, {
+                        method: 'POST',
+                        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ transcript: transcript.map(({ role, text }) => ({ role, text })) }),
+                    });
+                    if (res.ok)
+                        form = (await res.json())?.data?.form ?? null;
+                }
+                catch {
+                    /* offline: the record goes without the form */
+                }
+            }
+            try {
+                onConversationEndRef.current?.({
+                    conversationId: conv.conversationId,
+                    agent: conv.agent,
+                    avatar: conv.agent,
+                    language: conv.language,
+                    platform: Platform.OS === 'ios' ? 'ios' : Platform.OS === 'android' ? 'android' : 'web',
+                    sdkVersion: SDK_VERSION,
+                    startedAt: conv.startedAt.toISOString(),
+                    endedAt: endedAt.toISOString(),
+                    durationSec: Math.max(0, Math.round((endedAt.getTime() - conv.startedAt.getTime()) / 1000)),
+                    endReason,
+                    transcript,
+                    form,
+                });
+            }
+            catch (err) {
+                console.warn('[FacePeMobileAvatar] onConversationEnd error:', err);
+            }
+        })();
     };
     const mountedRef = useRef(true);
     const isConnectingRef = useRef(false);
@@ -189,7 +232,7 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             return;
         try {
             const cleanBase = apiBaseUrl.replace(/\/+$/, '');
-            await fetch(`${cleanBase}/avatar-sessions/${uId}/end`, {
+            await gatewayFetch(cleanBase, `/agent-sessions/${uId}/end`, `/avatar-sessions/${uId}/end`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
@@ -226,29 +269,30 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
                 throw new Error('Authentication token not available. Please verify your token provider.');
             }
             const cleanBase = apiBaseUrl.replace(/\/+$/, '');
-            // Resolve target avatar ID
-            let targetAvatarId = avatarKey;
-            if (!targetAvatarId) {
-                // No avatar given: use the first one assigned to this token's user.
-                const listRes = await fetch(`${cleanBase}/avatars`, {
+            // The agent to talk to
+            let targetAgentId = chosenAgent;
+            if (!targetAgentId) {
+                // No agent given: use the first one assigned to this token's user.
+                const listRes = await gatewayFetch(cleanBase, '/agents', '/avatars', {
                     method: 'GET',
                     headers: {
                         Authorization: `Bearer ${currentToken}`,
                     },
                 });
                 if (listRes.ok) {
-                    const listData = await listRes.json();
-                    const avatars = listData?.data?.avatars || [];
-                    if (avatars.length > 0) {
-                        targetAvatarId = avatars[0].id;
+                    const listData = (await listRes.json())?.data;
+                    const agents = listData?.agents || listData?.avatars || [];
+                    if (agents.length > 0) {
+                        targetAgentId = agents[0].id;
                     }
                 }
             }
-            if (!targetAvatarId) {
-                throw new Error('No Avatar configured or assigned to this token.');
+            if (!targetAgentId) {
+                throw new Error('No agent is assigned to these keys. Create one on the FacePe dashboard (Agents).');
             }
             // Request live streaming session from FacePe SDK backend
-            const sessionResp = await fetch(`${cleanBase}/avatars/${targetAvatarId}/sessions`, {
+            const agentPath = encodeURIComponent(targetAgentId);
+            const sessionResp = await gatewayFetch(cleanBase, `/agents/${agentPath}/sessions`, `/avatars/${agentPath}/sessions`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
@@ -258,7 +302,7 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             });
             if (!sessionResp.ok) {
                 const errBody = await sessionResp.json().catch(() => ({}));
-                const errMsg = errBody?.error?.message || errBody?.message || 'Failed to initialize avatar session';
+                const errMsg = errBody?.error?.message || errBody?.message || 'Failed to start the conversation';
                 throw new Error(errMsg);
             }
             const sessionPayload = await sessionResp.json();
@@ -266,7 +310,10 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             usageIdRef.current = sessionInfo?.usageId || null;
             conversationRef.current = {
                 conversationId: usageIdRef.current,
-                avatar: { id: String(sessionInfo?.avatar?.id ?? targetAvatarId), name: String(sessionInfo?.avatar?.name ?? '') },
+                agent: (() => {
+                    const who = sessionInfo?.agent ?? sessionInfo?.avatar;
+                    return { id: String(who?.id ?? targetAgentId), name: String(who?.name ?? '') };
+                })(),
                 language: language ?? null,
                 startedAt: new Date(),
                 lines: [],
@@ -524,7 +571,7 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
         }
     }, [
         hasLiveKit,
-        avatarKey,
+        chosenAgent,
         language,
         enableMic,
         apiBaseUrl,

package/dist/types.d.ts

@@ -22,9 +22,33 @@ export interface FacePeConversationLine {
  * (`onConversationEnd`). It stays in your app: the SDK sends it nowhere — you
  * decide whether to show, keep or send it.
  */
+/** One question of a form avatar, with the customer's answer (null: not answered). */
+export interface FacePeFormAnswer {
+    label: string;
+    question: string;
+    required: boolean;
+    value: string | null;
+}
+/** A form avatar's form, filled from the conversation. */
+export interface FacePeFilledForm {
+    title: string;
+    /** Every required question has an answer. */
+    complete: boolean;
+    fields: FacePeFormAnswer[];
+    /** Documents the customer was asked to upload once the form was done (may be empty). */
+    documents: string[];
+    /** Where to upload them, as the company wrote it (empty when not set). */
+    uploadWhere: string;
+}
 export interface FacePeConversation {
     /** The conversation's id (its FacePe usage record), or null if none was opened. */
     conversationId: string | null;
+    /** The agent that held the conversation. */
+    agent: {
+        id: string;
+        name: string;
+    };
+    /** @deprecated The same as `agent` (kept for apps from before agents). */
     avatar: {
         id: string;
         name: string;
@@ -41,6 +65,12 @@ export interface FacePeConversation {
     endReason: 'ended' | 'disconnected' | 'unmounted';
     /** Every line, in order (a line that grew while being spoken appears once, complete). */
     transcript: FacePeConversationLine[];
+    /**
+     * For an avatar that fills a form: its questions with the customer's answers,
+     * read from the conversation. Null for other avatars, or when the answers
+     * could not be read.
+     */
+    form: FacePeFilledForm | null;
 }
 export interface OrderItem {
     name: string;
@@ -64,7 +94,12 @@ export interface TokenProviderParams {
 }
 export type TokenProvider = (params: TokenProviderParams) => Promise<string>;
 export interface FacePeMobileAvatarProps {
-    /** Specific avatar identifier or key override */
+    /**
+     * The agent to talk to (its id, from the FacePe dashboard's SDK page or
+     * GET /agents). Without one, the first agent assigned to the keys' user.
+     */
+    agentId?: string;
+    /** @deprecated Use `agentId` (the same id; kept for apps from before agents). */
     avatarKey?: string;
     /** Language to converse in ('en', 'es', 'hi', etc.) */
     language?: string;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, reported in conversation records. Keep in step with package.json. */
-export declare const SDK_VERSION = "1.3.1";
+export declare const SDK_VERSION = "1.5.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** This package's version, reported in conversation records. Keep in step with package.json. */
-export const SDK_VERSION = '1.3.1';
+export const SDK_VERSION = '1.5.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facepe/widget-mobile-app",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "FacePe AI 3D Video Avatar Native Live Streaming SDK for React Native (iOS & Android)",
   "main": "./dist/index.js",
   "module": "./dist/index.js",