> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Offline Mode

> Learn how to handle offline sessions in the Suki Headless Web SDK

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    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.

    <br />

    <br />

    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.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">June 2026</span>
  </div>
</div>

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 duration | Approximate file size |
| ------------------ | --------------------- |
| 10 minutes         | \~19.2 MB             |
| 30 minutes         | \~57.6 MB             |

## Offline sessions hook (recommended)

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.

```javascript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const { sessions, on } = useOfflineSessions();
```

### What it returns

It returns the following values:

<Accordion title="Sessions" defaultOpen="true">
  #### 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 `uploading` to `complete`), so your UI always shows the latest information.

  <Note>
    Each object in the array represents a single session and contains details about its submission status.
  </Note>

  #### Session statuses

  Sessions submitted while offline use the same `status` values as in the [Online/offline behavior](/headless-web-sdk/guides/online-offline-behavior#session-object-structure) guide. They reflect upload and backend processing:

  | Session status | Description                                                                                           |
  | -------------- | ----------------------------------------------------------------------------------------------------- |
  | `idle`         | The session is queued locally and waiting for a network connection to begin uploading.                |
  | `uploading`    | The session is currently uploading to the Suki backend. Optional `progress` (0–100) may be available. |
  | `processing`   | Upload finished; the backend is processing the session (for example, generating the note).            |
  | `complete`     | Processing finished. Fetch the transcript or note using the session ID.                               |
  | `error`        | The submission or pipeline failed. The SDK may retry in the background.                               |
</Accordion>

<Accordion title="On" defaultOpen="true">
  #### On

  The `on` property lets you listen for session updates. Register a function that runs automatically whenever a session's status changes (for example, when it moves from `uploading` to `complete`).

  <Note>
    This function returns a **cleanup function**. You must call this function to unsubscribe from the event and prevent memory leaks.
  </Note>
</Accordion>

## Example code

The following example demonstrates how to use the `useOfflineSessions` hook within a React component to display the status of sessions.

```JavaScript React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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);
      // Optionally 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)

We recommend using the `useOfflineSessions` hook for individual components. However, 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

```JavaScript React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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

<AccordionGroup>
  <Accordion title="How do we fetch the note later?">
    Watch for `status === 'complete'` in `useOfflineSessions()`.
  </Accordion>

  <Accordion title="What if user offline for hours?">
    SDK retries every **15 minutes** plus immediately when browser goes online.
  </Accordion>

  <Accordion title="Need to resubscribe after reload?">
    No - `useOfflineSessions()` auto-hydrates pending sessions.
  </Accordion>

  <Accordion title="Is local audio cleaned up?">
    Yes - right after `status === 'complete'`.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Online/offline behavior](/headless-web-sdk/guides/online-offline-behavior) guide to understand how the SDK handles network connectivity and transitions between online and offline states.