@exotel-npm-dev/exotel-ai-assist 1.1.0 → 1.1.2

package/README.md

@@ -113,12 +113,14 @@ function AgentDashboard() {
 import { useExotelAIAssist } from "@exotel-npm-dev/exotel-ai-assist/react";
 
 function MyCustomUI({ call_sid }: { call_sid: string }) {
-  const { status, suggestions, transcripts, lastError } = useExotelAIAssist({
+  const { isReady, status, suggestions, transcripts, lastError } = useExotelAIAssist({
     authToken: "your-auth-token",
     call_sid,
     accountId: "your-account-id",
   });
 
+  if (!isReady) return <p>Connecting…</p>;
+
   return (
     <div>
       <p>Status: {status}</p>
@@ -169,6 +171,16 @@ const ctrl = new ExotelAIAssistController({
   authToken: "your-auth-token",
   call_sid: "CALL-SID-001",
   accountId: "your-account-id",
+  env: "production", // defaults to PRODUCTION if omitted
+});
+
+ctrl.on("onReady", (ready) => {
+  if (ready) {
+    console.log("Connection established and acknowledged by server");
+    // Safe to start consuming data / show the UI
+  } else {
+    console.log("Connection lost");
+  }
 });
 
 ctrl.on("suggestion", (s) => console.log("Suggestion:", s));
@@ -210,15 +222,16 @@ Extends `EventEmitter`.
 
 #### Constructor options (`ExotelAIAssistParams`)
 
-| Field                  | Type     | Required | Default                  | Description                                              |
-| ---------------------- | -------- | -------- | ------------------------ | -------------------------------------------------------- |
-| `authToken`            | `string` | ✓        | —                        | Bearer token                                             |
-| `call_sid`             | `string` | ✓        | —                        | Active call SID                                          |
-| `accountId`            | `string` | ✓        | —                        | Exotel account identifier                                |
-| `wssBaseUrl`           | `string` | —        | Exotel AI Assist backend | Override only when pointing at a non-production endpoint |
-| `reconnectInterval`    | `number` | —        | `3000`                   | Base reconnect delay in ms                               |
-| `maxReconnectAttempts` | `number` | —        | `5`                      | Max retries before error                                 |
-| `[customParam]`        | `string` | —        | —                        | Max 3 params you can send                                |
+| Field                  | Type          | Required | Default                    | Description                                                        |
+| ---------------------- | ------------- | -------- | -------------------------- | ------------------------------------------------------------------ |
+| `authToken`            | `string`      | ✓        | —                          | Bearer token                                                       |
+| `call_sid`             | `string`      | ✓        | —                          | Active call SID                                                    |
+| `accountId`            | `string`      | ✓        | —                          | Exotel account identifier                                          |
+| `env`                  | `"production" or "uat" or "development"` |  —      | `production`   | Target environment (`production`, `uat`, or `development`)         |
+| `wssBaseUrl`           | `string`      | —        | Derived from `env`         | Full override for the WebSocket URL (takes precedence over `env`)  |
+| `reconnectInterval`    | `number`      | —        | `3000`                     | Base reconnect delay in ms                                         |
+| `maxReconnectAttempts` | `number`      | —        | `5`                        | Max retries before error                                           |
+| `[customParam]`        | `string`      | —        | —                          | Extra query params forwarded to the server (max 3)                 |
 
 #### Methods
 
@@ -232,16 +245,33 @@ Extends `EventEmitter`.
 
 #### Events
 
-| Event          | Payload            | Description                            |
-| -------------- | ------------------ | -------------------------------------- |
-| `suggestion`   | `Suggestion`       | New AI suggestion (capped at last 50)  |
-| `transcript`   | `TranscriptLine[]` | Live transcript update                 |
-| `sentiment`    | `Sentiment`        | Sentiment label update                 |
-| `onCallStart`  | `unknown`          | Connection opened                      |
-| `onCallEnd`    | `unknown`          | Connection closed                      |
-| `statusChange` | `ConnectionStatus` | Status transition                      |
-| `error`        | `Error`            | Any error (auth, parse, max-reconnect) |
-| `raw`          | `unknown`          | Every raw server message               |
+| Event          | Payload            | Description                                                                                                     |
+| -------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `onReady`      | `boolean`          | `true` when connected and server sends `ack`; `false` on disconnect. Multi-tab safe — works for follower tabs too |
+| `suggestion`   | `Suggestion`       | New AI suggestion (capped at last 50)                                                                           |
+| `transcript`   | `TranscriptLine[]` | Live transcript update                                                                                          |
+| `sentiment`    | `Sentiment`        | Sentiment label update                                                                                          |
+| `onCallStart`  | —                  | Connection opened                                                                                               |
+| `onCallEnd`    | —                  | Connection closed                                                                                               |
+| `statusChange` | `ConnectionStatus` | Status transition                                                                                               |
+| `error`        | `Error`            | Any error (auth, parse, max-reconnect)                                                                          |
+| `raw`          | `unknown`          | Every raw server message                                                                                        |
+
+---
+
+### `useExotelAIAssist(params)` — Hook return values
+
+| Field         | Type               | Description                                                            |
+| ------------- | ------------------ | ---------------------------------------------------------------------- |
+| `isReady`     | `boolean`          | `true` after connected + server ack. Multi-tab safe. `false` on disconnect |
+| `status`      | `ConnectionStatus` | Current connection status                                              |
+| `suggestions` | `Suggestion[]`     | AI suggestions, oldest first, capped at 50                             |
+| `transcripts` | `TranscriptLine[]` | Live transcript lines, ordered by start time                           |
+| `sentiment`   | `Sentiment \| null`| Latest sentiment reading                                               |
+| `lastError`   | `Error \| null`    | Most recent error                                                      |
+| `connect()`   | `() => void`       | Manually open the connection                                           |
+| `disconnect()` | `() => void`      | Manually close the connection                                          |
+| `setParams()` | `(patch) => void`  | Merge params; reconnects if connection params change                   |
 
 ---
 

package/dist/components/ExotelAIAssistApp.d.ts

@@ -2,6 +2,8 @@ import { ExotelAIAssistParams } from "../types";
 import "../styles/index.css";
 export interface ExotelAIAssistProps extends ExotelAIAssistParams {
     className?: string;
+    /** Called with `true` when the server acknowledges the connection, `false` on disconnect. */
+    onReady?: (ready: boolean) => void;
 }
-export declare function ExotelAIAssist({ className, ...params }: ExotelAIAssistProps): JSX.Element;
+export declare function ExotelAIAssist({ className, onReady, ...params }: ExotelAIAssistProps): JSX.Element;
 export { ExotelAIAssist as ExotelAIAssistApp };

package/dist/controller/index.d.ts

@@ -6,6 +6,7 @@ export declare class ExotelAIAssistController extends EventEmitter<ControllerEve
     private status;
     private destroyed;
     private connectionEstablished;
+    private readyFired;
     private reconnectAttempt;
     private reconnectTimer;
     private static readonly MAX_RECONNECT_ATTEMPTS;
@@ -20,6 +21,7 @@ export declare class ExotelAIAssistController extends EventEmitter<ControllerEve
     private _handleTransportMessage;
     private _scheduleReconnect;
     private _clearReconnectTimer;
+    private _fireReady;
     private _handleServerPayload;
     private _setStatus;
 }

package/dist/controller/index.js

@@ -343,6 +343,7 @@ class BroadcastChannelTransport {
     this.pendingUrl = null;
     this.pendingAuthToken = null;
     this.lockReleaser = null;
+    this.ackReceived = false;
     this._destroyed = false;
     const channelName = `exotel-ai-assist:${sessionHash}`;
     const lockName = `exotel-ai-assist-leader:${sessionHash}`;
@@ -351,12 +352,15 @@ class BroadcastChannelTransport {
       var _a;
       const data = ev.data;
       if (this.isLeader) {
-        // A new follower tab has opened. If our socket is already connected,
-        // broadcast CONNECTED so the follower can sync its status immediately.
         if (data.type === "JOIN" && this.socketConnected) {
           this.channel.postMessage({
             type: "CONNECTED"
           });
+          if (this.ackReceived) {
+            this.channel.postMessage({
+              type: "ACKNOWLEDGED"
+            });
+          }
         }
         return;
       }
@@ -411,6 +415,7 @@ class BroadcastChannelTransport {
       var _a;
       if (this._destroyed) return;
       this.socketConnected = true;
+      this.ackReceived = false;
       this.socket.send(JSON.stringify({
         type: "auth",
         access_token: authToken
@@ -445,6 +450,7 @@ class BroadcastChannelTransport {
       var _a;
       if (this._destroyed) return;
       this.socketConnected = false;
+      this.ackReceived = false;
       const msg = {
         type: "DISCONNECTED",
         code: ev.code
@@ -477,6 +483,9 @@ class BroadcastChannelTransport {
   onMessage(handler) {
     this.handler = handler;
   }
+  markAcknowledged() {
+    this.ackReceived = true;
+  }
   destroy() {
     var _a;
     this._destroyed = true;
@@ -1497,6 +1506,18 @@ function requireObject_hash() {
 var object_hashExports = requireObject_hash();
 var objectHash = /*@__PURE__*/getDefaultExportFromCjs(object_hashExports);
 
+var Environment;
+(function (Environment) {
+  Environment["PRODUCTION"] = "production";
+  Environment["UAT"] = "uat";
+  Environment["DEVELOPMENT"] = "development";
+})(Environment || (Environment = {}));
+const WssBaseUrl = {
+  [Environment.PRODUCTION]: "wss://ai-assist.in.exotel.com",
+  [Environment.UAT]: "wss://oneassist-uat.in.exotel.com",
+  [Environment.DEVELOPMENT]: "ws://localhost:8081"
+};
+
 class Utils {
   /**
    * Returns a deterministic SHA-1 hex digest for any plain object.
@@ -1528,10 +1549,16 @@ class Utils {
    * @param accountId - The account ID to get the base WebSocket URL for.
    * @returns The base WebSocket URL.
    */
-  static getWssBaseUrl(accountId) {
-    // return `wss://ai-assist.in.exotel.com/ai-assist/accounts/${accountId}/one-assistant-event-publisher`;
-    // return `wss://oneassist-uat.in.exotel.com/ai-assist/one-assistant-event-publisher/${accountId}`;
-    return `wss://oneassist-uat.in.exotel.com/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+  static getWssBaseUrl(accountId, env) {
+    if (env === Environment.DEVELOPMENT) {
+      return `${WssBaseUrl[Environment.DEVELOPMENT]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    } else if (env === Environment.UAT) {
+      return `${WssBaseUrl[Environment.UAT]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    } else if (env === Environment.PRODUCTION) {
+      return `${WssBaseUrl[Environment.PRODUCTION]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    } else {
+      return `${WssBaseUrl[Environment.PRODUCTION]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    }
   }
   /**
    * Builds a WebSocket URL from the given parameters.
@@ -1539,17 +1566,18 @@ class Utils {
    * @returns The WebSocket URL.
    */
   static buildWsUrl(params) {
+    var _a;
     const {
       wssBaseUrl
     } = params;
-    const resolved = wssBaseUrl !== null && wssBaseUrl !== void 0 ? wssBaseUrl : Utils.getWssBaseUrl(params.accountId);
+    const resolved = wssBaseUrl !== null && wssBaseUrl !== void 0 ? wssBaseUrl : Utils.getWssBaseUrl(params.accountId, (_a = params === null || params === void 0 ? void 0 : params.env) !== null && _a !== void 0 ? _a : Environment.PRODUCTION);
     const base = resolved.endsWith("/") ? resolved.slice(0, -1) : resolved;
     const query = Utils.constructQueryParams(params);
     return `${base}?${query}`;
   }
   static constructQueryParams(params) {
     // Keys consumed by the library — never forwarded to the server.
-    const INTERNAL_KEYS = new Set(["authToken", "accountId", "wssBaseUrl", "reconnectInterval", "maxReconnectAttempts"]);
+    const INTERNAL_KEYS = new Set(["authToken", "accountId", "wssBaseUrl", "reconnectInterval", "maxReconnectAttempts", "env"]);
     // Mandatory server params remapped to the names the API expects.
     // accountId is embedded in the URL path — never sent as a query param.
     const pairs = [];
@@ -1595,6 +1623,7 @@ class ExotelAIAssistController extends EventEmitter {
     //   connectionEstablished === false  → connection never opened → retry
     //   connectionEstablished === true   → server ended a live connection → destroy
     this.connectionEstablished = false;
+    this.readyFired = false;
     this.reconnectAttempt = 0;
     this.reconnectTimer = null;
     this.params = Object.assign({}, params);
@@ -1603,6 +1632,7 @@ class ExotelAIAssistController extends EventEmitter {
     if (this.destroyed) return;
     this._clearReconnectTimer();
     this.connectionEstablished = false;
+    this.readyFired = false;
     this.reconnectAttempt = 0;
     this._setStatus("connecting");
     this._ensureTransport();
@@ -1612,6 +1642,10 @@ class ExotelAIAssistController extends EventEmitter {
     var _a;
     this._clearReconnectTimer();
     (_a = this.transport) === null || _a === void 0 ? void 0 : _a.disconnect();
+    if (this.readyFired) {
+      this.readyFired = false;
+      this.emit("onReady", false);
+    }
     this._setStatus("disconnected");
   }
   setParams(patch) {
@@ -1622,6 +1656,7 @@ class ExotelAIAssistController extends EventEmitter {
     if (hashChanged) {
       this._clearReconnectTimer();
       this.connectionEstablished = false;
+      this.readyFired = false;
       this.reconnectAttempt = 0;
       // Tear down the current transport and start fresh with the new params.
       (_a = this.transport) === null || _a === void 0 ? void 0 : _a.destroy();
@@ -1662,22 +1697,23 @@ class ExotelAIAssistController extends EventEmitter {
         this._setStatus("connected");
         this.emit("onCallStart");
         break;
+      case "ACKNOWLEDGED":
+        this._fireReady();
+        break;
       case "DISCONNECTED":
         if (this.connectionEstablished) {
-          // Server ended an already-established connection (call ended, stream
-          // not found, auth failure, etc.) — do not retry.
+          if (this.readyFired) {
+            this.readyFired = false;
+            this.emit("onReady", false);
+          }
           this._setStatus("disconnected");
           this.emit("onCallEnd");
           this.destroy();
         } else {
-          // WebSocket never opened — network/DNS/refused error.
-          // Retry up to MAX_RECONNECT_ATTEMPTS then give up.
           this._scheduleReconnect();
         }
         break;
       case "ERROR":
-        // onerror fires before onclose; DISCONNECTED will arrive right after
-        // and drive the retry / destroy decision. Just surface the error here.
         this.emit("error", new Error((_a = msg.message) !== null && _a !== void 0 ? _a : "Unknown transport error"));
         break;
       case "MESSAGE":
@@ -1711,18 +1747,21 @@ class ExotelAIAssistController extends EventEmitter {
       this.reconnectTimer = null;
     }
   }
+  _fireReady() {
+    if (this.readyFired) return;
+    this.readyFired = true;
+    this.emit("onReady", true);
+  }
   _handleServerPayload(raw) {
-    var _a;
+    var _a, _b;
     let parsed;
     try {
       parsed = JSON.parse(raw);
-    } catch (_b) {
+    } catch (_c) {
       this.emit("error", new Error(`Failed to parse server message: ${raw}`));
       return;
     }
     this.emit("raw", parsed);
-    // Auth error messages arrive before the server closes the connection.
-    // Treat both as fatal — the server will follow up with a 4001/4002 close.
     const msgType = parsed.type;
     if (msgType === "auth_failed" || msgType === "auth_timeout") {
       const detail = (_a = parsed.error) !== null && _a !== void 0 ? _a : msgType;
@@ -1732,6 +1771,10 @@ class ExotelAIAssistController extends EventEmitter {
       this.emit("error", err);
       return;
     }
+    if (msgType === "ack" && !this.readyFired) {
+      (_b = this.transport) === null || _b === void 0 ? void 0 : _b.markAcknowledged();
+      this._fireReady();
+    }
     if (parsed.config) {
       this.emit("botConfig", parsed.config);
     }

package/dist/hooks/useExotelAIAssist.d.ts

@@ -1,6 +1,13 @@
 import { ExotelAIAssistParams, Suggestion, TranscriptLine, Sentiment, BotConfig, ConnectionStatus } from "../types";
 export interface UseExotelAIAssistReturn {
     status: ConnectionStatus;
+    /**
+     * `true` once the WebSocket connection is established and the server has
+     * acknowledged it.  In multi-tab scenarios where this tab joins an
+     * already-acknowledged session, it becomes `true` immediately.
+     * Resets to `false` on disconnect.
+     */
+    isReady: boolean;
     /** AI suggestions, oldest first, capped at 50. */
     suggestions: Suggestion[];
     /** Live transcript lines, ordered by start time. */

package/dist/index.js

@@ -19761,6 +19761,7 @@ class BroadcastChannelTransport {
     this.pendingUrl = null;
     this.pendingAuthToken = null;
     this.lockReleaser = null;
+    this.ackReceived = false;
     this._destroyed = false;
     const channelName = `exotel-ai-assist:${sessionHash}`;
     const lockName = `exotel-ai-assist-leader:${sessionHash}`;
@@ -19769,12 +19770,15 @@ class BroadcastChannelTransport {
       var _a;
       const data = ev.data;
       if (this.isLeader) {
-        // A new follower tab has opened. If our socket is already connected,
-        // broadcast CONNECTED so the follower can sync its status immediately.
         if (data.type === "JOIN" && this.socketConnected) {
           this.channel.postMessage({
             type: "CONNECTED"
           });
+          if (this.ackReceived) {
+            this.channel.postMessage({
+              type: "ACKNOWLEDGED"
+            });
+          }
         }
         return;
       }
@@ -19829,6 +19833,7 @@ class BroadcastChannelTransport {
       var _a;
       if (this._destroyed) return;
       this.socketConnected = true;
+      this.ackReceived = false;
       this.socket.send(JSON.stringify({
         type: "auth",
         access_token: authToken
@@ -19863,6 +19868,7 @@ class BroadcastChannelTransport {
       var _a;
       if (this._destroyed) return;
       this.socketConnected = false;
+      this.ackReceived = false;
       const msg = {
         type: "DISCONNECTED",
         code: ev.code
@@ -19895,6 +19901,9 @@ class BroadcastChannelTransport {
   onMessage(handler) {
     this.handler = handler;
   }
+  markAcknowledged() {
+    this.ackReceived = true;
+  }
   destroy() {
     var _a;
     this._destroyed = true;
@@ -20915,6 +20924,18 @@ function requireObject_hash() {
 var object_hashExports = requireObject_hash();
 var objectHash = /*@__PURE__*/getDefaultExportFromCjs(object_hashExports);
 
+var Environment;
+(function (Environment) {
+  Environment["PRODUCTION"] = "production";
+  Environment["UAT"] = "uat";
+  Environment["DEVELOPMENT"] = "development";
+})(Environment || (Environment = {}));
+const WssBaseUrl = {
+  [Environment.PRODUCTION]: "wss://ai-assist.in.exotel.com",
+  [Environment.UAT]: "wss://oneassist-uat.in.exotel.com",
+  [Environment.DEVELOPMENT]: "ws://localhost:8081"
+};
+
 class Utils {
   /**
    * Returns a deterministic SHA-1 hex digest for any plain object.
@@ -20946,10 +20967,16 @@ class Utils {
    * @param accountId - The account ID to get the base WebSocket URL for.
    * @returns The base WebSocket URL.
    */
-  static getWssBaseUrl(accountId) {
-    // return `wss://ai-assist.in.exotel.com/ai-assist/accounts/${accountId}/one-assistant-event-publisher`;
-    // return `wss://oneassist-uat.in.exotel.com/ai-assist/one-assistant-event-publisher/${accountId}`;
-    return `wss://oneassist-uat.in.exotel.com/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+  static getWssBaseUrl(accountId, env) {
+    if (env === Environment.DEVELOPMENT) {
+      return `${WssBaseUrl[Environment.DEVELOPMENT]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    } else if (env === Environment.UAT) {
+      return `${WssBaseUrl[Environment.UAT]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    } else if (env === Environment.PRODUCTION) {
+      return `${WssBaseUrl[Environment.PRODUCTION]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    } else {
+      return `${WssBaseUrl[Environment.PRODUCTION]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    }
   }
   /**
    * Builds a WebSocket URL from the given parameters.
@@ -20957,17 +20984,18 @@ class Utils {
    * @returns The WebSocket URL.
    */
   static buildWsUrl(params) {
+    var _a;
     const {
       wssBaseUrl
     } = params;
-    const resolved = wssBaseUrl !== null && wssBaseUrl !== void 0 ? wssBaseUrl : Utils.getWssBaseUrl(params.accountId);
+    const resolved = wssBaseUrl !== null && wssBaseUrl !== void 0 ? wssBaseUrl : Utils.getWssBaseUrl(params.accountId, (_a = params === null || params === void 0 ? void 0 : params.env) !== null && _a !== void 0 ? _a : Environment.PRODUCTION);
     const base = resolved.endsWith("/") ? resolved.slice(0, -1) : resolved;
     const query = Utils.constructQueryParams(params);
     return `${base}?${query}`;
   }
   static constructQueryParams(params) {
     // Keys consumed by the library — never forwarded to the server.
-    const INTERNAL_KEYS = new Set(["authToken", "accountId", "wssBaseUrl", "reconnectInterval", "maxReconnectAttempts"]);
+    const INTERNAL_KEYS = new Set(["authToken", "accountId", "wssBaseUrl", "reconnectInterval", "maxReconnectAttempts", "env"]);
     // Mandatory server params remapped to the names the API expects.
     // accountId is embedded in the URL path — never sent as a query param.
     const pairs = [];
@@ -21013,6 +21041,7 @@ class ExotelAIAssistController extends EventEmitter {
     //   connectionEstablished === false  → connection never opened → retry
     //   connectionEstablished === true   → server ended a live connection → destroy
     this.connectionEstablished = false;
+    this.readyFired = false;
     this.reconnectAttempt = 0;
     this.reconnectTimer = null;
     this.params = Object.assign({}, params);
@@ -21021,6 +21050,7 @@ class ExotelAIAssistController extends EventEmitter {
     if (this.destroyed) return;
     this._clearReconnectTimer();
     this.connectionEstablished = false;
+    this.readyFired = false;
     this.reconnectAttempt = 0;
     this._setStatus("connecting");
     this._ensureTransport();
@@ -21030,6 +21060,10 @@ class ExotelAIAssistController extends EventEmitter {
     var _a;
     this._clearReconnectTimer();
     (_a = this.transport) === null || _a === void 0 ? void 0 : _a.disconnect();
+    if (this.readyFired) {
+      this.readyFired = false;
+      this.emit("onReady", false);
+    }
     this._setStatus("disconnected");
   }
   setParams(patch) {
@@ -21040,6 +21074,7 @@ class ExotelAIAssistController extends EventEmitter {
     if (hashChanged) {
       this._clearReconnectTimer();
       this.connectionEstablished = false;
+      this.readyFired = false;
       this.reconnectAttempt = 0;
       // Tear down the current transport and start fresh with the new params.
       (_a = this.transport) === null || _a === void 0 ? void 0 : _a.destroy();
@@ -21080,22 +21115,23 @@ class ExotelAIAssistController extends EventEmitter {
         this._setStatus("connected");
         this.emit("onCallStart");
         break;
+      case "ACKNOWLEDGED":
+        this._fireReady();
+        break;
       case "DISCONNECTED":
         if (this.connectionEstablished) {
-          // Server ended an already-established connection (call ended, stream
-          // not found, auth failure, etc.) — do not retry.
+          if (this.readyFired) {
+            this.readyFired = false;
+            this.emit("onReady", false);
+          }
           this._setStatus("disconnected");
           this.emit("onCallEnd");
           this.destroy();
         } else {
-          // WebSocket never opened — network/DNS/refused error.
-          // Retry up to MAX_RECONNECT_ATTEMPTS then give up.
           this._scheduleReconnect();
         }
         break;
       case "ERROR":
-        // onerror fires before onclose; DISCONNECTED will arrive right after
-        // and drive the retry / destroy decision. Just surface the error here.
         this.emit("error", new Error((_a = msg.message) !== null && _a !== void 0 ? _a : "Unknown transport error"));
         break;
       case "MESSAGE":
@@ -21129,18 +21165,21 @@ class ExotelAIAssistController extends EventEmitter {
       this.reconnectTimer = null;
     }
   }
+  _fireReady() {
+    if (this.readyFired) return;
+    this.readyFired = true;
+    this.emit("onReady", true);
+  }
   _handleServerPayload(raw) {
-    var _a;
+    var _a, _b;
     let parsed;
     try {
       parsed = JSON.parse(raw);
-    } catch (_b) {
+    } catch (_c) {
       this.emit("error", new Error(`Failed to parse server message: ${raw}`));
       return;
     }
     this.emit("raw", parsed);
-    // Auth error messages arrive before the server closes the connection.
-    // Treat both as fatal — the server will follow up with a 4001/4002 close.
     const msgType = parsed.type;
     if (msgType === "auth_failed" || msgType === "auth_timeout") {
       const detail = (_a = parsed.error) !== null && _a !== void 0 ? _a : msgType;
@@ -21150,6 +21189,10 @@ class ExotelAIAssistController extends EventEmitter {
       this.emit("error", err);
       return;
     }
+    if (msgType === "ack" && !this.readyFired) {
+      (_b = this.transport) === null || _b === void 0 ? void 0 : _b.markAcknowledged();
+      this._fireReady();
+    }
     if (parsed.config) {
       this.emit("botConfig", parsed.config);
     }
@@ -21203,6 +21246,7 @@ ExotelAIAssistController.RECONNECT_BASE_MS = 3000;
 function useExotelAIAssist(params) {
   const controllerRef = reactExports.useRef(null);
   const [status, setStatus] = reactExports.useState("idle");
+  const [isReady, setIsReady] = reactExports.useState(false);
   const [suggestions, setSuggestions] = reactExports.useState([]);
   const [transcripts, setTranscripts] = reactExports.useState([]);
   const [sentiment, setSentiment] = reactExports.useState(null);
@@ -21210,8 +21254,8 @@ function useExotelAIAssist(params) {
   const [lastError, setLastError] = reactExports.useState(null);
   const paramHash = Utils.hash(params);
   reactExports.useEffect(() => {
-    // Clear all stale state from the previous session before connecting.
     setStatus("idle");
+    setIsReady(false);
     setSuggestions([]);
     setTranscripts([]);
     setSentiment(null);
@@ -21220,6 +21264,7 @@ function useExotelAIAssist(params) {
     const ctrl = new ExotelAIAssistController(params);
     controllerRef.current = ctrl;
     ctrl.on("statusChange", setStatus);
+    ctrl.on("onReady", setIsReady);
     ctrl.on("botConfig", setBotConfig);
     ctrl.on("suggestion", s => setSuggestions(prev => [...prev, s].slice(-50)));
     ctrl.on("sentiment", setSentiment);
@@ -21250,6 +21295,7 @@ function useExotelAIAssist(params) {
   }, []);
   return {
     status,
+    isReady,
     suggestions,
     transcripts,
     sentiment,
@@ -21800,16 +21846,24 @@ function TranscriptTab({
 
 function ExotelAIAssist(_a) {
   var {
-      className
+      className,
+      onReady
     } = _a,
-    params = __rest(_a, ["className"]);
+    params = __rest(_a, ["className", "onReady"]);
   const {
     status,
+    isReady,
     suggestions,
     transcripts,
     sentiment,
     botConfig
   } = useExotelAIAssist(params);
+  const onReadyRef = reactExports.useRef(onReady);
+  onReadyRef.current = onReady;
+  reactExports.useEffect(() => {
+    var _a;
+    (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef, isReady);
+  }, [isReady]);
   const connected = status === "connected";
   return jsxRuntimeExports.jsx(Provider, {
     children: jsxRuntimeExports.jsx("div", {

package/dist/react/index.js

@@ -5047,6 +5047,7 @@ class BroadcastChannelTransport {
     this.pendingUrl = null;
     this.pendingAuthToken = null;
     this.lockReleaser = null;
+    this.ackReceived = false;
     this._destroyed = false;
     const channelName = `exotel-ai-assist:${sessionHash}`;
     const lockName = `exotel-ai-assist-leader:${sessionHash}`;
@@ -5055,12 +5056,15 @@ class BroadcastChannelTransport {
       var _a;
       const data = ev.data;
       if (this.isLeader) {
-        // A new follower tab has opened. If our socket is already connected,
-        // broadcast CONNECTED so the follower can sync its status immediately.
         if (data.type === "JOIN" && this.socketConnected) {
           this.channel.postMessage({
             type: "CONNECTED"
           });
+          if (this.ackReceived) {
+            this.channel.postMessage({
+              type: "ACKNOWLEDGED"
+            });
+          }
         }
         return;
       }
@@ -5115,6 +5119,7 @@ class BroadcastChannelTransport {
       var _a;
       if (this._destroyed) return;
       this.socketConnected = true;
+      this.ackReceived = false;
       this.socket.send(JSON.stringify({
         type: "auth",
         access_token: authToken
@@ -5149,6 +5154,7 @@ class BroadcastChannelTransport {
       var _a;
       if (this._destroyed) return;
       this.socketConnected = false;
+      this.ackReceived = false;
       const msg = {
         type: "DISCONNECTED",
         code: ev.code
@@ -5181,6 +5187,9 @@ class BroadcastChannelTransport {
   onMessage(handler) {
     this.handler = handler;
   }
+  markAcknowledged() {
+    this.ackReceived = true;
+  }
   destroy() {
     var _a;
     this._destroyed = true;
@@ -6201,6 +6210,18 @@ function requireObject_hash() {
 var object_hashExports = requireObject_hash();
 var objectHash = /*@__PURE__*/getDefaultExportFromCjs(object_hashExports);
 
+var Environment;
+(function (Environment) {
+  Environment["PRODUCTION"] = "production";
+  Environment["UAT"] = "uat";
+  Environment["DEVELOPMENT"] = "development";
+})(Environment || (Environment = {}));
+const WssBaseUrl = {
+  [Environment.PRODUCTION]: "wss://ai-assist.in.exotel.com",
+  [Environment.UAT]: "wss://oneassist-uat.in.exotel.com",
+  [Environment.DEVELOPMENT]: "ws://localhost:8081"
+};
+
 class Utils {
   /**
    * Returns a deterministic SHA-1 hex digest for any plain object.
@@ -6232,10 +6253,16 @@ class Utils {
    * @param accountId - The account ID to get the base WebSocket URL for.
    * @returns The base WebSocket URL.
    */
-  static getWssBaseUrl(accountId) {
-    // return `wss://ai-assist.in.exotel.com/ai-assist/accounts/${accountId}/one-assistant-event-publisher`;
-    // return `wss://oneassist-uat.in.exotel.com/ai-assist/one-assistant-event-publisher/${accountId}`;
-    return `wss://oneassist-uat.in.exotel.com/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+  static getWssBaseUrl(accountId, env) {
+    if (env === Environment.DEVELOPMENT) {
+      return `${WssBaseUrl[Environment.DEVELOPMENT]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    } else if (env === Environment.UAT) {
+      return `${WssBaseUrl[Environment.UAT]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    } else if (env === Environment.PRODUCTION) {
+      return `${WssBaseUrl[Environment.PRODUCTION]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    } else {
+      return `${WssBaseUrl[Environment.PRODUCTION]}/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    }
   }
   /**
    * Builds a WebSocket URL from the given parameters.
@@ -6243,17 +6270,18 @@ class Utils {
    * @returns The WebSocket URL.
    */
   static buildWsUrl(params) {
+    var _a;
     const {
       wssBaseUrl
     } = params;
-    const resolved = wssBaseUrl !== null && wssBaseUrl !== void 0 ? wssBaseUrl : Utils.getWssBaseUrl(params.accountId);
+    const resolved = wssBaseUrl !== null && wssBaseUrl !== void 0 ? wssBaseUrl : Utils.getWssBaseUrl(params.accountId, (_a = params === null || params === void 0 ? void 0 : params.env) !== null && _a !== void 0 ? _a : Environment.PRODUCTION);
     const base = resolved.endsWith("/") ? resolved.slice(0, -1) : resolved;
     const query = Utils.constructQueryParams(params);
     return `${base}?${query}`;
   }
   static constructQueryParams(params) {
     // Keys consumed by the library — never forwarded to the server.
-    const INTERNAL_KEYS = new Set(["authToken", "accountId", "wssBaseUrl", "reconnectInterval", "maxReconnectAttempts"]);
+    const INTERNAL_KEYS = new Set(["authToken", "accountId", "wssBaseUrl", "reconnectInterval", "maxReconnectAttempts", "env"]);
     // Mandatory server params remapped to the names the API expects.
     // accountId is embedded in the URL path — never sent as a query param.
     const pairs = [];
@@ -6299,6 +6327,7 @@ class ExotelAIAssistController extends EventEmitter {
     //   connectionEstablished === false  → connection never opened → retry
     //   connectionEstablished === true   → server ended a live connection → destroy
     this.connectionEstablished = false;
+    this.readyFired = false;
     this.reconnectAttempt = 0;
     this.reconnectTimer = null;
     this.params = Object.assign({}, params);
@@ -6307,6 +6336,7 @@ class ExotelAIAssistController extends EventEmitter {
     if (this.destroyed) return;
     this._clearReconnectTimer();
     this.connectionEstablished = false;
+    this.readyFired = false;
     this.reconnectAttempt = 0;
     this._setStatus("connecting");
     this._ensureTransport();
@@ -6316,6 +6346,10 @@ class ExotelAIAssistController extends EventEmitter {
     var _a;
     this._clearReconnectTimer();
     (_a = this.transport) === null || _a === void 0 ? void 0 : _a.disconnect();
+    if (this.readyFired) {
+      this.readyFired = false;
+      this.emit("onReady", false);
+    }
     this._setStatus("disconnected");
   }
   setParams(patch) {
@@ -6326,6 +6360,7 @@ class ExotelAIAssistController extends EventEmitter {
     if (hashChanged) {
       this._clearReconnectTimer();
       this.connectionEstablished = false;
+      this.readyFired = false;
       this.reconnectAttempt = 0;
       // Tear down the current transport and start fresh with the new params.
       (_a = this.transport) === null || _a === void 0 ? void 0 : _a.destroy();
@@ -6366,22 +6401,23 @@ class ExotelAIAssistController extends EventEmitter {
         this._setStatus("connected");
         this.emit("onCallStart");
         break;
+      case "ACKNOWLEDGED":
+        this._fireReady();
+        break;
       case "DISCONNECTED":
         if (this.connectionEstablished) {
-          // Server ended an already-established connection (call ended, stream
-          // not found, auth failure, etc.) — do not retry.
+          if (this.readyFired) {
+            this.readyFired = false;
+            this.emit("onReady", false);
+          }
           this._setStatus("disconnected");
           this.emit("onCallEnd");
           this.destroy();
         } else {
-          // WebSocket never opened — network/DNS/refused error.
-          // Retry up to MAX_RECONNECT_ATTEMPTS then give up.
           this._scheduleReconnect();
         }
         break;
       case "ERROR":
-        // onerror fires before onclose; DISCONNECTED will arrive right after
-        // and drive the retry / destroy decision. Just surface the error here.
         this.emit("error", new Error((_a = msg.message) !== null && _a !== void 0 ? _a : "Unknown transport error"));
         break;
       case "MESSAGE":
@@ -6415,18 +6451,21 @@ class ExotelAIAssistController extends EventEmitter {
       this.reconnectTimer = null;
     }
   }
+  _fireReady() {
+    if (this.readyFired) return;
+    this.readyFired = true;
+    this.emit("onReady", true);
+  }
   _handleServerPayload(raw) {
-    var _a;
+    var _a, _b;
     let parsed;
     try {
       parsed = JSON.parse(raw);
-    } catch (_b) {
+    } catch (_c) {
       this.emit("error", new Error(`Failed to parse server message: ${raw}`));
       return;
     }
     this.emit("raw", parsed);
-    // Auth error messages arrive before the server closes the connection.
-    // Treat both as fatal — the server will follow up with a 4001/4002 close.
     const msgType = parsed.type;
     if (msgType === "auth_failed" || msgType === "auth_timeout") {
       const detail = (_a = parsed.error) !== null && _a !== void 0 ? _a : msgType;
@@ -6436,6 +6475,10 @@ class ExotelAIAssistController extends EventEmitter {
       this.emit("error", err);
       return;
     }
+    if (msgType === "ack" && !this.readyFired) {
+      (_b = this.transport) === null || _b === void 0 ? void 0 : _b.markAcknowledged();
+      this._fireReady();
+    }
     if (parsed.config) {
       this.emit("botConfig", parsed.config);
     }
@@ -6489,6 +6532,7 @@ ExotelAIAssistController.RECONNECT_BASE_MS = 3000;
 function useExotelAIAssist(params) {
   const controllerRef = React.useRef(null);
   const [status, setStatus] = React.useState("idle");
+  const [isReady, setIsReady] = React.useState(false);
   const [suggestions, setSuggestions] = React.useState([]);
   const [transcripts, setTranscripts] = React.useState([]);
   const [sentiment, setSentiment] = React.useState(null);
@@ -6496,8 +6540,8 @@ function useExotelAIAssist(params) {
   const [lastError, setLastError] = React.useState(null);
   const paramHash = Utils.hash(params);
   React.useEffect(() => {
-    // Clear all stale state from the previous session before connecting.
     setStatus("idle");
+    setIsReady(false);
     setSuggestions([]);
     setTranscripts([]);
     setSentiment(null);
@@ -6506,6 +6550,7 @@ function useExotelAIAssist(params) {
     const ctrl = new ExotelAIAssistController(params);
     controllerRef.current = ctrl;
     ctrl.on("statusChange", setStatus);
+    ctrl.on("onReady", setIsReady);
     ctrl.on("botConfig", setBotConfig);
     ctrl.on("suggestion", s => setSuggestions(prev => [...prev, s].slice(-50)));
     ctrl.on("sentiment", setSentiment);
@@ -6536,6 +6581,7 @@ function useExotelAIAssist(params) {
   }, []);
   return {
     status,
+    isReady,
     suggestions,
     transcripts,
     sentiment,
@@ -7086,16 +7132,24 @@ function TranscriptTab({
 
 function ExotelAIAssist(_a) {
   var {
-      className
+      className,
+      onReady
     } = _a,
-    params = __rest(_a, ["className"]);
+    params = __rest(_a, ["className", "onReady"]);
   const {
     status,
+    isReady,
     suggestions,
     transcripts,
     sentiment,
     botConfig
   } = useExotelAIAssist(params);
+  const onReadyRef = React.useRef(onReady);
+  onReadyRef.current = onReady;
+  React.useEffect(() => {
+    var _a;
+    (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef, isReady);
+  }, [isReady]);
   const connected = status === "connected";
   return jsxRuntime.jsx(Provider, {
     children: jsxRuntime.jsx("div", {

package/dist/transport/index.d.ts

@@ -5,6 +5,9 @@ export interface ITransport {
     disconnect(): void;
     send(payload: string): void;
     onMessage(handler: TransportMessageHandler): void;
+    /** Signal that the server ack has been received. The leader stores this so
+     *  follower tabs joining later get an immediate ACKNOWLEDGED broadcast. */
+    markAcknowledged(): void;
     destroy(): void;
 }
 export declare class BroadcastChannelTransport implements ITransport {
@@ -16,6 +19,7 @@ export declare class BroadcastChannelTransport implements ITransport {
     private pendingUrl;
     private pendingAuthToken;
     private lockReleaser;
+    private ackReceived;
     private _destroyed;
     /**
      * @param sessionHash - A hash of all connection-relevant params (see
@@ -30,6 +34,7 @@ export declare class BroadcastChannelTransport implements ITransport {
     disconnect(): void;
     send(payload: string): void;
     onMessage(handler: TransportMessageHandler): void;
+    markAcknowledged(): void;
     destroy(): void;
 }
 export declare function createTransport(sessionHash: string): ITransport;

package/dist/types/index.d.ts

@@ -1,3 +1,9 @@
+export declare enum Environment {
+    PRODUCTION = "production",
+    UAT = "uat",
+    DEVELOPMENT = "development"
+}
+export declare const WssBaseUrl: Record<Environment, string>;
 export interface ExotelAIAssistParams {
     authToken: string;
     call_sid: string;
@@ -7,6 +13,7 @@ export interface ExotelAIAssistParams {
     wssBaseUrl?: string;
     reconnectInterval?: number;
     maxReconnectAttempts?: number;
+    env?: Environment;
     [key: string]: unknown;
 }
 /** A single AI-generated suggestion for the agent. */
@@ -69,6 +76,14 @@ export interface ControllerEvents {
     sentiment: (data: Sentiment) => void;
     /** Internal: bot feature-flag config. Consumed by the UI component only. */
     botConfig: (config: BotConfig) => void;
+    /**
+     * Fires with `true` once the WebSocket connection is established AND the
+     * server has acknowledged it (first successful server message after auth).
+     * In multi-tab scenarios where a follower tab joins an already-acknowledged
+     * connection, this fires immediately with `true`.
+     * Fires with `false` on disconnect.
+     */
+    onReady: (ready: boolean) => void;
     onCallStart: () => void;
     onCallEnd: () => void;
     statusChange: (status: ConnectionStatus) => void;
@@ -80,6 +95,8 @@ export type WorkerInboundMessage = {
     payload: string;
 } | {
     type: "CONNECTED";
+} | {
+    type: "ACKNOWLEDGED";
 } | {
     type: "DISCONNECTED";
     code?: number;

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { ExotelAIAssistParams } from "../types";
+import { Environment, ExotelAIAssistParams } from "../types";
 export declare class Utils {
     static MAX_EXTRA_QUERY_PARAMS: number;
     /**
@@ -20,7 +20,7 @@ export declare class Utils {
      * @param accountId - The account ID to get the base WebSocket URL for.
      * @returns The base WebSocket URL.
      */
-    static getWssBaseUrl(accountId: string): string;
+    static getWssBaseUrl(accountId: string, env: Environment): string;
     /**
      * Builds a WebSocket URL from the given parameters.
      * @param params - The parameters to build the WebSocket URL from.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exotel-npm-dev/exotel-ai-assist",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "AI-powered real-time suggestions, transcript, and sentiment for agent calls",
   "license": "Apache-2.0",
   "main": "dist/index.js",