Cloudflare Agents

There are two ways to answer Relay conversations on Cloudflare, and which one you want depends on whether you already have an agent.

You have	Do this
An agent on Think, Cloudflare’s chat agent framework	Add Relay as a channel, next to Telegram and Slack
No agent yet, or an agent whose only job is Relay	Deploy the starter on the Agents SDK

Prerequisites for both:

An agent and its Agent Token. See Create and connect an agent.
A Cloudflare account. Both paths deploy with wrangler.
Node 20 or newer.

Add Relay as a channel to a Think agent

Think builds a channel by wrapping a Chat SDK adapter in messengerChannel(). That is how its own Telegram channel is built. Relay publishes a Chat SDK adapter, so Relay is one more channel: your agent, its tools, and its memory stay exactly as they are.

Install the adapter

npm install @cloudflare/think @relaymessenger/chat-sdk-adapter agents ai chat

On Workers, the adapter must be 0.2.1 or newer.

Declare the channel

The channel id names the route. Called relay, it serves POST /messengers/relay/webhook.

src/index.ts

import { Think, messengerChannel } from "@cloudflare/think";
import { chatSdkMessenger } from "@cloudflare/think/messengers";
import {
  createRelayAdapter,
  verifyWebhookSignature,
} from "@relaymessenger/chat-sdk-adapter";

function relayWebhookVerifier(secret: string) {
  return async (request: Request): Promise<boolean> => {
    try {
      await verifyWebhookSignature({
        secret,
        payload: await request.text(),
        headers: {
          "webhook-id": request.headers.get("webhook-id"),
          "webhook-timestamp": request.headers.get("webhook-timestamp"),
          "webhook-signature": request.headers.get("webhook-signature"),
        },
      });
      return true;
    } catch {
      return false;
    }
  };
}

export class MyAgent extends Think<Env> {
  configureChannels() {
    return {
      relay: messengerChannel(
        chatSdkMessenger({
          adapter: createRelayAdapter({
            token: this.env.RELAY_AGENT_TOKEN,
            webhookSecret: this.env.RELAY_WEBHOOK_SECRET,
          }),
          provider: "relay",
          userName: "Relay Agent",
          verifyWebhook: relayWebhookVerifier(this.env.RELAY_WEBHOOK_SECRET),
        }),
      ),
    };
  }
}

Set the secrets and deploy

npx wrangler secret put RELAY_AGENT_TOKEN
npx wrangler deploy

Set the webhook receiver

curl -sS -X POST "https://api.relayapp.im/v1/webhooks" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://<your-worker>.workers.dev/messengers/relay/webhook", "events": ["message.received"]}'

Save signing_secret from the response, then set it:

npx wrangler secret put RELAY_WEBHOOK_SECRET

Message your agent

Open Relay, find your agent, and send it a message. It replies.

An unsigned or forged delivery to the webhook route returns 401 before Think parses anything.

Think owns the parts a channel needs, so you write none of them.

Think handles	How
The webhook route	The channel id becomes `/messengers/<id>/webhook`
Refusing forged deliveries	`verifyWebhook` runs before any parsing. Every custom messenger must supply one, or opt out explicitly
One conversation per thread	Think fans out to a sub-agent per Chat SDK thread, and a Relay thread is one conversation
Surviving a restart mid-reply	The reply runs in a durable fiber, which Think replays or closes with its interruption message rather than risking a duplicate
Bursts	The Chat SDK debounces a run of messages into one turn

Two Relay rules shape what arrives on the other end. One send is one message, so the adapter buffers a streamed turn and posts the finished text once instead of editing a draft bubble into place. In a group, the agent is an ordinary member: it receives every message from the sequence it joined at, and each reply is an ordinary send.

A runnable version of this is examples/think-channel in the starter repository.

Deploy the starter

Deploy relay-agent-starter to answer Relay conversations from a Cloudflare Agent. Each conversation gets its own agent instance, its own SQLite ledger, and its own alarm, so a reply survives an evicted isolate. Replace one function with your model call and it is your agent.

The starter is developed in the public relaymessenger/relay-agent-starter repository. It depends on Cloudflare’s agents package and nothing of Relay’s own beyond the HTTPS API documented on this site.

Scaffold or deploy the starter

Use the one-click deploy:Deploy to CloudflareOr scaffold locally, then deploy:

npm create cloudflare@latest -- --template relaymessenger/relay-agent-starter
npm install
npx wrangler deploy

Note the deployed URL. It looks like https://relay-agent.<your-subdomain>.workers.dev.

Never add --accept-defaults to the scaffold command. That flag ignores --template, scaffolds a hello-world Worker, and still prints success.

Set the Agent Token

The deploy button prompts for it. Locally:

npx wrangler secret put RELAY_AGENT_TOKEN

Set the webhook receiver

Point Relay at /webhooks/relay on the deployed Worker:

curl -sS -X POST "https://api.relayapp.im/v1/webhooks" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://relay-agent.<your-subdomain>.workers.dev/webhooks/relay", "events": ["message.received"]}'

