API Reference - Strada Voice API

Strada’s Web SDK consists of a global stradaChat object that you must add to your site to use any Web SDK functionality, along with corresponding settings and actions.

Settings

Configure the Web SDK by creating a stradaSettings object in the global window scope.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id'
    // ... other settings
  };
</script>
<!-- Define the web SDK script afterwards -->
<script src="https://sdk.getstrada.com/web-sdk/latest/strada-chat.js"></script>

Alternatively, you can pass settings to the stradaChat.start method. (See Delay widget loading.)

The Web SDK requires that window.stradaSettings be defined before the script loads. You must therefore define window.stradaSettings before the script, or use the lazy option and call start() manually.

Available configuration options:

organizationId

organizationId: string; (required) Your Strada organization ID. You can find this in the Strada dashboard.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id'
  };
</script>

agentId

agentId: string; (required) The ID of the agent to load in the chat widget. You can find this in the Strada dashboard.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id'
  };
</script>

agentVariables

agentVariables?: Record<string, unknown>; Pass data that you want to make available to your agent through agentVariables. This data can be accessible to the AI agent or be used in your actions.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    agentVariables: {
      first_name: 'John',
      last_name: 'Doe',
      email: 'john@example.com'
    }
  };
</script>

metadata

metadata?: Record<string, unknown>; Use metadata to pass information about a user to Strada for attribution and analytics purposes. This data is not accessible to the AI agent during conversations. For passing data that should be available in chat conversations, use agentVariables instead.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    metadata: {
      userId: '12345',
      accountType: 'premium',
      signupDate: '2024-01-15'
    }
  };
</script>

To change these values dynamically, pass them to open() (see open action).

Meta field keys should not include whitespace, emojis, or special characters.

secureMetadata

secureMetadata?: Record<string, unknown>; Use secureMetadata to pass sensitive data that requires an extra layer of protection. The values of secure metadata are never revealed in the UI, but they are still accessible through actions.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    secureMetadata: {
      internalUserId: 'usr_12345',
      authToken: 'sensitive-token-value'
    }
  };
</script>

Use secure metadata for sensitive identifiers, tokens, or confidential information that your actions need but should not be visible in the dashboard.

stradaReadyCallback

stradaReadyCallback?(params: { isLoaded: boolean }): void; Callback invoked when the SDK completes initialization. Useful for asynchronous widget loading scenarios.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    stradaReadyCallback: ({ isLoaded }) => {
      console.log('Strada widget is ready. Chat support is now available.');
    }
  };
</script>

toggleCallback

toggleCallback?(isOpen: boolean): void; Callback triggered whenever the widget opens or closes.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    toggleCallback: (isOpen) => {
      console.log('Chat is now', isOpen ? 'open' : 'closed');
    }
  };
</script>

lazy

lazy?: boolean; When set to true, this will prevent the widget from loading until the stradaChat.start(...) method is called. (See Delay widget loading.)

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    lazy: true
  };
</script>

hideButton

hideButton?: boolean; Hides the default floating button when set to true, allowing you to trigger the widget through custom UI elements.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    hideButton: true
  };
</script>

parentElement

parentElement?: string; CSS selector for a custom DOM element to mount the widget into (e.g. '#my-container' or '.widget-container'). If not provided, the widget mounts to document.body with fixed positioning (floating on desktop, full-screen on mobile). Use this when you want the chat embedded in a specific part of your layout (e.g. a sidebar or dedicated panel) instead of the default bottom-right overlay. The widget will fill the parent element. Typically used together with hideButton: true and your own trigger (e.g. a tab or button) that calls stradaChat.open(). Requirements:

The target element must exist in the DOM when the SDK initializes.
The container should have position: relative and padding: 0, margin: 0 so the widget can fill it correctly.
Use a string selector only (e.g. '#id', '.class'). HTMLElement references are not supported.

If the selector does not match any element, the SDK falls back to document.body and logs a console warning.

