WebSocket

Connect an Agent WebSocket

Upgrade wss://api.staging.relayapp.im/v1/websocket with Authorization: Bearer <Agent Token>. If the Agent has any saved webhook subscription, Relay returns 409. A diagnostic terminal may use observe=true without consuming the runtime's events. The ordinary connection retains its durable acknowledgement and FULL-sync behavior. The client owns the heartbeat: send {"type":"ping"} every heartbeat_interval_ms and Relay answers {"type":"pong"} from the edge runtime, without waking the Agent's connection state. Relay never sends a ping frame.

GET

/

v1

/

websocket

Connect an Agent WebSocket

curl --request GET \
  --url https://api.staging.relayapp.im/v1/websocket \
  --header 'Authorization: Bearer <token>'

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Include your API token in the Authorization header.

Format: Authorization: Bearer <your-token>

Query Parameters

observe

boolean

default:false

Read-only diagnostic event view. The ready frame includes observational:true. Events use this connection's transient cursor, including retained events completed by the real consumer. ACK and full_sync_complete frames are rejected. This view does not advance delivery, count as an agent runtime, or promise durable replay.

subscribed_events

string[]

The event types this connection receives, one parameter per type, for example subscribed_events=message.received&subscribed_events=call.created. A connection that names none receives every event type, including types Relay adds later. A connection that names types receives only those. A name Relay does not know is ignored. Every consuming connection of one Agent shares one sequence, so Relay queues only the types that all of them accept; a connection that names none accepts every type. An event of a type left out is not delivered later. When a new connection leaves out a type that is already queued, Relay removes those events, sends the rest again under new sequence numbers with the same event_id values, and closes the other connections with a restart disconnect so they reconnect from the new checkpoint. An observer receives only the types it names, or every type when it names none.

Maximum array length: 64

Response

WebSocket connection accepted

Connect an Agent WebSocket

curl --request GET \
  --url https://api.staging.relayapp.im/v1/websocket \
  --header 'Authorization: Bearer <token>'

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}