Skip to main content
To effectively manage offline scenarios, you must understand which commands require an active network connection and which function locally.Commands that require a networkThe following commands always require an active internet connection. If you call them while offline, the SDK throws a PlatformError (or a wrapped network error).
  • Authentication: login, registerUser, updatePartnerToken.
  • Session creation: session.create (from the useAmbient hook).
  • Initial start: The start method (from useAmbientSession) needs a connection once to establish the backend session stream.
Commands that work offlineOnce you successfully start a session, the Suki SDK becomes offline-resilient.
  • Capture: If the network drops after the session starts, the SDK continues to capture and buffer microphone audio locally in IndexedDB.
  • Pause and resume: Use pause and resume while offline. The SDK updates the local state immediately and reconciles it eventually when the connection returns.
  • Submit:.
    • Online: The session finalizes immediately.
    • Offline: The SDK marks the session as “finalize-pending.” It automatically starts the upload process once the network is restored.
  • Cancel:.
    • Online: The session cancels immediately.
    • Offline: The cancellation is queued. If the session is still valid when you reconnect, the SDK applies the cancellation.
Error handling and status tracking You should monitor the session status to handle offline behaviors correctly.
  • Errors: Connectivity issues during online-only commands surface as PlatformError. You should catch these and notify the user to check their connection.
  • Status updates: The outcome of offline actions (like submit or cancel) is reflected in the session status. Track this using the useOfflineSessions hook in React.
The initial create and start commands are the only critical points that require a network. After that, the SDK safely stores encrypted audio locally and syncs your submit or cancel actions eventually.
Yes. Pass an optional deviceId so the recording uses a specific microphone. Requires Headless Web SDK v0.3.1 or later (@suki-sdk/platform and @suki-sdk/platform-react).
  • React: Pass config.audio.deviceId to useAmbientSession with a MediaDeviceInfo.deviceId from your own enumerateDevices() flow.
  • Platform Client: Pass { audio: { deviceId } } to startAmbientSession and resumeAmbientSession.
Your app owns the microphone picker and device list. The SDK does not enumerate devices or persist the selection.Changing deviceId while recording does not switch the microphone that is already in use. Update your app state, call pause(), then call resume(). Expect a short capture gap. There is no public switchMicrophone API.When an exact deviceId is unavailable or disconnected, start or resume fails. The SDK does not fall back to the browser default microphone. The partner-facing code is StartSessionFailed or ResumeSessionFailed, with reason AudioRecorderFailure (not a top-level AudioRecorderFailure code). On Platform Client you get structured code / reason / cause. In React useAmbientSession, start/resume often rethrow a string from error.toString().Learn more in Select a microphone.
Offline mode has no fixed timeout. As long as the browser’s IndexedDB remains intact, the SDK preserves the buffered sessions.If you close the browser tab or window, the SDK scans the database when you re-initialize the PlatformClient on the next load. It then automatically starts uploading any offline sessions that you previously submitted. The browser’s storage settings determine the effective lifetime of this offline data.
Effective lifetime of offline data is governed by browser storage and not by an internal SDK timer.
The SDK manages session persistence internally. If an ongoing session is interrupted by a refresh or relaunch, you can resume it by passing the same ambientSessionId.The session continues from where it left off, and you can track updates via the useOfflineSessions hook.
Last modified on September 29, 2026