Save signing_secret from the response. Relay never returns it again.

Set the signing secret and redeploy

npx wrangler secret put RELAY_WEBHOOK_SECRET
npx wrangler deploy

Message your agent

Open Relay, find your agent, and send it a message. It replies.

GET /healthz on the Worker returns {"ok":true} when it is up.

What it uses from the Agents SDK

The starter is a normal Cloudflare Agents project. RelayConversationAgent extends the SDK’s Agent class, and each row below is a stock part of the agents package doing the job it was built for.

SDK surface	Where	What it does here
`class ... extends Agent<Env, State>`	`src/agent.ts`	One instance per conversation
`initialState`, `setState()`	`src/agent.ts`	Last event, last reply, cached handle
`this.sql`	`src/agent.ts`	The turn ledger, in the instance’s own SQLite
`this.schedule(delay, callback, payload)`	`src/agent.ts`	The alarm that drives the reply
`onStart()`	`src/agent.ts`	Creates tables, sweeps old rows, re-arms stranded turns
`onRequest(request)`	`src/agent.ts`	Receives the verified event from the Worker
`getAgentByName(namespace, name)`	`src/index.ts`	Routes each conversation to its own instance
`new_sqlite_classes` migration	`wrangler.jsonc`	Gives the class its SQLite storage

The instance name is a digest of chat_id, so every event for one thread reaches one object and one ledger.

The starter serves explicit routes only, with no routeAgentRequest fallthrough. That helper’s default /agents/<binding>/<name> shape includes an unauthenticated WebSocket that syncs agent state to any caller. Keep the fallthrough out unless you are authenticating it yourself.

What the starter handles for you

Each row is a contract from these docs that the starter implements.

Contract	Starter behavior
Signature verification	Standard Webhooks HMAC over the exact raw body, checked before anything parses it. An unsigned, tampered, or stale request gets `401`
At-least-once delivery	`202` is returned only after the ledger row and the alarm both exist. Anything earlier returns `5xx`, so Relay redelivers rather than dropping the reply
One reply per user turn	Each send arrives as one `message.received` event. Events that land inside a two second window collect into a turn, and the turn gets one reply
Idempotent sends	The reply’s `message_id` carries a digest of the reply itself, so a retry writing the same words replays the stored message and a retry writing different words mints a new id instead of taking `409 idempotency_conflict`
Read receipts and typing	The message is marked read and typing starts before model work, so the sender sees Read while they wait
Surviving eviction	Replies are armed with `schedule()`, which sets a Durable Object alarm and wakes an evicted instance on its own. `queue()` would strand the reply
Retries	A failed turn backs off to a ceiling of fifteen minutes across six attempts. A `4xx` from Relay is terminal and is not retried
Event compatibility	Any event that is not a user `message.received` is acknowledged and dropped, so a new event type never breaks the Worker

The ledger stores identifiers only. Message text is re-read from Relay at reply time rather than parked in agent storage.

Write your agent

Everything you change lives in one function, generateReply at the bottom of src/agent.ts:

src/agent.ts

async generateReply(text: string, mediaCount: number, handle: string): Promise<string> {
  return `@${handle} here. You said: ${text}`;
}

text is the whole user turn, with the messages of a burst joined back in order. mediaCount is how many media parts came with it, for a model that cannot open them yet. Call any model from there. A Workers AI example is commented directly above the function and needs no extra secrets: add the ai binding to wrangler.jsonc, uncomment AI in src/env.ts, and swap the return.

Keep the call inside the Worker CPU budget. Longer work belongs behind another schedule() call, which is the same alarm mechanism the reply already uses.

Secrets

Secret	Where it comes from
`RELAY_AGENT_TOKEN`	The Agent Token from the Relay app. Relay shows it once
`RELAY_WEBHOOK_SECRET`	`signing_secret` from `POST /v1/webhooks`. Relay never returns it again

RELAY_API_ORIGIN is a plain var, already set to https://api.relayapp.im.

Running it as a plain Worker

The starter needs the Agents SDK, because the ledger, the state, and the alarm are the SDK’s. If you want a Relay backend with none of that, answer the webhook from any HTTPS route you already run and send replies with POST /v1/messages. Webhooks has the verification steps. You then own the redelivery, idempotency, and turn coalescing this page’s table lists.

Next steps

Webhooks for registration, verification, and secret rotation
Sending messages for every part type beyond text
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

Cloudflare Agents

Add Relay as a channel to a Think agent

Deploy the starter

What it uses from the Agents SDK

What the starter handles for you

Write your agent

Secrets

Running it as a plain Worker

Next steps

​Add Relay as a channel to a Think agent

​Deploy the starter

​What it uses from the Agents SDK

​What the starter handles for you

​Write your agent

​Secrets

​Running it as a plain Worker

​Next steps

Add Relay as a channel to a Think agent

Deploy the starter

What it uses from the Agents SDK

What the starter handles for you

Write your agent

Secrets

Running it as a plain Worker

Next steps