@voice-ai-labs/web-sdk 1.0.0 → 1.0.2

package/README.md

@@ -61,6 +61,7 @@ await voiceai.connect({ agentId: 'agent-123', testMode: true });
 
 - `agentId` for a saved agent
 - `dynamicVariables` for optional runtime variables passed at call start
+- `agentOverrides` for optional call-scoped runtime config overrides
 - `testMode` to preview paused agents before deploying
 
 ### Events
@@ -276,7 +277,14 @@ await voiceai.agents.disable(agent.agent_id);
 await voiceai.agents.createOutboundCall({
   agent_id: agent.agent_id,
   target_phone_number: '+15551234567',
-  dynamic_variables: { case_id: 'abc-1' }
+  dynamic_variables: { case_id: 'abc-1' },
+  agent_overrides: {
+    tts_params: {
+      voice_id: 'voice_priority_customer',
+      dictionary_id: 'dict-123',
+      dictionary_version: 2,
+    },
+  },
 });
 ```
 
@@ -294,6 +302,8 @@ Today the SDK includes one Google entry:
 
 Use the managed Google surface to connect an agent to Google Calendar, Sheets, or Gmail.
 
+For a working browser example, see [`demo/managed-tools.html`](https://github.com/voice-ai/web-sdk/blob/main/demo/managed-tools.html).
+
 ```typescript
 import VoiceAI, {
   GOOGLE_CALENDAR_OPERATION_OPTIONS,
@@ -331,7 +341,7 @@ const reconnect = getGoogleReconnectState(
 
 Connection flow:
 
-1. Call `startOAuth(...)` with the agent ID, `returnUrl`, and the individual Google managed tool configs you want enabled.
+1. Call `startOAuth(...)` with the agent ID, `returnUrl`, and the currently enabled Google managed tool config for the agent.
 2. Open the returned `auth_url` in a popup or browser tab.
 3. Google redirects to the VoiceAI backend callback.
 4. The backend completes OAuth and then returns the user to your `returnUrl`.
@@ -340,9 +350,9 @@ Connection flow:
 Connection semantics:
 
 - `startOAuth(...)` manages Google managed-tools access for the agent
-- `managedTools.google_calendar`, `managedTools.google_sheets`, and `managedTools.google_gmail` decide which Google capabilities should be available
-- enabling more Google operations later can require reconnecting to grant additional access
-- `disconnect(...)` removes Google managed-tools access for that agent
+- the Google connection is shared across Calendar, Sheets, and Gmail for that agent
+- enabling more Google operations later can require reconnecting to grant access for the currently enabled Google tools
+- `disconnect(...)` removes Google managed-tools access for all Google tools on that agent
 
 Available helpers:
 
@@ -393,7 +403,8 @@ Supported Gmail operations:
 Notes:
 
 - Google Calendar, Sheets, and Gmail all use the `voiceai.managedTools.google` surface.
-- If you enable additional Google operations later, `getStatus()` / `getGoogleReconnectState(...)` may report `reconnect_required` until you reconnect and grant the additional access.
+- `startOAuth(...)` uses the Google managed tool config you pass in `managedTools` to determine the scopes requested for the shared agent-level Google connection.
+- If you enable additional Google operations later, `getStatus()` / `getGoogleReconnectState(...)` may report `reconnect_required` until you reconnect and grant access for the currently enabled Google tools.
 - `voiceai.managedTools.google.disconnect(agentId)` removes Google managed-tools access for the agent.
 - `returnUrl` is your app/frontend return target after the VoiceAI backend callback completes. It is not the Google-registered OAuth redirect URI.
 - Calendar `timezone` should be an IANA timezone like `America/Los_Angeles`
@@ -433,6 +444,32 @@ await voiceai.connect({
 - Variables that are not referenced by the runtime prompt are ignored.
 - The runtime is responsible for interpolating these variables into the prompt.
 
+### Runtime Agent Overrides
+
+Pass optional `agentOverrides` at call start when you need a call-scoped config patch rather than prompt interpolation:
+
+```typescript
+await voiceai.connect({
+  agentId: agent.agent_id,
+  dynamicVariables: {
+    customer_name: 'Alice',
+  },
+  agentOverrides: {
+    tts_params: {
+      voice_id: 'voice_vip_alice',
+      model: 'voiceai-tts-v1-latest',
+      language: 'en',
+    },
+  },
+});
+```
+
+- `agentOverrides` is separate from `dynamicVariables`.
+- `dynamicVariables` is for prompt and greeting interpolation.
+- `agentOverrides` is for allowlisted runtime config changes.
+- v1 supports only `tts_params.voice_id`, `model`, `language`, `temperature`, `top_p`, `dictionary_id`, and `dictionary_version`.
+- `agentOverrides` uses the same nested shape as agent config, so voice overrides live under `tts_params`.
+
 ## Knowledge Base
 
 ```typescript
@@ -729,6 +766,17 @@ Your endpoint should respond with:
 ```typescript
 interface InboundCallWebhookResponse {
   dynamic_variables?: Record<string, string | number | boolean>;
+  agent_overrides?: {
+    tts_params?: {
+      voice_id?: string;
+      model?: string;
+      language?: string;
+      temperature?: number;
+      top_p?: number;
+      dictionary_id?: string;
+      dictionary_version?: number;
+    };
+  };
 }
 ```
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAEV,iBAAiB,EACjB,iBAAiB,EAEjB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EAEnB,cAAc,EAEd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACd,MAAM,SAAS,CAAC;AAKjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,OAAO;IAKlB,uEAAuE;IACvE,IAAW,MAAM,IAAI,WAAW,CAG/B;IACD,OAAO,CAAC,OAAO,CAAC,CAAc;IAE9B,oDAAoD;IACpD,IAAW,SAAS,IAAI,eAAe,CAGtC;IACD,OAAO,CAAC,UAAU,CAAC,CAAkB;IAErC,6CAA6C;IAC7C,IAAW,aAAa,IAAI,mBAAmB,CAG9C;IACD,OAAO,CAAC,cAAc,CAAC,CAAsB;IAE7C,6DAA6D;IAC7D,IAAW,YAAY,IAAI,iBAAiB,CAG3C;IACD,OAAO,CAAC,aAAa,CAAC,CAAoB;IAE1C,qEAAqE;IACrE,IAAW,GAAG,IAAI,SAAS,CAG1B;IACD,OAAO,CAAC,IAAI,CAAC,CAAY;IAEzB,yEAAyE;IACzE,IAAW,YAAY,IAAI,kBAAkB,CAG5C;IACD,OAAO,CAAC,aAAa,CAAC,CAAqB;IAM3C,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,gBAAgB,CAA6D;IACrF,OAAO,CAAC,qBAAqB,CAAwC;IACrE,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,kBAAkB,CAAqC;IAC/D,OAAO,CAAC,kBAAkB,CAAqC;IAC/D,OAAO,CAAC,uBAAuB,CAA0C;IACzE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAC,CAAoB;IACzC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,uBAAuB,CAAkC;IACjE,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,kBAAkB,CAAuB;IAEjD;;;;;;OAMG;gBACS,MAAM,GAAE,aAAkB;IA2BtC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIlF;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,CACf,iBAAiB,EAAE,iBAAiB,EACpC,OAAO,GAAE,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,GAAG,cAAc,GAAG,kBAAkB,CAAM,GAC5F,OAAO,CAAC,IAAI,CAAC;IAgDhB;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDxD;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CjC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAI7B;;OAEG;IACH,aAAa,IAAI,cAAc;IAO/B;;OAEG;IACH,kBAAkB,IAAI,eAAe;IAWrC;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9C;;OAEG;IACG,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB3D;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK1D;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAK5D;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI;IAK1C;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAM1D;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAKpD;;;OAGG;IACH,uBAAuB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAgBpE,OAAO,CAAC,cAAc;YAYR,6BAA6B;IAgC3C;;;OAGG;IACH;;;OAGG;YACW,sBAAsB;YAOtB,gBAAgB;YAchB,6BAA6B;YAyD7B,UAAU;IAaxB,OAAO,CAAC,kBAAkB;IAiH1B,OAAO,CAAC,sBAAsB;IAmB9B,OAAO,CAAC,yBAAyB;IAsDjC,OAAO,CAAC,wBAAwB;IAkBhC,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,mBAAmB;CAG5B;AAMD,yCAAyC;AACzC,eAAe,OAAO,CAAC;AAEvB,iCAAiC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAS7C,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,EACV,cAAc,EACd,cAAc,EACd,eAAe,EACf,KAAK,EACL,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,gCAAgC,EAChC,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,aAAa,EACb,WAAW,EACX,eAAe,GAChB,MAAM,SAAS,CAAC;AAMjB;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAmBvG;AAED,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,iCAAiC,EACjC,+BAA+B,EAC/B,8BAA8B,EAC9B,gCAAgC,EAChC,qBAAqB,EACrB,gCAAgC,EAChC,0BAA0B,EAC1B,uBAAuB,EACvB,sBAAsB,EACtB,qCAAqC,EACrC,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,YAAY,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAEV,iBAAiB,EACjB,iBAAiB,EAEjB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EAEnB,cAAc,EAEd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACd,MAAM,SAAS,CAAC;AAKjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,OAAO;IAKlB,uEAAuE;IACvE,IAAW,MAAM,IAAI,WAAW,CAG/B;IACD,OAAO,CAAC,OAAO,CAAC,CAAc;IAE9B,oDAAoD;IACpD,IAAW,SAAS,IAAI,eAAe,CAGtC;IACD,OAAO,CAAC,UAAU,CAAC,CAAkB;IAErC,6CAA6C;IAC7C,IAAW,aAAa,IAAI,mBAAmB,CAG9C;IACD,OAAO,CAAC,cAAc,CAAC,CAAsB;IAE7C,6DAA6D;IAC7D,IAAW,YAAY,IAAI,iBAAiB,CAG3C;IACD,OAAO,CAAC,aAAa,CAAC,CAAoB;IAE1C,qEAAqE;IACrE,IAAW,GAAG,IAAI,SAAS,CAG1B;IACD,OAAO,CAAC,IAAI,CAAC,CAAY;IAEzB,yEAAyE;IACzE,IAAW,YAAY,IAAI,kBAAkB,CAG5C;IACD,OAAO,CAAC,aAAa,CAAC,CAAqB;IAM3C,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,gBAAgB,CAA6D;IACrF,OAAO,CAAC,qBAAqB,CAAwC;IACrE,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,kBAAkB,CAAqC;IAC/D,OAAO,CAAC,kBAAkB,CAAqC;IAC/D,OAAO,CAAC,uBAAuB,CAA0C;IACzE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAC,CAAoB;IACzC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,uBAAuB,CAAkC;IACjE,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,kBAAkB,CAAuB;IAEjD;;;;;;OAMG;gBACS,MAAM,GAAE,aAAkB;IA2BtC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIlF;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,CACf,iBAAiB,EAAE,iBAAiB,EACpC,OAAO,GAAE,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,GAAG,cAAc,GAAG,kBAAkB,CAAM,GAC5F,OAAO,CAAC,IAAI,CAAC;IAgDhB;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDxD;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CjC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAI7B;;OAEG;IACH,aAAa,IAAI,cAAc;IAO/B;;OAEG;IACH,kBAAkB,IAAI,eAAe;IAWrC;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9C;;OAEG;IACG,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB3D;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK1D;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAK5D;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI;IAK1C;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAM1D;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAKpD;;;OAGG;IACH,uBAAuB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAgBpE,OAAO,CAAC,cAAc;YAYR,6BAA6B;IAgC3C;;;OAGG;IACH;;;OAGG;YACW,sBAAsB;YAOtB,gBAAgB;YAchB,6BAA6B;YA4D7B,UAAU;IAaxB,OAAO,CAAC,kBAAkB;IAiH1B,OAAO,CAAC,sBAAsB;IAmB9B,OAAO,CAAC,yBAAyB;IAsDjC,OAAO,CAAC,wBAAwB;IAkBhC,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,mBAAmB;CAG5B;AAMD,yCAAyC;AACzC,eAAe,OAAO,CAAC;AAEvB,iCAAiC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAS7C,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,EACV,cAAc,EACd,cAAc,EACd,eAAe,EACf,KAAK,EACL,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,gCAAgC,EAChC,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,aAAa,EACb,WAAW,EACX,eAAe,GAChB,MAAM,SAAS,CAAC;AAMjB;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAmBvG;AAED,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,iCAAiC,EACjC,+BAA+B,EAC/B,8BAA8B,EAC9B,gCAAgC,EAChC,qBAAqB,EACrB,gCAAgC,EAChC,0BAA0B,EAC1B,uBAAuB,EACvB,sBAAsB,EACtB,qCAAqC,EACrC,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,YAAY,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/index.esm.js

@@ -30101,6 +30101,9 @@ class VoiceAI {
         if (options.dynamicVariables) {
             requestData.dynamic_variables = options.dynamicVariables;
         }
+        if (options.agentOverrides) {
+            requestData.agent_overrides = options.agentOverrides;
+        }
         const authToken = await this.resolveAuthToken(options);
         this.effectiveApiKey = authToken;
         const response = await fetch(endpoint, {