SDK API reference - Sagepilot Docs

Method return behavior

Method	Return behavior
`SagepilotChat.configure(config)`	`Promise<SagepilotMobileConfigureResult>`
`SagepilotChat.identify(identity)`	`Promise<SagepilotIdentifyResult>`
`SagepilotChat.logout()`	`Promise<SagepilotLogoutResponse>`
`SagepilotChat.getSession()`	`Promise<SagepilotSessionState>`
`SagepilotChat.getUnreadCount()`	`Promise<number>`
`SagepilotChat.presentMessageComposer(message?, options?)`	`boolean` or `Promise<boolean>` 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<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.

Push add-on

This reference describes matching 0.4.2 base and push add-on packages. Start with the step-by-step integration guide; use this page to look up inputs, timing and return values. push below means either brandPush.push on a standalone client or SagepilotChat.push after SagepilotChat.configure(...) succeeds with a push configuration. Both expose the same API. Do not run both clients for the same installation and push channel. The guide’s fetchPushProof, connectPush and disconnectPush are example functions implemented by your app, not SDK exports. You can supply the backend proof through your existing login/session response or a separate authenticated request.

Import map

Package	Exports used for push
`@sagepilot-ai/react-native-sdk`	`SagepilotBrandPush`, `SagepilotChat`, `createFirebasePushAdapter`, `createKeychainTokenStorage`, and push types such as `SagepilotPushMessage`.
`@sagepilot-ai/react-native-push-addon`	`createSagepilotNativePushAdapter`, `handleSagepilotBackgroundPush`, `getSagepilotPushPermission`, `getSagepilotPushNotificationSettings`, `openSagepilotPushNotificationSettings`.
`@react-native-firebase/messaging`	Firebase’s `getMessaging`, `getToken`, `onTokenRefresh`, `onMessage`, `onNotificationOpenedApp`, `getInitialNotification`, `setBackgroundMessageHandler`. These are Firebase methods, not Sagepilot customer APIs.

Client setup and identity

Method	Call it when	Input and effect	Return
`new SagepilotBrandPush(config)`	Once, for a push-only app.	Creates the client. `key` is `workspaceId:pushChannelId`; supply secure `tokenStorage`, `push.storage`, the adapter and `onError`. Construction does not identify or register a customer.	Client instance
`brandPush.start()`	Before standalone `identify`, after restoring the app’s login.	Restores the stored SDK session, starts listeners and attempts synchronization for an existing authorized customer. Does not ask for OS permission.	`Promise<void>`
`brandPush.identify(identityToken)`	After login/session restoration, or to renew push authorization.	Accepts a backend-signed proof string, resolves the customer and stores the scoped SDK session. Starts registration when permission allows. Does not accept a profile object or FCM token.	`Promise<void>`
`SagepilotChat.configure(config)`	Once during normal initialization of an app that uses chat.	Add `push: { channelId, storage, adapter }` to the existing chat configuration. Its main `key` still uses the chat channel ID.	`Promise<SagepilotMobileConfigureResult>`
`SagepilotChat.identify(profile)`	After app login, before push authorization.	Accepts `userId`, name, email, phone, custom properties and optional chat `userHash`. It clears the previous push grant, so authorize push afterwards.	`Promise<SagepilotIdentifyResult>`
`SagepilotChat.authorizePush(identityToken)`	After chat `identify`, or when renewing the push grant.	Verifies a backend-signed proof for the same customer and configured push channel. Keeps one shared SDK session. Does not grant marketing consent or OS permission.	`Promise<void>`
`brandPush.logout()` / `SagepilotChat.logout()`	Before clearing app credentials or changing accounts.	Pauses refresh and revokes the old installation before ending the SDK identity. A failed revocation retains credentials for retry.	`Promise<void>` / `Promise<SagepilotLogoutResponse>`
`brandPush.destroy()` / `SagepilotChat.destroy()`	When disposing of the client.	Stops listeners. Does not replace logout or revoke a device registration. Create/configure a client again before reuse.	`Promise<void>` / `void`

The backend identity proof contains the external customer ID and optional email/phone authorized by your brand. Your brand chooses how to verify its users; Sagepilot checks the signed proof and resolves the supplied customer identity. Use the same external ID as webhook client_customer_id and chat userId. A chat userHash, brand proof, FCM token and SDK session token have different purposes and are not interchangeable. A proof is valid for at most five minutes. Push authorization lasts 24 hours; your app must obtain a fresh proof from its backend to renew it. Do not embed the signing secret in the app.

Configuration fields used in the guide

