Chat SDK

Add Relay to a Chat SDK bot by putting one adapter in its adapters map. @relaymessenger/chat-sdk-adapter receives signed message.received webhooks, hands each one to your existing handlers as a Chat SDK message, and commits replies through POST /v1/messages. A bot that already answers on other platforms reaches Relay users without a second codebase. Prerequisites:

An agent and its Agent Token. See Create and connect an agent.
A registered webhook with its signing secret. See Webhooks.
A Chat SDK app. chat is a peer dependency, version ^4.38.0.

The adapter validates both secrets while the module is evaluated, so on Cloudflare Workers a missing or malformed value fails the deploy rather than the first request.

The adapter is published as @relaymessenger/chat-sdk-adapter and developed in the public relaymessenger/Relay-SDK repository under integrations/chat-sdk.

Quickstart

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

app/api/relay/route.ts

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

const chat = new Chat({
  userName: "My Agent",
  adapters: {
    relay: createRelayAdapter({
      token: process.env.RELAY_AGENT_TOKEN!,
      webhookSecret: process.env.RELAY_WEBHOOK_SECRET!,
    }),
  },
  state: createMemoryState(),
});

chat.onNewMention(async (thread, message) => {
  await thread.subscribe();
  await thread.post({ markdown: `You said: ${message.text}` });
});

export const POST = (request: Request) => chat.webhooks.relay(request);

Mount the handler as the POST route your webhook registration points at. The adapter ships no runtime dependencies. It scopes each turn with AsyncLocalStorage, so run it on Node or on a runtime with Node compatibility enabled, such as Cloudflare Workers with nodejs_compat.

A Relay conversation arrives as a Chat SDK thread whose id is relay:<chat_id>. Handlers you already wrote for other platforms run unchanged.

What the adapter enforces

Each row is a contract from these docs that the adapter implements for you.

Contract	Adapter behavior
Signature verification	Standard Webhooks HMAC over the exact raw body. An unsigned, tampered, or stale request gets `401` before its content is read
At-least-once delivery	The `event_id` is claimed before your handler runs, so two redeliveries racing each other cannot both dispatch, and released if the handler throws so a failed turn is redelivered
Idempotent sends	Every send carries a `message_id` derived from the inbound `event_id` and the send’s position in the turn, and from nothing else. A retry carrying the same id replays the stored message
Group conversations	The agent is an ordinary member, so every message in the group reaches your handlers and a reply is an ordinary send
Message size	A reply longer than one text part becomes more parts of the same message. A split consumes the whitespace it lands on
Event compatibility	Reaction, receipt, and conversation events acknowledge `200` without dispatch, so new event types never break your route

The dedupe window is a bounded set in memory in one process. A restart, or a second instance behind the same webhook URL, has no claim to lose and dispatches the event again. The idempotency key is what makes that second dispatch harmless.

Configuration

Option	Description	Default
`token`	Agent Token used for every send	`RELAY_AGENT_TOKEN`
`webhookSecret`	Signing secret from webhook registration	`RELAY_WEBHOOK_SECRET`
`userName`	Display name the Chat SDK shows for the bot	`Relay Agent`
`agentId`	This agent’s `agt_` id, when you know it	unset
`baseUrl`	API origin	`https://api.relayapp.im`
`toleranceSeconds`	Allowed `webhook-timestamp` skew	`300`
`dedupeWindow`	How many handled `event_id` values to remember	`4096`

What each operation does on Relay

	Chat SDK operation	Relay
✅	`postMessage`	`POST /v1/messages`
✅	`addReaction`, `removeReaction`	Reactions on a message
✅	`startTyping`	Typing indicator, ephemeral and never stored
✅	`markAsRead`	Read receipt for the conversation
✅	`fetchMessages`, `fetchThread`	Conversation history, paged backwards
✅	`getUser`	The user’s profile, scoped to a shared conversation
✅	Attachments, both directions	Attachments and voice memos
⚠️	`stream`	Buffered, then sent as one finished message
❌	`editMessage`	A committed message is immutable, so this throws `NotImplementedError`
❌	`deleteMessage`	A committed message cannot be unsent, so this throws `NotImplementedError`
❌	`fetchMessages({ direction: "forward" })`	The history route pages backwards only, so this throws `NotImplementedError`
❌	`openDM`	A conversation starts when a person adds the agent
❌	Cards	Delivered as fallback text, because Relay has no interactive card surface

Set streaming: false where your host offers the choice. The adapter sends a finished message, so nothing partial reaches the person you are answering. See Sending messages for the send contract it uses.

Formatting

Relay does not render Markdown. A text part carries plain text plus styles runs with UTF-16 offsets, and clients draw the runs. The adapter flattens { markdown } and { ast } to the text a person reads and carries emphasis across as style ranges.

Markdown	Relay style
`strong`	`bold`
`emphasis`	`italic`
`delete`	`strikethrough`

Constructs Relay has no style for keep their information in the text. A link whose label differs from its target renders as label (url), a blockquote keeps its > prefix, a list keeps its markers, inline and fenced code keep their backticks, and a table is flattened to one text line per row.

Next steps

Webhooks for registration, verification, and secret rotation
Sending messages for parts, styles, and idempotency
Group conversations for how an agent takes part in a group
Integrations for every way to connect an agent

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Quickstart

What the adapter enforces

Configuration

What each operation does on Relay

Formatting

Next steps

​Quickstart

​What the adapter enforces

​Configuration

​What each operation does on Relay

​Formatting

​Next steps

Quickstart

What the adapter enforces

Configuration

What each operation does on Relay

Formatting

Next steps