Quickstart

Create an agent in Relay and save the Agent Token shown once. Relay sends events to your HTTPS endpoint; your backend sends messages back through the REST API.

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

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

Relay returns the signing secret exactly once:

{
  "webhook": {
    "id": "wh_01JZWEBHOOK",
    "url": "https://agent.example/webhooks/relay",
    "events": ["message.received", "message.edited", "message.unsent", "conversation.added", "conversation.updated", "conversation.removed", "reaction.added", "reaction.removed", "message.delivered", "message.read", "group.invite.completed", "group.invite.expired"],
    "enabled": true,
    "secret_prefix": "whsec_MfKQ9r8G…",
    "created_at": "2026-07-15T20:00:00.000Z",
    "updated_at": "2026-07-15T20:00:00.000Z"
  },
  "signing_secret": "whsec_..."
}

Store the secret in your secret manager. It is not returned by list or update requests.

Receive and verify the signed event

Relay sends the event envelope as the raw JSON request body with webhook-id, webhook-timestamp, and webhook-signature headers. Verify the signature before parsing the body, reject timestamps older than five minutes, durably enqueue the event, and return a 2xx quickly.

{
  "event_id": "evt_01JZE9M2XW",
  "event_type": "message.received",
  "agent_id": "agt_01JZRELAY",
  "created_at": "2026-07-12T01:21:03.000Z",
  "data": {
    "message": {
      "id": "msg_01JZM3T8AH",
      "conversation_id": "cnv_01JZC7K4RQ",
      "sequence": 1,
      "sender": { "kind": "user", "id": "usr_01JZU1F0BD" },
      "parts": [{ "part_index": 0, "type": "text", "text": "What time works tomorrow?" }],
      "reply_to": null,
      "fallback_text": "What time works tomorrow?",
      "status": "sent",
      "created_at": "2026-07-12T01:21:03.000Z"
    }
  }
}

Delivery is at least once. Deduplicate with event_id.

Derive the Idempotency-Key from the incoming event_id so retries cannot create a second reply.

curl -sS -X POST "$RELAY_API_URL/v1/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-evt_01JZE9M2XW" \
  -d '{
    "conversation_id": "cnv_01JZC7K4RQ",
    "parts": [{ "type": "text", "text": "Tomorrow at 2:00 PM works." }],
    "reply_to": { "message_id": "msg_01JZM3T8AH", "part_index": 0 }
  }'

Relay returns 202 Accepted with the canonical message.

Next, read Webhooks for verification, retries, rotation, and event filtering. Then connect the same handler your existing channels already use.

Overview

Get started

Messages

Message components

Conversations

Webhooks & events

Reference

Next steps

​Next steps

Next steps