<div id="chat-panel" style="position: relative; width: 100%; height: 500px; padding: 0; margin: 0;"></div>

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    parentElement: '#chat-panel',
    hideButton: true
  };
</script>
<script src="https://sdk.getstrada.com/web-sdk/latest/strada-chat.js"></script>

// Open the widget when user clicks your UI
document.getElementById('open-chat').addEventListener('click', () => {
  window.stradaChat.open();
});

Single Page Applications: The widget mounts once on initial page load. If your application uses client-side routing (React Router, Vue Router, etc.), keep the widget in a layout container that persists across route changes. The parentElement cannot be changed dynamically after the widget initializes.

darkMode

darkMode?: boolean; Enables dark mode theme for the widget. Defaults to false.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    darkMode: true
  };
</script>

To toggle dark mode dynamically after initialization, use the setDarkMode action.

widgetUrl

widgetUrl?: string; Specifies a custom widget URL. Unless directed by a Strada team member, you should not change this value.

getUserToken

getUserToken?(): Promise<string | null>; Function that retrieves a JWT token from your backend for user authentication. Returns a token to establish a verified user identity for the chat session.

<script>
  window.stradaSettings = {
    organizationId: 'your-org-id',
    agentId: 'your-agent-id',
    getUserToken: async () => {
      // Make a request to your API to get a fresh JWT token
      const response = await fetch('/api/strada-token');
      const { token } = await response.json();
      return token;
    }
  };
</script>

The getUserToken function should return a Promise that resolves to a JWT token string, or null if authentication should be skipped.

Actions

All actions are called through the global stradaChat object.

start

start(settings: StradaSettings): Promise<void>; Initializes the SDK. Automatically called on load unless lazy mode is enabled, in which case you must call this method manually.

window.stradaChat.start({
  organizationId: 'your-org-id',
  agentId: 'your-agent-id',
  metadata: {
    userId: '12345',
    accountType: 'premium'
  }
});

open

open(options?: { agentId?: string; agentVariables?: Record<string, unknown>; metadata?: Record<string, unknown>; secureMetadata?: Record<string, unknown> }): Promise<void>;

Opens the widget. You can optionally pass context to switch agents or update variables. Field-Level REPLACE Semantics:

Each field you provide REPLACES that entire field (no merging)
Fields you omit keep their current value
Pass {} to clear a field

// Open with current context (no changes)
window.stradaChat.open();

// Switch agents (keeps current variables/metadata)
window.stradaChat.open({ agentId: 'sales-agent-id' });

// Update variables (REPLACES all variables)
window.stradaChat.open({
  agentVariables: {
    userId: '123',
    screenName: 'checkout',
    cartTotal: 99.99
  }
});

// Switch agents AND update variables
window.stradaChat.open({
  agentId: 'sales-agent-id',
  agentVariables: {
    userId: '123',
    intent: 'upgrade'
  }
});

// Clear variables (empty object = fresh start)
window.stradaChat.open({
  agentVariables: {}
});

// Update multiple fields at once
window.stradaChat.open({
  agentVariables: { userId: '123', page: 'billing' },
  metadata: { tier: 'premium', source: 'webapp' }
});

REPLACE Semantics: Providing agentVariables: { page: 'checkout' } REPLACES all variables with just { page: 'checkout' }. To keep existing variables, include them explicitly or omit the field entirely.

Changing agentVariables creates a new chat context. Each unique combination of agentId + agentVariables represents a different conversation.

close

close(): Promise<void>; Closes the chat widget.

window.stradaChat.close();

Context-Based Chat System

The widget maintains separate chats for each unique context. Context is determined by the combination of organizationId, agentId, and agentVariables.

How it works

Each unique context creates or accesses a separate chat
Changing variables creates a new context = different chat
Same variables returns to the same chat (history preserved)

Updating variables dynamically

To update variables after initialization, pass them to open().

// Initial setup
window.stradaSettings = {
  organizationId: 'your-org-id',
  agentId: 'your-agent-id',
  agentVariables: { userId: '123' }
};

