@developer.notchatbot/webchat 1.5.3 → 1.7.1

package/README.md

@@ -44,6 +44,8 @@ interface WebChatConfig {
     active?: boolean;                   // Enable or disable the button (default: true)
     color?: string;                     // Customize the internal WhatsApp button color
   };
+  apiBaseUrl?: string;                  // Backend override (see "Targeting a non-production backend")
+  realtimeUrl?: string;                 // Convex deployment override (same section)
 }
 
 interface WebChatPositionConfig {
@@ -85,6 +87,33 @@ WebChat.initialize({
 });
 ```
 
+## 🎯 Targeting a non-production backend
+
+By default the widget picks its backend from the hostname of the page it runs
+on: `localhost` → `http://localhost:3000`, anything else → production
+(`https://next.notchatbot.com`). That default is right for a merchant's
+storefront, but wrong wherever the page itself is a non-production deployment —
+a Vercel preview, `dev.notchatbot.com`, or a local dev server on a port other
+than 3000. Without an override, a message typed on a preview lands in the
+**production** inbox.
+
+`apiBaseUrl` and `realtimeUrl` override that detection:
+
+```js
+WebChat.initialize({
+    apiKey: "your-chatbot-uid",
+    apiBaseUrl: window.location.origin,          // HTTP: /api/webchat, /upload, /rate
+    realtimeUrl: "https://<deployment>.convex.cloud" // Convex realtime subscriptions
+});
+```
+
+- Both must be `https://` (or `http://localhost` / `http://127.0.0.1`); anything
+  else is ignored with a console warning and the defaults are kept.
+- **Set them as a pair.** `apiBaseUrl` alone writes to one deployment while the
+  widget keeps listening on the default Convex, so agent replies never arrive.
+- Omitting them keeps the previous behaviour exactly — existing embeds are
+  unaffected, and each `initialize()` clears any override from a prior call.
+
 # 💬 WhatsApp Button
 
 If you simply want a floating WhatsApp action button with no WebChat, you can use `WhatsAppButtonAPI`, which isolates itself in the Shadow DOM to avoid CSS conflicts.

package/dist/config/endpoints.d.ts

@@ -5,6 +5,15 @@ export interface EndpointConfig {
     rateEndpoint: string;
     realtimeUrl: string;
 }
+/**
+ * Replaces the endpoint overrides. Called on every `initialize()`, so a config
+ * without these keys clears any previous override. Invalid URLs are ignored
+ * with a warning and the environment defaults are kept.
+ */
+export declare function setEndpointOverrides(overrides: {
+    apiBaseUrl?: string;
+    realtimeUrl?: string;
+}): void;
 /**
  * Detecta si estamos en ambiente de desarrollo
  */

package/dist/types.d.ts

@@ -25,6 +25,22 @@ export interface WebChatConfig {
     whatsapp?: Omit<WhatsAppConfig, 'position' | 'marginBottom' | 'marginSide' | 'mobile' | 'desktop'> & {
         active?: boolean;
     };
+    /**
+     * Optional backend base URL override (e.g. a Vercel preview deployment or
+     * dev.notchatbot.com). `/api/webchat`, `/api/webchat/upload` and
+     * `/api/webchat/conversation/rate` are derived from it. Must be https://
+     * (or http://localhost). Omitted or invalid → the environment defaults.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Optional Convex deployment URL override for the realtime subscriptions
+     * (agent replies, history, activation). Must be https:// (or
+     * http://localhost). Omitted or invalid → the environment default.
+     *
+     * Pair it with `apiBaseUrl`: pointing HTTP at one deployment and realtime at
+     * another means the widget writes to one database and listens on another.
+     */
+    realtimeUrl?: string;
     /**
      * Optional GTM/GA event name overrides for dataLayer pushes.
      * If omitted, defaults are used.
@@ -142,6 +158,15 @@ export interface ChatWindowProps {
     isRated?: boolean;
     onRatingChange?: (isRated: boolean) => void;
     conversationId?: string;
+    /** Configurable auto-survey threshold from the backend; undefined = legacy default (2). */
+    surveyAfterUserMessages?: number;
+    /** Timestamp of the last manual survey request from Livechat; undefined = never requested. */
+    webchatSurveyRequestedAt?: number;
+}
+/** Survey-related conversation state forwarded from the Convex realtime subscription. */
+export interface ConversationSurveyState {
+    surveyAfterUserMessages?: number;
+    webchatSurveyRequestedAt?: number;
 }
 export interface ChatHeaderProps {
     title: string;
@@ -195,8 +220,16 @@ export interface WebChatInstance {
     setIsOpen?: (open: boolean) => void;
     updateConfig?: (newConfig: Partial<WebChatConfig>) => void;
     setPosition?: (pos: Partial<WebChatConfig>) => void;
+    getIsOpen?: () => boolean;
     hide?: () => void;
     show?: () => void;
+    /**
+     * Starts a new conversation in place: new conversation id, empty transcript,
+     * fresh visitor session, realtime subscriptions reopened. Unlike calling
+     * `initialize()` again it does not destroy and rebuild the widget, so the
+     * panel does not blink out while the new thread is prepared.
+     */
+    restartConversation?: () => void;
     injectCSS?: (css: string) => void;
     removeCustomCSS?: () => void;
 }

package/dist/utils/convex.d.ts

@@ -1,5 +1,5 @@
 import { ConvexReactClient } from 'convex/react';
-import { Message } from '../types';
+import { ConversationSurveyState, Message } from '../types';
 export interface ConvexConnectionData {
     client: ConvexReactClient;
     unsubscribe: (() => void) | null;
@@ -11,9 +11,10 @@ export interface ConvexConnectionData {
  * @param conversationId Conversation ID
  * @param onMessage Callback for new messages
  * @param onChatbotToggle Callback for chatbot activation changes
+ * @param onSurveyStateChange Callback for survey state changes (threshold + manual trigger)
  * @returns Promise that resolves to Convex connection data
  */
-export declare const initializeConvexConnection: (realtimeEndpoint: string, _chatbotUid: string, conversationId: string, onMessage: (message: Message) => void, onChatbotToggle?: (chatbotActivated: boolean) => void) => Promise<ConvexConnectionData>;
+export declare const initializeConvexConnection: (realtimeEndpoint: string, _chatbotUid: string, conversationId: string, onMessage: (message: Message) => void, onChatbotToggle?: (chatbotActivated: boolean) => void, onSurveyStateChange?: (surveyState: ConversationSurveyState) => void) => Promise<ConvexConnectionData>;
 /**
  * Fetches initial conversation data with messages from Convex
  * @param realtimeEndpoint Realtime service deployment URL

package/dist/utils/survey.d.ts

@@ -0,0 +1,30 @@
+import { Message } from '../types';
+/** Legacy hardcoded threshold, used when the backend does not send one. */
+export declare const DEFAULT_SURVEY_AFTER_USER_MESSAGES = 2;
+/**
+ * Resolves the configured auto-survey threshold.
+ * Falls back to the default when the backend does not expose the field yet
+ * or sends something unusable (non-number, NaN, zero/negative).
+ */
+export declare const resolveSurveyThreshold: (value: unknown) => number;
+/** Counts only messages sent by the end user (bot/employee ones don't count). */
+export declare const countUserMessages: (messages: Message[]) => number;
+/**
+ * Whether the survey should auto-open because the user reached the
+ * configured message threshold. Never true for already rated conversations.
+ */
+export declare const shouldAutoShowSurvey: (messages: Message[], surveyAfterUserMessages: number | undefined, isRated: boolean) => boolean;
+/**
+ * Whether a manual survey request (`webchatSurveyRequestedAt`, a timestamp
+ * written by an agent from Livechat) is a new, still unhandled trigger.
+ * Comparing against the last handled value — not just presence — keeps
+ * re-renders and Convex reconnections from re-opening the survey for the
+ * same request, while a fresh timestamp triggers it again.
+ *
+ * Deliberately NOT gated on `isRated`: a manual request fired after a rating
+ * re-opens the survey so the agent can re-validate the experience (the new
+ * rating overwrites the previous one server-side). Stale requests can't leak
+ * across reloads because the backend clears `webchatSurveyRequestedAt` when a
+ * rating is submitted — a present timestamp is always a pending ask.
+ */
+export declare const isNewSurveyRequest: (requestedAt: number | undefined, lastHandledRequestedAt: number | undefined) => boolean;