> ## Documentation Index > Fetch the complete documentation index at: https://docs.sagepilot.ai/llms.txt > Use this file to discover all available pages before exploring further. # SDK API reference > Public API surface for the Sagepilot React Native SDK. ## Method return behavior | Method | Return behavior | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `SagepilotChat.configure(config)` | `Promise` | | `SagepilotChat.identify(identity)` | `Promise` | | `SagepilotChat.logout()` | `Promise` | | `SagepilotChat.getSession()` | `Promise` | | `SagepilotChat.getUnreadCount()` | `Promise` | | `SagepilotChat.presentMessageComposer(message?, options?)` | `boolean` or `Promise` when `behavior.waitForIdentifyBeforeComposer` is enabled and identity is pending | | `SagepilotChat.present()` | `boolean` | | `SagepilotChat.presentMessages()` | `boolean` | | `SagepilotChat.dismiss()` / `hide()` / `toggle()` | `boolean` | | `SagepilotChat.isPresented()` | `boolean` | | `SagepilotChat.getIdentityState()` / `getSessionState()` / `getChannel()` | synchronous state | | `SagepilotChat.onIdentify(...)` / `onConversationCreated(...)` / lifecycle subscriptions | unsubscribe function | | `SagepilotChat.destroy()` | `void` | ## 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` 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.