andy-widget-react 2.0.5 → 2.1.0

package/dist/types/types/index.d.ts

@@ -37,15 +37,23 @@ export interface ChatbotConfig {
     collectUserInfo: CollectUserInfoConfig;
     predefinedQuestions: PredefinedQuestion[];
     faqs: FAQItem[];
+    bootstrap?: {
+        convexUrl: string;
+        surfaceKey: string;
+        surfaceProof: string;
+        surfaceProofExpiresAt: number;
+    };
 }
 export interface Message {
-    id: number;
+    id: string | number;
     content: string;
     sender: 'user' | 'bot';
     timestamp: string;
     isForm?: boolean;
     isLoading?: boolean;
     isError?: boolean;
+    isHuman?: boolean;
+    isWaiting?: boolean;
 }
 export interface UserInfo {
     name: string;
@@ -66,6 +74,10 @@ export interface AndyChatProps {
     welcomeMessage?: string;
     /** Optional custom label for pill-style bubble (overrides default) */
     bubbleLabel?: string;
+    /** Optional UI language for the widget's own chrome, overrides the Agent's defaultLang */
+    lang?: 'en' | 'es';
+    /** Optional starter questions (overrides API value) */
+    predefinedQuestions?: PredefinedQuestion[];
     /** Optional theme ('light' | 'dark' | 'auto') */
     theme?: 'light' | 'dark' | 'auto';
     /** Optional position ('left' | 'right') */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "andy-widget-react",
-	"version": "2.0.5",
+	"version": "2.1.0",
 	"description": "Official React Widget for embeddable Andy agents",
 	"type": "module",
 	"main": "dist/index.cjs",
@@ -67,6 +67,6 @@
 		"react-dom": "^18.0.0 || ^19.0.0"
 	},
 	"dependencies": {
-		"andy-widget-core": "2.0.5"
+		"andy-widget-core": "2.1.0"
 	}
 }

package/src/AndyChat.tsx

