Skip to main content
Configure the SDK after your app knows the current workspace/channel and, if available, the current user. 
await SagepilotChat.configure({
  key: "workspace_id:channel_id"
});
If Sagepilot provides a dedicated endpoint for your workspace, pass it as an optional override: 
await SagepilotChat.configure({
  key: "workspace_id:channel_id",
  host: "https://your-sagepilot-host.com"
});

​
Supported options

OptionPurpose
keyPublic routing key in the format workspace_id:channel_id.
hostOptional Sagepilot host override. Most apps should omit this unless Sagepilot provides a dedicated endpoint.
widgetHostOptional hosted widget origin override. Use only when Sagepilot provides a separate widget endpoint.
headersAdditional headers for SDK service requests. Do not pass server API keys or long-lived secrets from a mobile app.
fetchCustom fetch implementation for runtimes that need one.
tokenStorageSecure storage adapter for SDK-created customer session tokens.
cacheStorageOptional durable cache adapter used by SDK features such as native file-picker batch recovery.
filePickerOptional native picker adapter. Use createSagepilotCameraXFilePicker() from the CameraX addon or createSagepilotFilePicker(...) with app-provided picker modules.
fileStoreOptional native file-store adapter created with createSagepilotFileStore(...) for durable picked-file bytes.
anonymousIdOptional stable anonymous identifier sent when the SDK creates a customer session.
metadataOptional app metadata merged into the session creation payload.
deviceInfoOptional adapter that returns device metadata to include during session creation.
presentation.styleModal presentation style: "sheet", "fullScreen", or "push".
presentation.mobileAdds mobile=1 to the hosted widget URL. Defaults to true for React Native.
presentation.showCloseButtonControls whether the provider renders a native close button around the WebView. Defaults to false so the hosted Sagepilot widget owns close behavior.
theme.accentColorPrimary brand color used as the fallback launcher button color.
theme.logoUrlOptional brand logo URL exposed in SDK theme state.
theme.preferredColorSchemeOptional hosted chat color scheme hint: "light", "dark", or "system".
theme.launcherOptional chat launcher icon, label, and badge color configuration.
behavior.preloadWebViewPreloads a hidden hosted chat WebView after configuration.
behavior.enableUnreadPollingStarts or disables automatic unread-count polling after configuration.
behavior.unreadPollIntervalMsSets the unread polling interval in milliseconds.
behavior.waitForIdentifyBeforeComposerWhen true, presentMessageComposer() waits up to 60 seconds for an in-flight identify() call before opening. Defaults to false.
For attachment setup, see Native file picker. For push notifications, see Push notifications.

​
Basic setup

import * as Keychain from "react-native-keychain";
import { useEffect, type ReactNode } from "react";
import {
  SagepilotChat,
  SagepilotChatProvider,
  createKeychainTokenStorage
} from "@sagepilot-ai/react-native-sdk";

const tokenStorage = createKeychainTokenStorage(Keychain);

export function SagepilotProvider({ children }: { children: ReactNode }) {
  useEffect(() => {
    let cancelled = false;

    async function setupSagepilot() {
      await SagepilotChat.configure({
        key: "workspace_id:channel_id",
        tokenStorage,
        presentation: {
          style: "sheet",
          mobile: true
        },
        behavior: {
          preloadWebView: true,
          enableUnreadPolling: true,
          waitForIdentifyBeforeComposer: true
        }
      });

      if (!cancelled) {
        await SagepilotChat.identify({
          userId: "user_123",
          email: "[email protected]",
          name: "Customer Name"
        });
      }
    }

    void setupSagepilot().catch(console.warn);

    return () => {
      cancelled = true;
      SagepilotChat.destroy();
    };
  }, []);

  return <SagepilotChatProvider>{children}</SagepilotChatProvider>;
}
Mount the provider once near the top of your app: 
export function App() {
  return (
    <SagepilotProvider>
      <RootNavigator />
    </SagepilotProvider>
  );
}

​
Keep configuration lifecycle stable

SagepilotChat.configure(...) is asynchronous. Await it before calling identify() or opening chat, and avoid reconfiguring the SDK on every render. If your setup depends on auth or workspace state, use stable primitive values in the effect dependencies. Do not depend on entire session or user objects if your auth library recreates those objects frequently. 
useEffect(() => {
  if (!workspaceId || !channelId || !userId) return;

  let cancelled = false;

  async function setupSagepilot() {
    await SagepilotChat.configure({
      key: `${workspaceId}:${channelId}`,
      tokenStorage
    });

    if (!cancelled) {
      await SagepilotChat.identify({
        userId,
        email,
        name
      });
    }
  }

  void setupSagepilot().catch(console.warn);

  return () => {
    cancelled = true;
    SagepilotChat.destroy();
  };
}, [workspaceId, channelId, userId, email, name]);
Mount SagepilotChatProvider once, and only re-run setup when the actual workspace, channel, or user values change.

​
Chat launcher theme

Use theme.launcher to configure the icon button and unread badge colors for your app-owned launcher. The SDK resolves omitted values to Sagepilot defaults. 
await SagepilotChat.configure({
  key: "workspace_id:channel_id",
  theme: {
    accentColor: "#173c2d",
    preferredColorScheme: "system",
    launcher: {
      label: "Support",
      buttonColor: "#173c2d",
      pressedButtonColor: "#225340",
      disabledButtonColor: "#d8cdbb",
      borderColor: "#2a5e49",
      disabledBorderColor: "#cbbda9",
      iconColor: "#fff8ef",
      iconInsideColor: "#173c2d",
      labelColor: "#d4e9dc",
      disabledContentColor: "#8d8172",
      unreadBadgeColor: "#e76f51",
      unreadBadgeTextColor: "#ffffff",
      unreadBadgeBorderColor: "#efe4d4"
    }
  }
});