Quickstart

Before you start

Requirement	Source
Agent Token	Relay shows it once when you create the agent
Public HTTPS endpoint	Your backend
Signing secret	Returned when you create the webhook subscription

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

Verify the token

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

Receive and reply

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"]
  }'

Store the returned signing_secret. The list and retrieve responses do not return its plaintext.

Verify and persist the event

Relay signs the raw request body with Standard Webhooks headers. Verify before parsing, insert event_id under a unique constraint, and return 2xx before model or tool work.

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") ?? "",
  },
);

The body is Linq’s v3 shape:

{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.received",
  "event_id": "evt_01m135vfepewek1yqy3p82yszs",
  "created_at": "2026-08-27T18:06:02.000Z",
  "trace_id": "8af9171a45022df2eb74ba4e4c83be0f",
  "partner_id": "agt_01jz9x4t2snbqe6m8v3kcyh7wd",
  "data": {
    "chat": {
      "id": "cnv_01JZC7K4RQ",
      "is_group": false,
      "owner_handle": {
        "id": "agt_01jz9x4t2snbqe6m8v3kcyh7wd",
        "handle": "scheduler",
        "is_me": true,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2026-08-27T18:00:00.000Z",
        "left_at": null
      },
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/guides/chats/chat-health#healthy",
        "updated_at": "2026-08-27T18:06:02.000Z"
      }
    },
    "id": "msg_01JZM3T8AH",
    "direction": "inbound",
    "sender_handle": {
      "id": "usr_01JZU1F0BD",
      "handle": "morrison",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-08-27T18:00:00.000Z",
      "left_at": null
    },
    "parts": [{ "type": "text", "value": "What time works tomorrow?" }],
    "effect": null,
    "reply_to": null,
    "sent_at": "2026-08-27T18:06:02.000Z",
    "delivered_at": null,
    "read_at": null,
    "service": "iMessage"
  }
}

Mark Read and show typing

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"}'

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}'

Send the reply

Mint the reply’s message_id before the first attempt and reuse it on retry.

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." }]
  }'

Stop typing after send, failure, or cancellation.

Failure and retry behavior

Failure	Action
Invalid signature	Return `401` and do not process the body
Duplicate `event_id`	Return `2xx` without repeating side effects
Relay returns `429` or `5xx`	Retry with backoff and the same `message_id`
Relay returns another `4xx`	Fix the request or token before retrying
Handler needs more than 10 seconds	Persist, return `2xx`, then continue

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Before you start

Verify the token

Receive and reply

Failure and retry behavior

Next steps

​Before you start

​Verify the token

​Receive and reply

​Failure and retry behavior

​Next steps

Before you start

Verify the token

Receive and reply

Failure and retry behavior

Next steps