# useDeliveries

The `useDeliveries` hook calls a handler for every delivery on the transport's channel while the component is mounted. A delivery holds the decoded event and the Ably message it came from, in the same shape as [`subscribe()`](https://ably.com/docs/ai-transport/api/javascript/transport/transport.md#subscribe). The hook reads the latest handler on each delivery, so an inline function does not subscribe again on every render.

<Code>

#### Javascript

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

function Chat() {
  useDeliveries(({ event }) => {
    if (event !== undefined) merge(event);
  });

  return <Messages />;
}
```
</Code>

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

Subscribing attaches the channel. A failed attach is reported through [`useTransportStatus`](https://ably.com/docs/ai-transport/api/react/use-transport-status.md).

`useDeliveries` receives live deliveries only. To replay history before live deliveries, call `transport.subscribe` with a `history` option from [`useTransport`](https://ably.com/docs/ai-transport/api/react/use-transport.md#example).

## Parameters 

<Table id='UseDeliveriesParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| handler | required | Called with each delivery, in channel order. | `(delivery: Delivery<E>) => void` |
| options | optional | The provider to read. | <Table id='UseDeliveriesOptions'/> |

</Table>

<Table id='UseDeliveriesOptions' >

| Property | Description | Type |
| --- | --- | --- |
| channelName | Optional. The channel name of the provider to read. Omit it to read the nearest provider. | String |

</Table>

The `Delivery` type:

<Table id='Delivery'>

| Property | Description | Type |
| --- | --- | --- |
| event | The decoded event, or `undefined` when the codec produced no event for the message. | `E` or `undefined` |
| message | The Ably message as delivered, with its `serial`, `version`, `clientId`, `timestamp`, `action`, `data` and `extras`. | `Ably.InboundMessage` |

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

## Example 

A component tracks which prompt each response answers by the `requestId` header the agent set on its pipe.

<Code>

### Javascript

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

function ResponseLog() {
  const [lines, setLines] = useState([]);

  useDeliveries(({ event, message }) => {
    if (event?.type !== 'text-delta') return;
    const requestId = message.extras?.headers?.requestId;
    setLines((prev) => [...prev, `${requestId}: ${event.delta}`]);
  });

  return <pre>{lines.join('\n')}</pre>;
}
```
</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.
- [useTransport](https://ably.com/docs/ai-transport/api/react/use-transport.md): API reference for the AI Transport useTransport hook: read the transport from the nearest or a named TransportProvider.
- [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.