useClientSession

useClientSession reads a ClientSession from the nearest ClientSessionProvider. It is a thin context reader that never throws during render. If no matching provider exists or the session failed to construct, the hook returns a stub session and a populated sessionError so the component can render an error state without an error boundary.

JavaScript

import { useClientSession } from '@ably/ai-transport/react';

function Chat() {
  const { session, sessionError } = useClientSession();

  if (sessionError) return <ErrorBanner error={sessionError} />;
  return <Conversation session={session} />;
}

This hook must be used within a ClientSessionProvider. When the provider is absent the hook still returns a handle, but session is a stub that throws on every access and sessionError is set.

Parameters

channelNameoptionalString

Look up a specific provider by channel name. Omit to use the innermost provider in the tree.

skipoptionalBoolean

When true, skip context lookup and return the stub session immediately. Useful when an auth condition is not yet resolved.

onErroroptional(error: Ably.ErrorInfo) => void

Called whenever the resolved session emits an error event. The subscription is established when the session resolves and removed on unmount.

Returns

sessionClientSession<TInput, TOutput, TProjection, TMessage>

The resolved session. A throwing stub when skip is true, when no matching provider was found, or when session construction failed.

sessionErrorAbly.ErrorInfo or Undefined

Set when no matching ClientSessionProvider was found or when session construction failed, and skip is false. undefined when the session resolved successfully.

Read the session

session: ClientSession<TInput, TOutput, TProjection, TMessage>

The resolved ClientSession. All session methods are available, including view, tree, connect, cancel, createView, on, and close. The provider already invokes connect() once per mount, so application code rarely calls it directly. The hooks useView, useTree, useCreateView, and useAblyMessages resolve their session through the same provider, so reach for them whenever you want reactive state rather than the raw session.

Read the session error

sessionError: Ably.ErrorInfo | undefined

The construction or lookup error, if any. undefined when the session is usable. Check sessionError before touching session to avoid the stub throw.

The post-construction error path is separate. Subscribe to those with the onError parameter (or session.on('error', ...)) rather than reading them from sessionError.

Example

A chat component that subscribes to session errors and renders a fallback while the provider is being looked up.

JavaScript

import { useState } from 'react';
import { useClientSession } from '@ably/ai-transport/react';

function Chat() {
  const [runtimeError, setRuntimeError] = useState<Ably.ErrorInfo | undefined>();

  const { session, sessionError } = useClientSession({
    channelName: 'ai:demo',
    onError: setRuntimeError,
  });

  if (sessionError) return <ErrorBanner error={sessionError} />;
  if (runtimeError) return <ErrorBanner error={runtimeError} />;

  return <Conversation session={session} />;
}