Relay

Relay v1

Use the locked Relay v1 contract instead of remembered examples.

Ground truth

1. Read the locked source record.
2. Read contracts/relay-v1-openapi.yaml from the public Relay-SDK repository at api.public_source.commit in the lock, and verify its hash against api.openapi_sha256. The Server commit records the contract's origin; private Server access is not required. If the public copy and the lock disagree, report the stale source.
3. Read the relevant guide and implementation evidence when it is available in the workspace.
4. Use the bundled Relay docs MCP to find material, not to override the locked OpenAPI. If a search result disagrees with the lock, report the result as stale and do not use its route, field, event, or package.
5. Prefer @relaymessenger/sdk for TypeScript and show equivalent cURL when teaching an HTTP operation.

Never invent a route, resource, field, event, package, or migration. Label unproved behavior unknown.

Agent event path

Relay derives an agent's event path from saved Webhook subscriptions:

There is no transport mode or toggle. A socket upgrade while any subscription exists returns HTTP 409. Creating the first subscription closes connected agent sockets; deleting the final subscription makes the WebSocket path available. Read Agent events before changing subscriptions or connection code.

Core model

Relay uses Contacts, Handles, Chats, Messages, parts, Attachments, reactions, and per-recipient delivery state. A Contact has kind: "user" | "agent".

For details, read only the reference needed:

• Messaging for sends, parts, Attachments, replies, reactions, mentions, and receipts.
• Chats and Contacts for groups, membership periods, Add requests, blocks, Contact Cards, and history.
• Agent events for Webhooks, WebSocket, ACK, path changes, FULL sync, typing, retries, and trace_id.
• SDK and authentication for Agent Tokens, environments, the public TypeScript surface, retries, and errors.

Verification

Prove the integration at its real boundaries:

• signature verification over raw webhook bytes;
• durable event commit before webhook 2xx or WebSocket ACK;
• duplicate event_id handling;
• idempotent REST replies;
• reconnect/replay and FULL-sync behavior for WebSocket consumers;
• first-subscription and last-subscription path changes;
• Webhook SSRF and redirect handling;
• direct and group Message behavior relevant to the product.

Keep Agent Tokens in trusted backend storage. Use a staging API root only with credentials created in that same environment.