// User navigates to checkout page - update variables
window.stradaChat.open({
  agentVariables: {
    userId: '123',
    page: 'checkout',
    cartTotal: 99.99
  }
}); // Opens/creates chat for checkout context

// User returns to home page - update variables again
window.stradaChat.open({
  agentVariables: { userId: '123' }
}); // Returns to original chat (same context)

Each unique combination of variables creates a separate chat. If you want to continue an existing conversation, ensure you pass the exact same variables.

setDarkMode

setDarkMode(enabled: boolean): void; Toggles dark mode dynamically. Useful for syncing the widget theme with your application’s theme.

// Enable dark mode
window.stradaChat.setDarkMode(true);

// Disable dark mode
window.stradaChat.setDarkMode(false);

// Match system preference
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
window.stradaChat.setDarkMode(prefersDark);

// Listen for system theme changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
  window.stradaChat.setDarkMode(e.matches);
});

subscribeEvent

subscribeEvent(eventKey: string, callback: (data: object, context: object) => void): Promise<number> Registers a callback for SDK events. Returns a subscription ID for later removal.

window.stradaChat.subscribeEvent('strada:ready', (data, context) => {
  console.log('Widget is ready:', data);
});

For best results, register event subscriptions inside stradaReadyCallback to ensure the SDK is loaded and no events are missed:

window.stradaSettings = {
  organizationId: 'your-org-id',
  agentId: 'your-agent-id',
  stradaReadyCallback: () => {
    window.stradaChat.subscribeEvent('strada:ready', (data) => {
      console.log('Widget loaded:', data);
    });
  }
};

The following are the events that you can currently subscribe to:

Event key	Data	Description
`strada:ready`	`{ isLoaded: boolean }`	Triggered when the widget has finished loading and is ready to use.

unsubscribeEvent

unsubscribeEvent(subscriptionId: number): void; Removes an event subscription using its subscription ID.

const subscriptionId = await window.stradaChat.subscribeEvent('strada:ready', (data) => {
  console.log('Widget is ready:', data);
});

// Later, unsubscribe
window.stradaChat.unsubscribeEvent(subscriptionId);

Type Signatures

The SDK actions commonly use the following type signatures.

StradaSettings

{
  organizationId: string;
  agentId: string;
  agentVariables?: Record<string, unknown>;
  metadata?: Record<string, unknown>;
  secureMetadata?: Record<string, unknown>;
  stradaReadyCallback?: (params: { isLoaded: boolean }) => void;
  toggleCallback?: (isOpen: boolean) => void;
  lazy?: boolean;
  hideButton?: boolean;
  parentElement?: string;
  darkMode?: boolean;
  widgetUrl?: string;
  getUserToken?: () => Promise<string | null>;
}

StradaEventKey

type StradaEventKey = 'strada:ready';

EventCallback

type EventCallback<K extends StradaEventKey> = (data: StradaEventData[K], context: EventContext) => void;

Web SDK

React Native SDK

​Settings

​organizationId

​agentId

​agentVariables

​metadata

​secureMetadata

​stradaReadyCallback

​toggleCallback

​lazy

​hideButton

​parentElement

​darkMode

​widgetUrl

​getUserToken

​Actions

​start

​open

​close

​Context-Based Chat System

​How it works

​Updating variables dynamically

​setDarkMode

​subscribeEvent

​unsubscribeEvent

​Type Signatures

​StradaSettings

​StradaEventKey

​EventCallback

Settings

organizationId

agentId

agentVariables

metadata

secureMetadata

stradaReadyCallback

toggleCallback

lazy

hideButton

parentElement

darkMode

widgetUrl

getUserToken

Actions

start

open

close

Context-Based Chat System

How it works

Updating variables dynamically

setDarkMode

subscribeEvent

unsubscribeEvent

Type Signatures

StradaSettings

StradaEventKey

EventCallback