Skip to main content
Quick Summary
You don’t need to handle different offline scenarios separately. The useOfflineSessions() hook automatically manages everything, whether users have brief network interruptions or extended offline periods.

The hook tracks offline sessions, handles retries, and updates your UI with the latest status. You don’t need to write complex logic for different scenarios.
Last updated:January 2026

​
Overview

The Suki Headless Web SDK provides a seamless offline experience for your users. It has an offline mode to keep your application working during network problems.

​
Understanding Offline Sessions

An offline session is a recording that you have submitted but that has not yet reached the Suki backend server due to a network disconnection. The SDK detects when the device is offline and automatically queues these sessions. It distinguishes between brief hiccups and continuous outages:
  • Brief interruptions: The SDK handles these transparently without triggering an offline session state. It uses a 15-second buffer to handle temporary connection problems.
  • Continuous disconnection: The session is marked as offline and queued for synchronization once the connection returns.

​
Estimated Data Usage

Audio files can be large. Use these estimates to plan for storage and bandwidth requirements:
Recording DurationApproximate File Size
10 minutes~19.2 MB
30 minutes~57.6 MB
The useOfflineSessions hook allows you to track the progress of sessions that are waiting to sync. You use this hook to build UI elements that show the user which files are pending, uploading, or finished.

​
How It Works

The hook returns a reactive list of sessions and a subscription method for listening to updates. 
const { sessions, on } = useOfflineSessions();

​
What It Returns

It returns the following values:

sessions

​
Sessions

This is an array of all current offline sessions. The array list automatically updates whenever a session’s status changes (for example, when it moves from syncing to synced), so your UI always shows the latest information.
Each object in the array represents a single session and contains details about its submission status.

​
Session Statuses

Sessions submitted while offline can have one of the following statuses that reflect their submission journey:
Session StatusDescription
idleThe session is queued locally and waiting for a network connection to begin uploading.
syncingThe session is currently uploading to the Suki backend server.
syncedThe upload is complete. The Suki backend server has successfully received the audio.
failedThe submission attempt failed. The SDK will automatically attempt to re-submit it in the background.

on

​
On

The on property lets you listen for session updates. You can register a function that runs automatically whenever a session’s status changes (for example, when it moves from syncing to synced).
This function returns a cleanup function. You must call this function to unsubscribe from the event and prevent memory leaks.

​
Example Code

The following example demonstrates how to use the useOfflineSessions hook within a React component to display the status of sessions.
React
import React, { useEffect } from 'react';
import { useOfflineSessions } from '@suki-sdk/platform-react';

function AmbientSessionMonitor() {
  // Destructure the sessions array and the 'on' subscription function
  const { sessions, on } = useOfflineSessions();

  useEffect(() => {
    // Subscribe to session updates using the 'on' function
    const unsubscribe = on('ambient:offlineSessionsUpdate', (updatedSessions) => {
      console.log('Sessions updated:', updatedSessions);
      // You can also update component state here if needed
    });

    // The cleanup function is returned to unsubscribe when the component unmounts
    return () => unsubscribe();
  }, [on]); // Dependency array ensures the effect runs only if 'on' changes

  return (
    <div>
      <h2>Ambient Session Status</h2>
      {sessions.length > 0 ? (
        <ul>
          {sessions.map(session => (
            <li key={session.id}>
              Session ID: {session.id} - Status: **{session.status}** ({session.sessionType})
            </li>
          ))}
        </ul>
      ) : (
        <p>No pending sessions.</p>
      )}
    </div>
  );
}

export default AmbientSessionMonitor;

​
Direct Subscription via PlatformClient (Alternative)

While we recommend using the useOfflineSessions hook for individual components, you may sometimes need to track session updates globally, for example, for centralized logging or analytics. In these cases, you can subscribe to events directly on the PlatformClient instance using the on method.

​
How It Works

You listen for the ambient:offlineSessionsUpdate event. The client triggers your callback function whenever the list of offline sessions changes, providing the updated array of sessions.

​
Example Code

React
import { PlatformClient, PlatformClientProvider } from '@suki-sdk/platform-react';

// Create a single client instance
const client = new PlatformClient({ env: 'staging', enableDebug: true, logLevel: 'error' });

function App() {

useEffect(()=>{
// Subscribe to events directly on the client instance
const unsubscribe =client.on('ambient:offlineSessionsUpdate', (sessions) => {
  console.log('Global pending sessions update:', sessions);
});
return () => unsubscribe();

},[])

  return ();
}

export { App };

​
Troubleshooting

Watch for status === 'complete' in useOfflineSessions().
SDK retries every 15 minutes plus immediately when browser goes online.
No - useOfflineSessions() auto-hydrates pending sessions.
Yes - right after status === 'complete'.

​
Next Steps

Refer to the Online/Offline Behavior guide to understand how the SDK handles network connectivity and transitions between online and offline states.