# useClientSession

`useClientSession` reads a `ClientSession` from the nearest [`ClientSessionProvider`](https://ably.com/docs/ai-transport/api/react/core/providers.md#client-session-provider). 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.

<Code>

#### Javascript

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

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

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

This hook must be used within a [`ClientSessionProvider`](https://ably.com/docs/ai-transport/api/react/core/providers.md#client-session-provider). 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 

<Table id='UseClientSessionParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| channelName | optional | Look up a specific provider by channel name. Omit to use the innermost provider in the tree. | String |
| skip | optional | When `true`, skip context lookup and return the stub session immediately. Useful when an auth condition is not yet resolved. | Boolean |
| onError | optional | Called whenever the resolved session emits an error event. The subscription is established when the session resolves and removed on unmount. | `(error: Ably.ErrorInfo) => void` |

</Table>

## Returns 

<Table id='ClientSessionHandle'>

| Property | Description | Type |
| --- | --- | --- |
| session | The resolved session. A throwing stub when `skip` is `true`, when no matching provider was found, or when session construction failed. | `ClientSession<TInput, TOutput, TProjection, TMessage>` |
| sessionError | Set when no matching `ClientSessionProvider` was found or when session construction failed, and `skip` is `false`. `undefined` when the session resolved successfully. | `Ably.ErrorInfo` or Undefined |

</Table>

## Read the session 

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

The resolved [`ClientSession`](https://ably.com/docs/ai-transport/api/javascript/core/client-session.md). 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.

<Code>

### 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} />;
}
```
</Code>

## Related Topics

- [Providers](https://ably.com/docs/ai-transport/api/react/core/providers.md): API reference for the AI Transport React providers: ClientSessionProvider and the createSessionHooks factory.
- [useView](https://ably.com/docs/ai-transport/api/react/core/use-view.md): Subscribe to a paginated, branch-aware view of the AI Transport conversation tree from React.
- [useCreateView](https://ably.com/docs/ai-transport/api/react/core/use-create-view.md): Create an independent View over the AI Transport conversation tree from React, with its own branch selections and pagination.
- [useTree](https://ably.com/docs/ai-transport/api/react/core/use-tree.md): Stable structural query callbacks for the AI Transport conversation tree from React.
- [useAblyMessages](https://ably.com/docs/ai-transport/api/react/core/use-ably-messages.md): Subscribe to raw Ably InboundMessages on the AI Transport channel from React.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.