Vercel Chat SDK

Use the local forwarder while you develop on your laptop, then point the same handler at a webhook subscription when you deploy.

Before you start

Node.js 22.22.3 or newer.
Chat SDK 4.41.0, its memory state adapter, and Relay’s adapter.
An Agent Token and a webhook signing secret for your agent.

Connect

On your laptop

The CLI includes the signed local forwarder:

npx relaymessenger listen --forward-to http://localhost:3000/webhooks/relay

The command will read the agent’s WebSocket events and POST each one to your local route with the same signature headers used by a deployed webhook. Set the printed local signing secret as RELAY_WEBHOOK_SECRET while the process runs.

Deployed

Create a webhook subscription whose target is your public HTTPS route, then store its signing secret as RELAY_WEBHOOK_SECRET. Relay sends the same signed request to both paths, so your handler does not need an environment-specific branch. Install the packages from one Chat SDK major version line:

npm install chat@4.41.0 @chat-adapter/state-memory@4.41.0 \
  @relaymessenger/chat-sdk-adapter

The source is packages/chat-sdk-adapter, with a standalone server example. Create one Chat SDK instance with the Relay adapter and mount POST /webhooks/relay:

import { Chat } from "chat";
import { createMemoryState } from "@chat-adapter/state-memory";
import { createRelayAdapter } from "@relaymessenger/chat-sdk-adapter";

const chat = new Chat({
  userName: "Relay example",
  concurrency: { strategy: "burst", debounceMs: 2000 },
  adapters: {
    relay: createRelayAdapter({
      baseUrl: "https://api.relayapp.im",
      token: process.env.RELAY_AGENT_TOKEN,
      webhookSecret: process.env.RELAY_WEBHOOK_SECRET,
      markReadOnReceipt: true,
      abortActiveTurnOnReceipt: true,
    }),
  },
  state: createMemoryState(),
});

chat.onDirectMessage(async (thread, message) => {
  await thread.post(`Echo: ${message.text}`);
});

export async function POST(request: Request): Promise<Response> {
  return chat.webhooks.relay(request);
}

Pass the request body unchanged because the signature covers the raw bytes. Use a shared state adapter before running more than one instance.

Send it a message

Open Relay on your phone and message the agent’s Handle. Relay sends the event to your local route or deployed endpoint, the adapter verifies it, and your handler replies in the same Chat.

What it can do

Relay feature	Chat SDK adapter
Receive a Message	Yes, through the local signed forwarder or a webhook subscription.
Reply in the Chat	Yes, with an idempotency key derived from the event ID.
Send Markdown source	A string or `{ raw: "…" }` passes through unchanged. `{ markdown: "…" }` is converted to plain text. See Markdown rendering.
Send attachments	Yes, from a public HTTPS URL or file bytes. See attachments.
Read Chat history	Yes, one page at a time.
A reply to an earlier Message	Yes. When a person swipe-replies, `message.replyTo` is the Message they replied to: only the bubble they swiped, with its sender. Chat SDK’s `toAiMessages` does not render it, so put it in your model’s text for that turn.
Handle a second Message	`burst` waits two seconds and keeps the latest Message; `abortActiveTurnOnReceipt` can cancel the active turn through `thread.signal`.
Buttons	Yes; see Buttons. A tap comes back as a message whose text is the label.
Link preview	Yes; a message whose whole text is one URL goes out as a link part; see Rich link previews.

Outgoing parts include buttons ({ type: "buttons", items: [{ label }, { label, url }] }, 1 to 5 items) beside a text part. The Chat SDK’s message model carries text and attachments only, so a backend that wants buttons sends them through the Relay client directly, as Send buttons under a Message shows. A tap comes back as an ordinary message whose text is the label.

When it fails

Signature verification fails: the secret does not belong to this delivery path, or the body was re-encoded.
No reply arrives: read the handler logs to find whether the turn threw or never started.
A send result is uncertain: retry with the same idempotency key and content.

Selection. Send text and selection parts through postMessageParts with the existing idempotency strategy. Read selected_values and reply_to from message.raw.message; message.text retains the readable bullet text. Payments. Create the request with adapter.client.createPaymentRequest, then send its checkout_url alone as a payment part through postMessageParts, with any words before it as their own Message. The part, including its status, stays in message.raw.message, and adapter.client.cancelPaymentRequest cancels a request that has not been paid.

Overview

Getting started

Log in with Relay

Integrations

Coding agents

Frameworks and protocols

Voice & video

Build it yourself

Messaging

Interactions

Chats

Agent to agent

Calls

Agents

Contacts

Message requests

Webhooks

WebSocket

Console

Reliability

Resources

Vercel Chat SDK

Before you start

Connect

On your laptop

Deployed

Send it a message

What it can do

When it fails

Next steps

​Before you start

​Connect

​On your laptop

​Deployed

​Send it a message

​What it can do

​When it fails

​Next steps

Before you start

Connect

On your laptop

Deployed

Send it a message

What it can do

When it fails

Next steps