Skip to main content
Strada’s React Native SDK consists of a StradaWidget component that you must add to your app to use any SDK functionality, along with corresponding props and methods.

​
Props

Configure the React Native SDK by passing props to the StradaWidget component. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  // ... other props
/>
Available configuration options:

​
organizationId

organizationId: string; (required) Your Strada organization ID. You can find this in the Strada dashboard. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
/>

​
agentId

agentId: string; (required) The ID of the agent to load in the chat widget. You can find this in the Strada dashboard. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
/>

​
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. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  agentVariables={{
    first_name: 'John',
    last_name: 'Doe',
    email: '[email protected]'
  }}
/>

​
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. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  metadata={{
    userId: '12345',
    accountType: 'premium',
    signupDate: '2024-01-15'
  }}
/>
To change these values after initialization, use the setMetadata method.
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. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  secureMetadata={{
    internalUserId: 'usr_12345',
    authToken: 'sensitive-token-value'
  }}
/>
Use secure metadata for sensitive identifiers, tokens, or confidential information that your actions need but should not be visible in the dashboard.

​
defaultView

defaultView?: 'chat' | 'list'; Controls which view the widget shows when it opens. Defaults to 'chat'.
  • 'chat': Opens directly to a chat conversation (new or existing)
  • 'list': Opens to the list of recent chats (requires authenticated user)
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  defaultView="list"
  getUserToken={async () => {
    return await getAuthToken();
  }}
/>
The list view requires user authentication via getUserToken. Anonymous users will always start in chat view.

​
onReady

onReady?(): void; Callback invoked when the SDK completes initialization. Useful for asynchronous widget loading scenarios. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  onReady={() => {
    console.log('Strada widget is ready. Chat support is now available.');
  }}
/>

​
onChatStart

onChatStart?(chatId: string): void; Callback triggered when a new chat session starts. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  onChatStart={(chatId) => {
    console.log('Chat started:', chatId);
    // Save chatId for analytics or persistence
  }}
/>

​
onChatEnd

onChatEnd?(chatId: string): void; Callback triggered when a chat session ends. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  onChatEnd={(chatId) => {
    console.log('Chat ended:', chatId);
  }}
/>

​
onMinimize

onMinimize?(): void; Callback triggered when the widget is minimized. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  onMinimize={() => {
    console.log('Widget minimized');
  }}
/>

​
hideButton

hideButton?: boolean; Hides the default floating button when set to true, allowing you to trigger the widget through custom UI elements. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  hideButton={true}
/>
Then use your own button: 
<Button title="Get Help" onPress={() => widgetRef.current?.open()} />

​
modalAnimationType

modalAnimationType?: 'none' | 'slide' | 'fade'; Controls the animation used when opening the widget in the native Modal (iOS/Android). Defaults to 'none'. This has no effect on desktop, where the widget renders as an in-page view. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  modalAnimationType="slide"
/>

​
widgetUrl

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

​
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. 
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  getUserToken={async () => {
    const response = await fetch('https://your-api.com/strada-token');
    const { token } = await response.json();
    return token;
  }}
/>
The getUserToken function should return a Promise that resolves to a JWT token string, or null if authentication should be skipped.

​
Methods

All methods are called through the widget ref.

​
open

open(options?: { agentId?: string }): void; Opens the widget. Pass an agentId to switch agents when opening. 
// Open the default agent
widgetRef.current?.open();

// Open a specific agent
widgetRef.current?.open({ agentId: 'different-agent-id' });

​
close

close(): void; Closes the chat widget. 
widgetRef.current?.close();

​
toggle

toggle(): void; Toggles the widget between open and closed states. 
widgetRef.current?.toggle();

​
setMetadata

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

​
setAgentVariables

Update agent variables. Changes take effect on next open() call. 
widgetRef.current?.setAgentVariables({
  screenName: 'checkout',
  reason: 'purchase'
});

​
setSecureMetadata

Update secure metadata (not exposed to client-side code). 
widgetRef.current?.setSecureMetadata({
  internalUserId: 'user_123'
});

​
subscribeEvent

subscribeEvent(eventKey: string, callback: (data: object, context: object) => void): number Registers a callback for SDK events. Returns a subscription ID for later removal. 
const subscriptionId = widgetRef.current?.subscribeEvent('strada:ready', (data, context) => {
  console.log('Widget is ready:', data);
});
For best results, register event subscriptions in useEffect to ensure the widget is mounted and no events are missed: 
useEffect(() => {
  const subscriptionId = widgetRef.current?.subscribeEvent('strada:chat:started', (data) => {
    console.log('Chat started:', data.chatId);
  });

  return () => {
    if (subscriptionId) {
      widgetRef.current?.unsubscribeEvent(subscriptionId);
    }
  };
}, []);
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.
strada:button:clicked{}Triggered when the floating button is clicked.
strada:chat:started{ chatId: string }Triggered when a new chat session starts.
strada:chat:ended{ chatId: string }Triggered when a chat session ends.
strada:chat:minimize{}Triggered when the widget is minimized.

​
unsubscribeEvent

unsubscribeEvent(subscriptionId: number): void; Removes an event subscription using its subscription ID. 
const subscriptionId = widgetRef.current?.subscribeEvent('strada:ready', (data) => {
  console.log('Widget is ready:', data);
});

// Later, unsubscribe
widgetRef.current?.unsubscribeEvent(subscriptionId);

​
Type Signatures

The SDK exports the following TypeScript types.

​
StradaWidgetProps

{
  organizationId: string;
  agentId: string;
  widgetUrl?: string;
  agentVariables?: Record<string, unknown>;
  metadata?: Record<string, unknown>;
  secureMetadata?: Record<string, unknown>;
  defaultView?: 'chat' | 'list';
  onReady?: () => void;
  onChatStart?: (chatId: string) => void;
  onChatEnd?: (chatId: string) => void;
  onMinimize?: () => void;
  getUserToken?: () => Promise<string | null>;
  hideButton?: boolean;
  modalAnimationType?: 'none' | 'slide' | 'fade';
}

​
StradaWidgetRef

{
  open: (options?: { agentId?: string }) => void;
  close: () => void;
  toggle: () => void;
  setMetadata: (data: Record<string, unknown>) => void;
  subscribeEvent: <K extends StradaEventKey>(
    eventKey: K | string,
    callback: EventCallback<K>
  ) => number;
  unsubscribeEvent: (subscriptionId: number) => void;
}

​
StradaEventKey

type StradaEventKey =
  | 'strada:ready'
  | 'strada:button:clicked'
  | 'strada:chat:started'
  | 'strada:chat:ended'
  | 'strada:chat:minimize';

​
EventCallback

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

​
StradaEventData

{
  'strada:ready': { isLoaded: boolean };
  'strada:button:clicked': Record<string, never>;
  'strada:chat:started': { chatId: string };
  'strada:chat:ended': { chatId: string };
  'strada:chat:minimize': Record<string, never>;
}

​
Hook API

The useStradaWidget hook provides a convenient way to interact with the widget. 
import { useStradaWidget } from '@stradahq/react-native-sdk';

const { widgetRef, open, close, toggle, setMetadata, subscribeEvent, unsubscribeEvent } = useStradaWidget();
All methods from the hook call the corresponding ref methods internally.