Field	Meaning
`key`	Public workspace/channel identifiers separated by `:`. Standalone uses the push channel; chat uses its chat channel. This is not the identity signing secret.
`host`	Your Sagepilot workspace’s regional host. The default is `https://app.sagepilot.ai`.
`tokenStorage`	Secure storage for SDK session credentials. Use Keychain or SecureStore, not AsyncStorage.
`push.channelId`	The brand push channel ID when attaching push to chat. Standalone gets its channel from `key`.
`push.storage`	Durable storage for installation identity and push state. AsyncStorage is appropriate. Keep this across launches.
`push.adapter`	Firebase transport wrapped by the native add-on.
`push.installationId`	Optional existing stable installation ID. Omit it to let the SDK generate and persist one. Do not change it while a device binding exists.
`push.appId`, `push.appVersion`	Optional application identifier and version sent during registration. SDK package version is added automatically.
`push.onOpen`	Your callback for routing an observed notification tap.
`onError`	Required error callback for the standalone client and native adapter. For chat client errors, subscribe with `SagepilotChat.onError(callback)`. Avoid logging credentials or complete payloads.

Method	Call it when	Behavior and return
`push.requestPermission()`	The customer chooses to enable notifications.	Requests OS access through the adapter and then calls `sync()`. Returns `Promise<SagepilotPushPermission>`. It does not save marketing consent.
`push.sync(token?)`	To explicitly refresh registration or await its result after authorization.	Reads OS permission, obtains the current token from the adapter unless a token is supplied, and upserts this installation. Automatically used for token refresh and foreground checks. Returns `Promise<void>`. Can do nothing if identity/adapter is absent or synchronization is paused; denied permission revokes an existing binding. It is not an endpoint-status getter.
`push.register(registration)`	Only when your app deliberately manages tokens itself.	Manually registers a token for the session’s customer. Returns `Promise<{ endpoint_id: string }>`. The adapter flow calls this for you. It does not identify a customer or enable consent.
`push.unregister()`	You need to revoke this installation.	Returns `Promise<void>`. Does not revoke the customer’s other devices. Does not pause future automatic sync; use logout for account changes and preferences for a lasting opt-out.
`push.getPreferences()`	Loading your notification settings UI.	Reads customer preferences without changing OS permission. Returns `Promise<SagepilotPushPreferences>`.
`push.setPreferences(preferences)`	The customer changes their consent.	Merges supplied preference fields; omitted fields are preserved. Returns the saved `Promise<SagepilotPushPreferences>`. This is customer consent, not an OS permission request.

Permission values are authorized, provisional, denied and not_determined. Registration requires authorized or provisional. Provisional permission does not guarantee banners or sound. There is no separate public push.upsert() method. Upsert describes the server’s registration behavior: create an installation registration when absent, otherwise update it. sync() and register() use that behavior; neither requires a customer object because the session already identifies the customer. Manual registration input, for an already identified/authorized client:

await push.register({
  token: currentDeviceToken,
  provider: 'fcm', // Or 'apns' for a deliberately configured direct-APNs integration.
  permission: 'authorized', // Use the actual OS permission result.
  app_id: 'com.yourbrand.app', // Optional.
});

currentDeviceToken is supplied by your native provider integration. The Firebase adapter obtains it automatically. installation_id, customer identity and SDK version metadata are managed by the SDK; capabilities is an optional registration override normally supplied by the native adapter. Do not advertise SDK rendering without native forwarding installed. Preferences accept this shape; all fields are optional:

type PushPreferenceFields = {
  enabled?: boolean;
  marketing_enabled?: boolean;
  support_enabled?: boolean;
};
type PushPreferences = PushPreferenceFields & {
  app?: PushPreferenceFields;
  web?: PushPreferenceFields;
};

For a new SDK customer without saved preferences, defaults are enabled: true, marketing_enabled: false, support_enabled: true. Existing saved consent is preserved. Top-level enabled: false blocks all push; a platform’s enabled: false blocks that platform. An app/web category value overrides the matching top-level category value, so changing only marketing_enabled will not replace a saved app.marketing_enabled override. Keep the settings screen consistent with the scope you use. Preferences apply to the customer’s devices, not just the phone on which the switch changed. Device permission and channel policy must also allow delivery. Legacy webhook customers retain their existing behavior during SDK rollout.

Adapters and automatic callbacks

