SDK API reference

​

Method return behavior

​

Setup

• SagepilotChat.configure(config): initializes the SDK, loads channel config, creates or resumes a customer session, and starts unread polling unless disabled.
• SagepilotChat.destroy(): stops polling, clears in-memory SDK state, and removes listeners.
• SagepilotChat.getChannel(): returns the loaded channel bootstrap data.

​

Identity and session

• SagepilotChat.identify(identity): links the active session to a known customer.
• SagepilotChat.logout(): removes known-customer identity from the active session.
• SagepilotChat.getSession(): fetches the current session and returns safe session metadata. It does not expose the session token.
• SagepilotChat.getSessionState(): returns safe local session metadata. It does not expose the session token.
• SagepilotChat.getIdentityState(): returns local identity state, including identified, pending, and customer.
• SagepilotChat.onIdentify(callback): subscribes to successful identify events.

​

Hosted chat UI

• SagepilotChat.present(): opens the hosted chat home screen.
• SagepilotChat.presentMessages(): opens the hosted conversations/messages screen.
• SagepilotChat.presentMessageComposer(message?, options?): returns boolean and opens immediately unless behavior.waitForIdentifyBeforeComposer is enabled and an identify() call is in flight. If both are true, it returns Promise<boolean> and waits up to 60 seconds for a successful identify response before opening. { mode: "auto" } is the default and lets Sagepilot reuse an existing conversation when one is available. Pass { mode: "new" } to force a fresh conversation, or { chatId } to open a specific conversation. It does not auto-send.
• SagepilotChat.dismiss(): closes the hosted chat modal.
• SagepilotChat.hide(): alias for dismiss().
• SagepilotChat.toggle(): opens the chat when closed and closes it when open.
• SagepilotChat.isPresented(): returns whether the hosted chat modal is open.
• SagepilotChat.onConversationCreated(callback): subscribes to hosted conversations created from the React Native widget and returns chat_id plus any composer metadata.
• SagepilotChatProvider: renders the hosted Sagepilot chat inside a React Native modal WebView.

When SagepilotChatProvider is mounted, the SDK preloads a hidden hosted WebView after configure() so the first visible open can reuse warmed network/cache state. Disable this with behavior.preloadWebView: false.

​

Unread state

• SagepilotChat.getUnreadCount(): fetches and returns the current unread count.
• SagepilotChat.onUnreadChange(callback): subscribes to unread count changes.
• SagepilotChat.startUnreadPolling(intervalMs?): starts unread polling.
• SagepilotChat.stopUnreadPolling(): stops unread polling.

​

Lifecycle events

• SagepilotChat.onReady(callback): fires when SDK configuration completes.
• SagepilotChat.onPresent(callback): fires when chat opens.
• SagepilotChat.onDismiss(callback): fires when chat closes.
• SagepilotChat.onError(callback): subscribes to SDK errors.
• SagepilotChat.onStateChange(callback): subscribes to local SDK state changes.

​

React hook

• useSagepilotChat(): returns presentation helpers, unread count, identity state, and common actions for app-owned launchers and badges.

​

Storage helpers

• createKeychainTokenStorage(keychain, options?): adapts react-native-keychain for secure session token storage.
• createAsyncStorageCacheStorage(asyncStorage): adapts AsyncStorage for SDK cache features such as native file-picker batch recovery.

Do not use AsyncStorage for session tokens.

​

Attachment helpers

• createSagepilotFilePicker(options): creates a native camera, gallery, and document picker adapter from app-provided picker modules.
• createSagepilotFileStore(blobUtil, options?): creates durable app-private storage for picked-file bytes.
• SagepilotFilePickerError: typed error class surfaced when the picker fails for permission, camera, file-size, encoding, read, or unknown errors.

The optional @sagepilot-ai/react-native-camera-addon package exports createSagepilotCameraXFilePicker(options?) for Android CameraX attachments.

​

Runtime notes

The React Native UI uses react-native-webview to show the Sagepilot-owned hosted conversation. The SDK injects mobile WebView polish for viewport scaling, text selection, tap highlighting, native bridge message forwarding, and secure hosted-auth handoff. Customers should depend on the public SDK methods and components, not WebView internals or hosted route implementation details.

​

License

MIT. The MIT License applies only to this SDK code. It does not grant access to Sagepilot AI services, workspaces, API credentials, hosted infrastructure, models, data, or paid features. Use of Sagepilot AI hosted services, APIs, Workspace IDs, and runtime-generated license keys is governed separately by Sagepilot AI’s Terms of Service or the applicable customer agreement.