> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getstrada.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

Strada's React Native SDK consists of a `StradaWidget` component that you must [add to your app](/sdks/react-native/getting-started) to use any SDK functionality, along with corresponding [props](#props) and [methods](#methods).

## Props

Configure the React Native SDK by passing props to the `StradaWidget` component.

```typescript theme={null}
<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.

```typescript theme={null}
<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.

```typescript theme={null}
<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.

```typescript theme={null}
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  agentVariables={{
    first_name: 'John',
    last_name: 'Doe',
    email: 'john@example.com'
  }}
/>
```

### 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](#agentvariables) instead.

```typescript theme={null}
<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](#setmetadata) method.

<Note>Meta field keys should not include whitespace, emojis, or special characters.</Note>

### 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.

```typescript theme={null}
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  secureMetadata={{
    internalUserId: 'usr_12345',
    authToken: 'sensitive-token-value'
  }}
/>
```

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

### 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)

```typescript theme={null}
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  defaultView="list"
  getUserToken={async () => {
    return await getAuthToken();
  }}
/>
```

<Note>
  The list view requires user authentication via `getUserToken`. Anonymous users will always start in chat
  view.
</Note>

### darkMode

`darkMode?: boolean;`

Enables dark mode theme for the widget. Defaults to `false`.

```typescript theme={null}
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  darkMode={true}
/>
```

To toggle dark mode dynamically after initialization, use the [setDarkMode](#setdarkmode) method.

### onReady

`onReady?(): void;`

Callback invoked when the SDK completes initialization. Useful for asynchronous widget loading scenarios.

```typescript theme={null}
<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.

```typescript theme={null}
<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.

```typescript theme={null}
<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.

```typescript theme={null}
<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.

```typescript theme={null}
<StradaWidget
  ref={widgetRef}
  organizationId="your-org-id"
  agentId="your-agent-id"
  hideButton={true}
/>
```

Then use your own button:

```typescript theme={null}
<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.

```typescript theme={null}
<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.

```typescript theme={null}
<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;
  }}
/>
```

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

## 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.

```typescript theme={null}
// 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.

```typescript theme={null}
widgetRef.current?.close();
```

### toggle

`toggle(): void;`

Toggles the widget between open and closed states.

```typescript theme={null}
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.

```typescript theme={null}
widgetRef.current?.setMetadata({
  userId: '67890',
  accountType: 'enterprise',
  currentPage: '/pricing'
});
```

<Note>Meta field keys should not include whitespace, emojis, or special characters.</Note>

### setAgentVariables

Update agent variables. Changes take effect on next `open()` call.

```typescript theme={null}
widgetRef.current?.setAgentVariables({
  screenName: 'checkout',
  reason: 'purchase'
});
```

### setSecureMetadata

Update secure metadata (not exposed to client-side code).

```typescript theme={null}
widgetRef.current?.setSecureMetadata({
  internalUserId: 'user_123'
});
```

### setDarkMode

`setDarkMode(enabled: boolean): void;`

Toggles dark mode dynamically. Useful for syncing the widget theme with your app's theme.

```typescript theme={null}
// Enable dark mode
widgetRef.current?.setDarkMode(true);

// Disable dark mode
widgetRef.current?.setDarkMode(false);

// Sync with React Native appearance
import { useColorScheme } from 'react-native';

const colorScheme = useColorScheme();
widgetRef.current?.setDarkMode(colorScheme === 'dark');
```

### subscribeEvent

`subscribeEvent(eventKey: string, callback: (data: object, context: object) => void): number`

Registers a callback for SDK events. Returns a subscription ID for later removal.

```typescript theme={null}
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:

```typescript theme={null}
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 key               | Data                    | Description                                                         |
| :---------------------- | :---------------------- | :------------------------------------------------------------------ |
| `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.

```typescript theme={null}
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

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

### StradaWidgetRef

```typescript theme={null}
{
  open: (options?: { agentId?: string }) => void;
  close: () => void;
  toggle: () => void;
  setMetadata: (data: Record<string, unknown>) => void;
  setAgentVariables: (data: Record<string, unknown>) => void;
  setSecureMetadata: (data: Record<string, unknown>) => void;
  setDarkMode: (enabled: boolean) => void;
  subscribeEvent: <K extends StradaEventKey>(
    eventKey: K | string,
    callback: EventCallback<K>
  ) => number;
  unsubscribeEvent: (subscriptionId: number) => void;
}
```

### StradaEventKey

```typescript theme={null}
type StradaEventKey =
  | 'strada:ready'
  | 'strada:button:clicked'
  | 'strada:chat:started'
  | 'strada:chat:ended'
  | 'strada:chat:minimize';
```

### EventCallback

```typescript theme={null}
type EventCallback<K extends StradaEventKey> = (data: StradaEventData[K], context: EventContext) => void;
```

### StradaEventData

```typescript theme={null}
{
  '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.

```typescript theme={null}
import { useStradaWidget } from '@stradahq/react-native-sdk';

const { widgetRef, open, close, toggle, setMetadata, setDarkMode, subscribeEvent, unsubscribeEvent } =
  useStradaWidget();
```

All methods from the hook call the corresponding ref methods internally.