Vercel integration API

Open in

The Vercel integration provides a pre-built codec and transport factories for the Vercel AI SDK. It maps Vercel's UIMessageChunk events to UIMessage objects, so you can use AI Transport with useChat without writing a custom codec.

Entry points

Entry point	Import path	Contents
Vercel	`@ably/ai-transport/vercel`	`UIMessageCodec`, `createClientTransport`, `createServerTransport`
Vercel React	`@ably/ai-transport/vercel/react`	`useChatTransport`, `useMessageSync`

UIMessageCodec

A pre-built Codec<UIMessageChunk, UIMessage> for the Vercel AI SDK. It handles encoding and decoding of Vercel's message types through Ably channels.

JavaScript

import { UIMessageCodec } from '@ably/ai-transport/vercel'

You do not need to use UIMessageCodec directly if you use the Vercel-specific transport factories or React hooks, as they bind the codec automatically.

createClientTransport

A pre-bound version of the core createClientTransport that omits the codec option. The codec is set to UIMessageCodec.

JavaScript

import { createClientTransport } from '@ably/ai-transport/vercel'

function createClientTransport(options: VercelClientTransportOptions): ClientTransport

VercelClientTransportOptions

Identical to ClientTransportOptions but without the codec property.

Property	Required	Type	Description
channel	required	`Ably.RealtimeChannel`	The Ably channel for the session.
clientId	optional	`string`	The client ID for this transport instance.
api	optional	`string`	URL of the API endpoint.
headers	optional	`Record<string, string>`	Additional HTTP headers.
body	optional	`Record<string, unknown>`	Additional request body fields.
credentials	optional	`RequestCredentials`	Credentials mode for fetch.
fetch	optional	`typeof fetch`	Custom fetch implementation.
messages	optional	`UIMessage[]`	Pre-loaded messages for history.
logger	optional	`Logger`	Logger instance.

createServerTransport

A pre-bound version of the core createServerTransport that omits the codec option.

JavaScript

import { createServerTransport } from '@ably/ai-transport/vercel'

function createServerTransport(options: VercelServerTransportOptions): ServerTransport

VercelServerTransportOptions

Identical to ServerTransportOptions but without the codec property.

Property	Required	Type	Description
channel	required	`Ably.RealtimeChannel`	The Ably channel for the session.
logger	optional	`Logger`	Logger instance.
onError	optional	`(error: ErrorInfo) => void`	Callback for transport-level errors.

createChatTransport

Create a ChatTransport from a ClientTransport. The ChatTransport is the adapter that plugs into Vercel's useChat hook.

JavaScript

import { createChatTransport } from '@ably/ai-transport/vercel'

function createChatTransport(transport: ClientTransport, options?: ChatTransportOptions): ChatTransport

In most cases you will use the useChatTransport hook instead of calling this factory directly.

useChatTransport

React hook that creates a ChatTransport for use with Vercel's useChat. Accepts either a VercelClientTransportOptions object (creates a transport internally) or an existing ClientTransport instance. Both forms accept an optional second argument for ChatTransportOptions.

JavaScript

import { useChatTransport } from '@ably/ai-transport/vercel/react'

function useChatTransport(options: VercelClientTransportOptions, chatOptions?: ChatTransportOptions): ChatTransport
function useChatTransport(transport: ClientTransport, chatOptions?: ChatTransportOptions): ChatTransport

When you pass VercelClientTransportOptions, the hook creates a ClientTransport internally with the codec pre-bound to UIMessageCodec. When you pass an existing ClientTransport, it wraps that instance as a ChatTransport without creating a new transport. Use the second form when you need direct access to the ClientTransport for features like active turn tracking, useMessageSync, or cancellation.

See the React hooks reference for full usage examples.

ChatTransportOptions

Optional second argument to useChatTransport and createChatTransport for customizing request behavior.

Property	Required	Type	Description
prepareSendMessagesRequest	optional	`(context: SendMessagesRequestContext) => { body?: Record<string, unknown>; headers?: Record<string, string> }`	Hook to customize the HTTP POST body and headers before sending to the API. Receives conversation context including history, new messages, and trigger type.