Vercel AI SDK ChatTransport: implementing a custom WebSocket transport

By default, useChat sends messages via HTTP POST to /api/chat and receives responses as a Server-Sent Events stream. That's DefaultChatTransport - the implementation the SDK ships with.

The ChatTransport interface abstracts this away. Every transport implementation exposes one core method: sendMessages. When you submit a message, useChat calls sendMessages on whatever transport you've configured. The transport gets that message to the server and returns a readable stream of UIMessageChunk events back to the client.

The implementation details - how the connection works, what protocol it uses, how reconnection is handled - are entirely encapsulated in the transport. useChat doesn't know or care.

Configuring a transport is a single argument:

const { messages, sendMessage, stop } = useChat({
  transport: new MyCustomTransport()
});

That's the full change to application code. Your agent, tool calls, message persistence, and UI rendering all stay exactly as they are. Only the delivery mechanism changes.

Vercel points you to the source implementations as the reference for building your own:

• DefaultChatTransport - the default HTTP transport

• HttpChatTransport - the base HTTP transport with request handling

• ChatTransport interface - the interface you implement

The ChatTransport interface exists because of a structural constraint: Vercel's serverless functions can't host persistent WebSocket connections. Each function invocation terminates after responding. There's no persistent process to hold a socket open.

Rather than limit AI applications to what serverless can support, Vercel made transport pluggable. Their Knowledge Base page on WebSocket support directs you to third-party providers - Ably is listed first.

The AI SDK 5 announcement describes the intent directly: "Swap out the default fetch-based transport for custom implementations. Use WebSockets for real-time communication or connect directly to LLM providers without a backend."

This isn't a workaround for a platform limitation. It's a design decision: the transport layer is yours to own.

To implement ChatTransport, you implement two methods.

sendMessages is called whenever the user submits a message. It receives the current message array and a session ID, and returns a ReadableStream<UIMessageChunk> that useChat consumes to update the UI.

reconnectToStream is called when useChat needs to reconnect to a stream that's already in progress - for example, after a page reload. If your transport doesn't support reconnection, return null. DefaultChatTransport delegates this to the server via a separate GET request; DirectChatTransport always returns null because there's no persistent server-side stream.

A WebSocket transport typically works like this: when sendMessages is called, open or reuse a channel for the session and publish the message. Return a stream that yields UIMessageChunk events as they arrive on that channel. reconnectToStream subscribes to the same channel and replays from the client's last offset.

Replacing the default HTTP transport with a channel-based transport changes the capability model of the whole session, not just the delivery mechanism.

Cancel becomes an explicit message. Instead of closing the SSE connection and hoping the server notices, stop() publishes a typed cancel message on the channel. The server receives it as intent. The distinction between intentional stop and network drop - the source of the billing issues documented in GitHub #8325 - disappears.

The session survives disconnects. When the connection drops - tab switch, mobile backgrounding, network change - the channel holds the session open. A reconnecting client presents its last offset and replays only the messages it missed. From the server's perspective, there was no gap.

Multiple clients can join. A second tab or a different device with the same session ID subscribes to the same channel and receives the stream. Session continuity is a property of the channel, not the HTTP connection.

None of this requires changes to your agent code or UI components. These are transport-layer properties.

Does it implement the interface? A transport that correctly implements ChatTransport drops into useChat without changes to your application code. Implementations that require manual stream management or custom hooks add complexity the interface is designed to avoid.

Bidirectional signaling. The transport should carry typed messages in both directions - tokens from server to client, and cancel, steer, or redirect instructions from client to server. Not raw TCP closes, but first-class channel messages.

Session persistence across reconnects. The transport should track message offsets and support catch-up on reconnect. Without offsets, a disconnected client either replays the entire generation or loses what arrived during the gap.

Ably AI Transport integrates with the Vercel AI SDK to add durable sessions, multi-device sync, and bidirectional control to your chat application. Visit the Ably AI Transport overview, read the documentation, or sign up free

Ready to build? Get started with Vercel AI SDK.

Sources: AI SDK UI Transport documentation; AI SDK 5 announcement (July 31, 2025, Lars Grammel, Nico Albanese, Vercel); Vercel KB: WebSocket support; ChatTransport interface source; DefaultChatTransport source; DirectChatTransport reference.