Quickstart

Receive one signed message event, mark it Read, and send one reply. Verify the token first. Then pick a receive path:

Where the backend runs	Receive path
Laptop or any host without a public URL	Long poll. No tunnel
Public HTTPS server	Webhook

Both transports read the same durable event log, so an agent can run either or both. Deduplicate on event_id whichever you pick.

Before you start

You need:

Requirement	Where it comes from	Needed for
Agent Token	Relay shows it once when you create an agent	Both paths
Public HTTPS endpoint	Your own hosting	Webhook path only
Signing secret	Relay returns it once when you register the webhook	Webhook path only

Set the API origin and token:

export RELAY_API_URL="https://api.relayapp.im"
export RELAY_AGENT_TOKEN="rly_live_..."

Verify the Agent Token

curl -sS "$RELAY_API_URL/v1/agents/me" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

Relay returns the agent identity:

{
  "agent": {
    "id": "agt_01JZRELAY",
    "handle": "scheduler",
    "display_name": "Scheduler",
    "tagline": "Finds a time that works",
    "avatar_url": null,
    "visibility": "private",
    "owner_user_id": "usr_01JZU1F0BD",
    "created_at": "2026-08-10T12:00:00.000Z"
  }
}

Receive and reply

Long poll
Webhook

Poll for one event

GET /v1/events reads the agent’s durable event log past after. The request holds open up to timeout seconds and returns as soon as an event lands.

curl -sS "$RELAY_API_URL/v1/events?after=0&timeout=30&limit=100" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

While it waits, open the Relay app and message your agent. The poll returns the event:

{
  "events": [
    {
      "event_id": "evt_01JZE9M2XW",
      "sequence": 1,
      "event_type": "message.received",
      "agent_id": "agt_01JZRELAY",
      "chat_id": "cnv_01JZC7K4RQ",
      "created_at": "2026-08-10T12:00:00.000Z",
      "data": {
        "message": {
          "id": "msg_01JZM3T8AH",
          "chat_id": "cnv_01JZC7K4RQ",
          "sequence": 1,
          "parts": [
            { "part_index": 0, "type": "text", "text": "What time works tomorrow?" }
          ]
        }
      }
    }
  ],
  "next_cursor": 1,
  "latest": 1,
  "has_more": false
}

Mark Read and reply

Mark the exact inbound message Read before model or tool work.

curl -sS -X POST \
  "$RELAY_API_URL/v1/chats/cnv_01JZC7K4RQ/read" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message_id":"msg_01JZM3T8AH"}'

Typing is a separate, ephemeral signal. Start it while you work.

curl -sS -X POST \
  "$RELAY_API_URL/v1/chats/cnv_01JZC7K4RQ/typing" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"started":true}'

Mint the reply’s message_id before you send it. That id names the message and is the send’s idempotency key.

curl -sS -X POST "$RELAY_API_URL/v1/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg_01k1m4q9vn2r7t9b4c6qdh8xwy",
    "chat_id": "cnv_01JZC7K4RQ",
    "parts": [{ "type": "text", "text": "Tomorrow at 2:00 PM works." }]
  }'

Relay returns 202 Accepted with { message_id, message }: one send is one message. Stop typing after send, failure, or cancellation:

curl -sS -X POST \
  "$RELAY_API_URL/v1/chats/cnv_01JZC7K4RQ/typing" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"started":false}'

Poll again with the cursor

Pass the returned next_cursor as after on the next poll. The cursor acknowledges nothing and consumes nothing, so persist the events and the new cursor together and deduplicate on event_id.

curl -sS "$RELAY_API_URL/v1/events?after=1&timeout=30" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

That is the whole loop: poll, handle, persist the cursor, poll again. has_more tells you another page is already waiting. See Long polling for backoff and limits.

The fastest deployed path: the Cloudflare Workers starter ships these steps as a working backend.

curl -sS -X POST "$RELAY_API_URL/v1/webhooks" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://agent.example/webhooks/relay",
    "events": ["message.received"]
  }'

Save signing_secret. Relay never returns it again.

{
  "webhook": {
    "id": "wh_01JZWEBHOOK",
    "url": "https://agent.example/webhooks/relay",
    "events": ["message.received"],
    "enabled": true,
    "secret_prefix": "whsec_EXAMPL…",
    "created_at": "2026-08-10T12:00:00.000Z",
    "updated_at": "2026-08-10T12:00:00.000Z"
  },
  "signing_secret": "whsec_EXAMPLEKEYDONOTUSE0000000000000000"
}

Verify and store the event

Relay signs the exact request body with Standard Webhooks headers.

npm install standardwebhooks

import { Webhook } from "standardwebhooks";

const rawBody = await request.text();
const event = new Webhook(process.env.RELAY_SIGNING_SECRET!).verify(
  rawBody,
  {
    "webhook-id": request.headers.get("webhook-id") ?? "",
    "webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
    "webhook-signature": request.headers.get("webhook-signature") ?? "",
  },
);

Store the event before returning 2xx. Deduplicate on event_id.

{
  "event_id": "evt_01JZE9M2XW",
  "event_type": "message.received",
  "data": {
    "message": {
      "id": "msg_01JZM3T8AH",
      "chat_id": "cnv_01JZC7K4RQ",
      "sequence": 1,
      "parts": [
        { "part_index": 0, "type": "text", "text": "What time works tomorrow?" }
      ]
    }
  }
}

Mark Read and reply

Mark the exact inbound message Read before model or tool work.

curl -sS -X POST \
  "$RELAY_API_URL/v1/chats/cnv_01JZC7K4RQ/read" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message_id":"msg_01JZM3T8AH"}'

Typing is a separate, ephemeral signal. Start it while you work.

curl -sS -X POST \
  "$RELAY_API_URL/v1/chats/cnv_01JZC7K4RQ/typing" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"started":true}'

Mint the reply’s message_id before you send it. That id names the message and is the send’s idempotency key.

curl -sS -X POST "$RELAY_API_URL/v1/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg_01k1m4q9vn2r7t9b4c6qdh8xwy",
    "chat_id": "cnv_01JZC7K4RQ",
    "parts": [{ "type": "text", "text": "Tomorrow at 2:00 PM works." }]
  }'

Relay returns 202 Accepted with { message_id, message }: one send is one message. Stop typing after send, failure, or cancellation:

curl -sS -X POST \
  "$RELAY_API_URL/v1/chats/cnv_01JZC7K4RQ/typing" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"started":false}'

Failure and retry behavior

Failure	What to do
Invalid signature	Return `401`. Do not parse or process the event
Duplicate `event_id`	Return `2xx`. Do not run side effects again
Relay returns `429` or `5xx`	Retry with backoff and the same `message_id`
Relay returns another `4xx`	Fix the request or token before retrying
Your handler needs more than 10 seconds	Store the event, return `2xx`, then continue work

Want a coding agent to build the handler? Copy the prompt on the home page, or hand it the machine-readable contract.

Next steps

Long polling for the durable poll loop
Webhooks for signature rotation and delivery retries
Sending messages for every part type
Group conversations for threads with several participants
Errors for every retry rule

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Before you start

Verify the Agent Token

Receive and reply

Failure and retry behavior

Next steps

​Before you start

​Verify the Agent Token

​Receive and reply

​Failure and retry behavior

​Next steps

Before you start

Verify the Agent Token

Receive and reply

Failure and retry behavior

Next steps