# useTransport

The `useTransport` hook returns the [transport](https://ably.com/docs/ai-transport/api/javascript/transport/transport.md) from the nearest `TransportProvider`, or from the provider for a channel name you pass. Use it to send messages, pipe events, or subscribe with history replay from a component.

<Code>

#### OpenAI Javascript

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

function Composer({ channelName }) {
  const { transport, error } = useTransport();

  if (error) return <p>Transport unavailable: {error.message}</p>;

  const send = async (text) => {
    if (!transport) return;
    const requestId = crypto.randomUUID();
    await transport.send({ type: 'input', items: [{ role: 'user', content: text }] }, { headers: { requestId } });
    // Wake the agent. It reads the prompt from the channel.
    await fetch('/api/chat', { method: 'POST', body: JSON.stringify({ channelName, requestId }) });
  };

  return <button onClick={() => send('Hello')} disabled={!transport}>Send</button>;
}
```

#### Vercel AI SDK Javascript

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

function Composer({ channelName }) {
  const { transport, error } = useTransport();

  if (error) return <p>Transport unavailable: {error.message}</p>;

  const send = async (text) => {
    if (!transport) return;
    const message = { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text }] };
    await transport.send({ type: 'user-message', message }, { headers: { requestId: message.id } });
    // Wake the agent. It reads the prompt from the channel.
    await fetch('/api/chat', { method: 'POST', body: JSON.stringify({ channelName, requestId: message.id }) });
  };

  return <button onClick={() => send('Hello')} disabled={!transport}>Send</button>;
}
```
</Code>

This hook must be used within a [`TransportProvider`](https://ably.com/docs/ai-transport/api/react/transport-provider.md).

## Parameters 

<Table id='UseTransportParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| channelName | optional | The channel name of the provider to read. Omit it to read the nearest provider. | String |

</Table>

The hook throws an [`ErrorInfo`](https://ably.com/docs/ai-transport/api/errors.md#errorinfo) with `InvalidArgument` when no matching `TransportProvider` encloses the component.

## Returns 

<Table id='UseTransportReturns'>

| Property | Description | Type |
| --- | --- | --- |
| transport | The provider's transport. `undefined` on the first render, before the provider has created it, and when creating it failed. | `Transport<E>` or `undefined` |
| error | The error that stopped the provider creating the transport, or `undefined` when the transport exists. | [`ErrorInfo`](https://ably.com/docs/ai-transport/api/errors.md#errorinfo) or `undefined` |

</Table>

## Example 

A component subscribes with history replay from the serial your server stored with the conversation. `useDeliveries` has no history option, so the component calls `transport.subscribe` in an effect and unsubscribes when the effect cleans up.

<Code>

### Javascript

```
import { useEffect } from 'react';
import { fromSerial } from '@ably/ai-transport';
import { useTransport } from '@ably/ai-transport/react';

function Conversation({ storedSerial, onDelivery }) {
  const { transport } = useTransport();

  useEffect(() => {
    if (!transport) return;
    const unsubscribe = transport.subscribe(onDelivery, {
      history: storedSerial ? { replay: fromSerial(storedSerial) } : undefined,
    });
    return () => unsubscribe();
  }, [transport, storedSerial, onDelivery]);

  return null;
}
```
</Code>

## Related Topics

- [TransportProvider](https://ably.com/docs/ai-transport/api/react/transport-provider.md): API reference for the AI Transport TransportProvider: create a transport for a channel and make it available to React components.
- [useDeliveries](https://ably.com/docs/ai-transport/api/react/use-deliveries.md): API reference for the AI Transport useDeliveries hook: receive every delivery on the transport's channel while a component is mounted.
- [useHistory](https://ably.com/docs/ai-transport/api/react/use-history.md): API reference for the AI Transport useHistory hook: read the channel's history one page at a time, oldest first.
- [useTransportStatus](https://ably.com/docs/ai-transport/api/react/use-transport-status.md): API reference for the AI Transport useTransportStatus hook: observe the transport's discontinuities and errors.

## 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.