# ovok.realtime

Canonical page: https://docs.ovok.com/web-sdk/core/namespaces/realtime

`ovok.realtime` opens a FHIR R4 websocket subscription through the API host. Signed-in apps call it to react to new or changed resources without polling.

## Subscribe to changes [#subscribe-to-changes]

`subscribe` takes a FHIR search string as the criteria and a handler.

```ts
import type { RealtimeNotification } from '@ovok/core';

const notifications: RealtimeNotification[] = [];

const unsubscribe = await ovok.realtime.subscribe(
  'Observation?subject=Patient/123',
  (notification) => {
    notifications.push(notification);
  },
);
```

- It creates a `Subscription` resource, then connects the socket.
- Empty criteria throw `OvokValidationError`.
- If the socket cannot start, the new subscription is deleted again and the error is thrown.
- The handler receives `SubscriptionStatus` event notifications. `notification.resources` holds the changed resources the server sent with each one. Handshake, heartbeat and ping/pong messages stay internal.

## Stay connected [#stay-connected]

The client keeps the connection alive for you.

- It refreshes the binding token before it expires and reconnects with a fresh token if the socket drops, waiting longer between failed attempts.
- When the user signs out it pauses; when a user signs in again it reconnects.
- The socket URL must be on the configured API host, or the subscription fails with `OvokServiceError`.

## Stop listening [#stop-listening]

```ts
await unsubscribe();
```

- It closes the socket and deletes the server subscription.
- Call it when the screen unmounts, or the subscription stays open.

## Reference [#reference]

- [realtime API reference](/web-sdk/core/reference/core/realtime): every method and type.
- [ovok.session](/web-sdk/core/namespaces/session) for session changes.
- [Errors and retries](/web-sdk/core/errors-and-retries)