Skip to main content
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: '[email protected]'
    }
  };
</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 after widget setup, use the setMetadata 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>

​
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 }): Promise<void>; Opens the widget. Pass an agentId to switch agents when opening. 
// Open the default agent
window.stradaChat.open();

// Open a specific agent
window.stradaChat.open({ agentId: 'different-agent-id' });

​
close

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

​
setMetadata

setMetadata(data: Record<string, unknown>): Promise<void>; Updates metadata after initialization. Primarily useful in Single Page Applications where user context changes while the widget remains active. 
window.stradaChat.setMetadata({
  userId: '67890',
  accountType: 'enterprise',
  currentPage: '/pricing'
});
Meta field keys should not include whitespace, emojis, or special characters.

​
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 keyDataDescription
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;
  widgetUrl?: string;
  getUserToken?: () => Promise<string | null>;
}

​
StradaEventKey

type StradaEventKey = 'strada:ready';

​
EventCallback

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