# useMessageSync

Wire AI Transport message updates into Vercel's `useChat` message state. Subscribes to the transport view's `update` event and replaces `useChat`'s messages with the view's authoritative list. Use this when `useChat`'s message array needs to reflect messages from other devices, browser tabs, or observer participants on the same session.

Without `useMessageSync`, `useChat` only renders messages from its own sends. The hook bridges the gap by feeding the view's authoritative list into `useChat`'s state.

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

<Code>

#### React

```
import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
import { useChat } from '@ai-sdk/react';

function Chat({ chatId }) {
  const { chatTransport } = useChatTransport();
  const { messages, setMessages, sendMessage } = useChat({ id: chatId, transport: chatTransport });
  useMessageSync({ setMessages });
  // messages now includes sends from other devices.
}
```
</Code>

## Parameters

<Table id='UseMessageSyncProps'>

| Prop | Required | Description | Type |
| --- | --- | --- | --- |
| setMessages | Required | The `setMessages` updater from `useChat()`. Called with an updater function that replaces the previous message list with the view's authoritative list. | `(updater: (prev: UIMessage[]) => UIMessage[]) => void` |
| channelName | Optional | Channel name of the `ChatTransportProvider` to observe. Omit to use the nearest provider in the tree. | String |
| skip | Optional | When `true`, skip all subscriptions and do nothing. Use when the hook's dependencies are not yet resolved (for example, auth pending). | Boolean |

</Table>

## Returns

The hook returns `void`. The sync is set up as a side-effect inside `useEffect`.

When a `ChatTransport` is provided (resolved from the nearest `ChatTransportProvider`), `setMessages` calls are gated during active own-turn streams. This prevents the push/replace ID mismatch in `useChat`'s internal write function. When the stream finishes, the gate opens and an immediate sync fires to pick up any observer messages that arrived during the stream.

## Example

<Code>

### React

```
import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
import { useChat } from '@ai-sdk/react';

function Chat({ chatId }) {
  const { chatTransport } = useChatTransport();
  const { messages, setMessages, sendMessage, stop } = useChat({
    id: chatId,
    transport: chatTransport,
  });
  useMessageSync({ setMessages });

  return (
    <div>
      {messages.map((m) => <Message key={m.id} message={m} />)}
      <Composer onSend={(text) => sendMessage({ text })} onStop={stop} />
    </div>
  );
}
```
</Code>

## Related Topics

- [Providers](https://ably.com/docs/ai-transport/api/react/providers.md): TransportProvider and ChatTransportProvider for the AI Transport React integration.
- [useClientTransport](https://ably.com/docs/ai-transport/api/react/use-client-transport.md): Read a ClientTransport from the nearest TransportProvider in the AI Transport React integration.
- [useView](https://ably.com/docs/ai-transport/api/react/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/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/use-tree.md): Stable structural query callbacks for the AI Transport conversation tree from React.
- [useActiveTurns](https://ably.com/docs/ai-transport/api/react/use-active-turns.md): Subscribe to active turns on the AI Transport channel from React.
- [useAblyMessages](https://ably.com/docs/ai-transport/api/react/use-ably-messages.md): Subscribe to raw Ably InboundMessages on the AI Transport channel from React.
- [useChatTransport](https://ably.com/docs/ai-transport/api/react/use-chat-transport.md): Read a ChatTransport and its underlying ClientTransport from the nearest ChatTransportProvider in AI Transport.

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