Method	Input	What it does
`createFirebasePushAdapter(firebase, permissions)`	Firebase callback functions and permission functions, as wired in the guide.	Returns a `SagepilotPushAdapter`. Calls the injected functions when needed; does not fetch a token at construction.
`createSagepilotNativePushAdapter(transport, options)`	The Firebase adapter plus `{ onError, displayMode?, channelName?, notificationSettingsPrompt? }`.	Returns an adapter with native rendering, analytics capture, durable buffering and upload using the base SDK’s session. Required for this guide’s analytics, including provider display.
`handleSagepilotBackgroundPush(message)`	A mapped `SagepilotPushMessage` from a real background callback.	Forwards it to native handling without starting chat or prompting. Returns `Promise<boolean>` for whether the native handler handled it, not a server-delivery receipt.
`push.handleReceived(message, foreground?)`	A host-owned receipt callback; `foreground` defaults to `false`.	Records receipt; can invoke an explicitly configured host foreground presenter. Returns `Promise<boolean>` for capture. Normally invoked by the adapter, not your screen code.
`push.handleOpened(message)`	A host-owned notification tap callback.	Records the open and invokes the configured routing flow when applicable. Returns `Promise<boolean>` for capture. Do not call it just because a message arrived.

The native adapter defaults to displayMode: 'provider', channelName: 'Notifications' and notificationSettingsPrompt: true. onError is required. Android advertises provider and SDK display support; iOS retains OS alert presentation in both modes. The channel policy can override the installation preference where supported. The Firebase adapter automatically subscribes to token refresh, foreground messages and taps once the client starts. Your app installs the one background handler and native forwarding. Avoid also wiring the same event into a second presenter or analytics implementation. The optional onOpen(message) in push configuration is your navigation callback. It does not create screens or configure app links. Preserve the original message for destination tracking and defer routing until authentication/navigation is ready.

Notification settings

These helpers are exported by the push add-on in 0.4.2:

Method	Call it when	Return/effect
`getSagepilotPushPermission()`	Inspecting OS access without prompting.	`Promise<SagepilotPushPermission>`. Passing `true` requests access; use `push.requestPermission()` in the normal flow so registration also synchronizes.
`getSagepilotPushNotificationSettings()`	Rendering a notification settings/diagnostics screen.	Resolves `{ notificationsEnabled: boolean, alertsEnabled: boolean \| null, lockScreenEnabled: boolean \| null }`. `null` means the device cannot reliably report the value.
`openSagepilotPushNotificationSettings()`	The user presses Open Settings.	`Promise<void>`; opens available OS notification settings, with an app-settings fallback. Does not grant permission or change privacy choices.

The adapter’s default guidance offers pop-up/lock-screen setup once after notification access is granted and the signed-in app is active. notificationSettingsPrompt: false disables that guidance if your app owns it. push.storage remembers dismissal. No separate permission dialog can guarantee banners, lock-screen content or a manufacturer’s Cards/Icons layout. See display setup.

Analytics and explicit outcomes

Method	Call it when	Return/effect
`push.track(type, message, metadata?, actionId?)`	Your app observes an actual destination, action or conversion outcome.	`Promise<boolean>`: whether local capture accepted the observation. `false` can mean a duplicate or an ineligible message. It is not confirmation of upload. Use the original signed notification.
`push.flush()`	You want an explicit upload attempt, such as after reconnecting.	`Promise<void>`. The add-on also retries automatically. Retryable failures retain queued events; success is not a guarantee that reporting has already refreshed.

Event type	Normal source
`received`	Available Firebase/native receipt callback.
`presentation_requested`, `presentation_failed`	Observable native presentation attempts/results.
`opened`	Actual notification tap.
`dismissed`	Supported native dismissal callback.
`destination_opened`, `destination_failed`	Your app after the intended screen loads or routing fails.
`action`, `conversion`	Your app after an actual action/conversion linked to that notification.

Receipt, tap and other native observations are captured by the configured add-on. Do not manufacture them after a provider send response. Firebase/provider rendering retains Sagepilot analytics when callbacks are forwarded; token registration alone does not report engagement. V1 deduplicates by notification delivery and event type. Actions/conversions also use actionId: use a stable order/action ID for each distinct outcome and reuse it when retrying that outcome. For example, in your confirmed purchase callback:

await push.track('conversion', originalPushMessage, { order_total: order.total }, order.id);

originalPushMessage must be the notification your app actually associates with that purchase, and order must be the confirmed order from your own flow. This does not implement attribution or general app event tracking for you. A generic action event does not create custom notification buttons. See metric availability and routing.

Lifecycle hooks you normally leave to the client

push.start(), push.stop(), push.pauseAndRevoke() and push.resume() support the client lifecycle. Normal apps call the standalone or chat client methods above and let that client manage these hooks. Do not use them as substitutes for authenticated login/logout.

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.

​Method return behavior

​Setup

​Identity and session

​Hosted chat UI

​Unread state

​Lifecycle events

​React hook

​Storage helpers

​Attachment helpers

​Push add-on

​Import map

​Client setup and identity

​Configuration fields used in the guide

​Permission, registration and consent

​Adapters and automatic callbacks

​Notification settings

​Analytics and explicit outcomes

​Lifecycle hooks you normally leave to the client

​Runtime notes

​License