@@ -5,11 +5,12 @@ import {
 	fetchChatbotConfig,
 	generateSessionId,
 	createGreetingMessage,
-	sendMessage as sendMessageToAPI,
+	sendMessageForWidget as sendMessageToAPI,
 	submitUserInfo,
 	isValidEmbedId,
 	getFullStylesheet,
 	getHostClasses,
+	createBrowserHandoff,
 	parseMarkdown,
 	CHAT_BUBBLE_DEFAULT_ICON,
 	CHAT_BUBBLE_DEFAULT_ICON_URL,
@@ -17,6 +18,7 @@ import {
 	FOOTER_TEXT,
 	getFooterUrl,
 	getDefaultBubbleLabel,
+	getUiStrings,
 	getKeyboardDetector,
 	updateKeyboardHeight,
 	isMobileDevice
@@ -73,6 +75,8 @@ const AndyChat: React.FC<AndyChatProps> = ({
 	description,
 	welcomeMessage,
 	bubbleLabel,
+	lang,
+	predefinedQuestions,
 	theme,
 	orientation,
 	brandColor,
@@ -83,10 +87,17 @@ const AndyChat: React.FC<AndyChatProps> = ({
 	initialOpen = false
 }) => {
 	const [config, setConfig] = useState<ChatbotConfig | null>(null)
+	// The visitor's language wins over the Agent's own default: a Spanish Agent
+	// embedded on an English page must still render English chrome.
+	const uiLang = lang || config?.defaultLang || 'en'
+	const strings = getUiStrings(uiLang)
+	const activeQuestions = predefinedQuestions?.length ? predefinedQuestions : config?.predefinedQuestions
 	const [isOpen, setIsOpen] = useState(initialOpen)
 	const [messages, setMessages] = useState<Message[]>([])
 	const [isLoading, setIsLoading] = useState(false)
 	const [sessionId, setSessionId] = useState(() => generateSessionId())
+	const handoffRef = useRef<ReturnType<typeof createBrowserHandoff>>(null)
+	const pendingHandoffIdsRef = useRef<string[]>([])
 	const [shadowReady, setShadowReady] = useState(false)
 	const [showPredefinedQuestions, setShowPredefinedQuestions] = useState(true)
 	const [userInfoCollected, setUserInfoCollected] = useState(false)
@@ -102,6 +113,29 @@ const AndyChat: React.FC<AndyChatProps> = ({
 	const welcomePopupShownRef = useRef(false)
 	const welcomePopupTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
+	useEffect(() => {
+		if (!config?.bootstrap || !config.id) return
+		handoffRef.current?.stop()
+		const handoff = createBrowserHandoff(config.id, config.bootstrap, projection => {
+			if (projection.offline) return
+			setSessionId(projection.identity.sessionId)
+			pendingHandoffIdsRef.current = projection.pendingProjectionIds || []
+			const projectedMessages = projection.messages.map(message => ({ id: message.id, content: message.content, sender: message.role === 'user' ? 'user' as const : 'bot' as const, timestamp: new Date(message.createdAt).toISOString(), isHuman: message.sentByHuman }))
+			setMessages(projection.control === 'requested' || projection.control === 'human'
+				? [...projectedMessages, { id: 'handoff-waiting', content: strings.handoffWaiting, sender: 'bot', timestamp: new Date().toISOString(), isWaiting: true }]
+				: projectedMessages)
+		})
+		handoffRef.current = handoff
+		return () => {
+			handoff?.stop()
+			handoffRef.current = null
+		}
+	}, [config?.bootstrap, config?.id])
+
+	useEffect(() => {
+		pendingHandoffIdsRef.current.forEach(messageId => void handoffRef.current?.markRendered(messageId))
+	}, [messages])
+
 	// Create shadow DOM container on mount
 	useEffect(() => {
 		if (!containerRef.current) return
@@ -300,12 +334,12 @@ const AndyChat: React.FC<AndyChatProps> = ({
 				bubbleStyle: bubbleStyle || 'icon',
 				bubbleLabel: bubbleLabel || null,
 				useBrandColor: useBrandColor !== undefined ? useBrandColor : true,
-				defaultLang: 'en',
+				defaultLang: uiLang,
 				showBranding: true,
 				showWelcomePopup: { enabled: false, seconds: 3, message: '' },
 				collectUserInfo: { enabled: false, message: '' },
 				welcomeMessage: welcomeMessage || 'Hi there! How can I help you today?',
-				predefinedQuestions: [],
+				predefinedQuestions: predefinedQuestions || [],
 				faqs: []
 			}
 			setConfig(previewConfig)
@@ -469,7 +503,7 @@ const AndyChat: React.FC<AndyChatProps> = ({
 			setMessages([])
 		}
 
-		if (config?.predefinedQuestions && config.predefinedQuestions.length > 0) {
+		if (activeQuestions && activeQuestions.length > 0) {
 			setShowPredefinedQuestions(true)
 		}
 	}
@@ -490,6 +524,7 @@ const AndyChat: React.FC<AndyChatProps> = ({
 				sender: 'user',
 				timestamp: new Date().toISOString()
 			}
+			handoffRef.current?.recordVisitorMessage(messageText)
 			setMessages(prev => [...prev, userMessage])
 
 			if (hidePredefined) {
@@ -499,10 +534,14 @@ const AndyChat: React.FC<AndyChatProps> = ({
 			try {
 				setIsLoading(true)
 				const response = await sendMessageToAPI(embedId!, sessionId, messageText)
+				if (response.status === 'waiting') {
+					setMessages(prev => prev.some(message => message.isWaiting) ? prev : [...prev, { id: 'handoff-waiting', content: strings.handoffWaiting, sender: 'bot', timestamp: new Date().toISOString(), isWaiting: true }])
+					return
+				}
 
 				const botMessage: Message = {
 					id: timestamp + 1,
-					content: response,
+					content: response.text,
 					sender: 'bot',
 					timestamp: new Date().toISOString()
 				}
@@ -525,10 +564,7 @@ const AndyChat: React.FC<AndyChatProps> = ({
 				console.error('AndyChat: Message request failed.')
 				const errorMessage: Message = {
 					id: timestamp + 3,
-					content:
-						config?.defaultLang === 'es'
-							? 'Lo siento, no pude responder. Inténtalo de nuevo.'
-							: 'Sorry, I could not answer. Please try again.',
+					content: strings.sendFailure,
 					sender: 'bot',
 					timestamp: new Date().toISOString(),
 					isError: true
@@ -673,7 +709,7 @@ const AndyChat: React.FC<AndyChatProps> = ({
 
 		const isPillStyle = config?.bubbleStyle === 'pill'
 		const displayLabel =
-			bubbleLabel || config?.bubbleLabel || (isPillStyle ? getDefaultBubbleLabel(config?.defaultLang || 'en') : null)
+			bubbleLabel || config?.bubbleLabel || (isPillStyle ? getDefaultBubbleLabel(uiLang) : null)
 		const bubbleLogoUrl = config?.logoUrl || CHAT_BUBBLE_DEFAULT_ICON_URL
 
 		if (bubble) {
@@ -897,11 +933,11 @@ const AndyChat: React.FC<AndyChatProps> = ({
 									return (
 										<div
 											key={message.id}
-											className={`andy-message-container andy-message-container--${message.sender}`}
+											className={`andy-message-container andy-message-container--${message.sender} ${message.isWaiting ? 'andy-message-container--waiting' : ''}`}
 										>
 											{message.sender === 'bot' && (
 												<div
-													className={`andy-message andy-message--bot ${message.isError ? 'andy-message--error' : ''}`}
+															className={`andy-message andy-message--bot ${message.isHuman ? 'andy-message--operator' : ''} ${message.isWaiting ? 'andy-message--waiting' : ''} ${message.isError ? 'andy-message--error' : ''}`}
 												>
 													<div className='andy-bot-header'>
 														<div className='andy-bot-header__icon'>
@@ -919,7 +955,9 @@ const AndyChat: React.FC<AndyChatProps> = ({
 																/>
 															)}
 														</div>
-														<span className='andy-bot-header__name'>{config?.name || 'Andy bot'}</span>
+									<span className='andy-bot-header__name'>
+										{message.isHuman ? strings.teamName : config?.name || 'Andy bot'}
+									</span>
 													</div>
 													<div className='andy-message__content'>
 														<div dangerouslySetInnerHTML={{ __html: parseMarkdown(message.content) }} />
@@ -951,15 +989,15 @@ const AndyChat: React.FC<AndyChatProps> = ({
 							</div>
 
 							<div className='andy-chat-window__bottom'>
-								{config?.predefinedQuestions &&
-									config.predefinedQuestions.length > 0 &&
+								{activeQuestions &&
+									activeQuestions.length > 0 &&
 									showPredefinedQuestions && (
 										<div className='andy-predefined-questions' id='andy-predefined-questions'>
 											<div className='andy-predefined-questions__header'>
-												<p className='andy-predefined-questions__title'>What would you like to know?</p>
+												<p className='andy-predefined-questions__title'>{strings.predefinedQuestionsTitle}</p>
 											</div>
 											<div className='andy-predefined-questions__list'>
-												{config.predefinedQuestions.map((q, index) => (
+												{activeQuestions.map((q, index) => (
 													<button
 														key={index}
 														type='button'
@@ -982,7 +1020,7 @@ const AndyChat: React.FC<AndyChatProps> = ({
 												type='text'
 												className='andy-input__field'
 												id='andy-message-input'
-												placeholder={config ? 'Type your message...' : '...'}
+												placeholder={config ? strings.inputPlaceholder : '...'}
 												aria-label='Message input'
 												onKeyDown={e => {
 													if (e.key === 'Enter' && (e.target as HTMLInputElement).value.trim()) {

package/src/hooks/useAndyChat.ts

@@ -3,7 +3,7 @@ import {
 	fetchChatbotConfig,
 	generateSessionId,
 	createGreetingMessage,
-	sendMessage as sendMessageToAPI,
+	sendMessageForWidget as sendMessageToAPI,
 	submitUserInfo as submitUserInfoAPI,
 	initializeConfig,
 	validateChatbotConfig,
@@ -142,10 +142,11 @@ export const useAndyChat = (embedId: string): UseAndyChatReturn => {
 
 			try {
 				const response = await sendMessageToAPI(embedId, sessionId, messageText)
+				if (response.status === 'waiting') return response
 
 				const botMessage: Message = {
 					id: Date.now() + 1,
-					content: response || 'I apologize, but I encountered an error processing your request.',
+					content: response.text || 'I apologize, but I encountered an error processing your request.',
 					sender: 'bot',
 					timestamp: new Date().toISOString()
 				}

package/src/types/index.ts

@@ -47,17 +47,25 @@ export interface ChatbotConfig {
 	collectUserInfo: CollectUserInfoConfig
 	predefinedQuestions: PredefinedQuestion[]
 	faqs: FAQItem[]
+	bootstrap?: {
+		convexUrl: string
+		surfaceKey: string
+		surfaceProof: string
+		surfaceProofExpiresAt: number
+	}
 }
 
 // Message in the chat
 export interface Message {
-	id: number
+	id: string | number
 	content: string
 	sender: 'user' | 'bot'
 	timestamp: string
 	isForm?: boolean
 	isLoading?: boolean
 	isError?: boolean
+	isHuman?: boolean
+	isWaiting?: boolean
 }
 
 // User info for form submission
@@ -82,6 +90,10 @@ export interface AndyChatProps {
 	welcomeMessage?: string
 	/** Optional custom label for pill-style bubble (overrides default) */
 	bubbleLabel?: string
+	/** Optional UI language for the widget's own chrome, overrides the Agent's defaultLang */
+	lang?: 'en' | 'es'
+	/** Optional starter questions (overrides API value) */
+	predefinedQuestions?: PredefinedQuestion[]
 	/** Optional theme ('light' | 'dark' | 'auto') */
 	theme?: 'light' | 'dark' | 'auto'
 	/** Optional position ('left' | 'right') */