Test a WebSocket client with a hosted mock

Create a mock and connect

Create a mock with empty HTTP routes and a websocket object. The response includes a WebSocket endpoint URL and management credentials. Mocks are private by default. Send the access token in the X-Access-Token handshake header. A browser on socket.help can also use its signed-in workspace session. For native browser clients on another site, explicitly enable public access and use synthetic data.

The CLI accepts the same JSON through socket-help mock create. With the TypeScript SDK, pass it to socket.createMock(config). Agents can call create_mock_api with the same fields, or use resource_request with kind mocks and action create.

curl https://socket.help/api/mocks \
  -H 'Content-Type: application/json' \
  -d '{"name":"Live updates","routes":[],"websocket":{"echo":true,"welcome":["ready"],"replies":[{"match":"ping","reply":"pong"}]}}'

# Save the returned credentials separately from the URL.
npx wscat -c "$ENDPOINT_URL" -H "X-Access-Token: $ACCESS_TOKEN"

Script replies and inspect traffic

Welcome messages are sent in order when a client connects. Replies match an exact text message. Unmatched text and binary messages echo by default. Set echo to false to ignore unmatched messages. Set delayMs to delay each scripted or echoed message by up to two seconds.

Set closeAfter to an object with a code and optional reason to close after the first reply. For a welcome-only script with echo off, it closes after the welcome messages. Change the script with PUT /api/mocks/{id}; the new script applies to new connections.

Use inspect_mock_api, socket.mockCalls or GET /api/mocks/{id}/calls to read connection, message and close events. Use the workspace credential or the management token. Binary messages are recorded by size; text previews are retained. Standard mock expiry, sharing and quotas apply. Each connection lasts up to one minute, with up to 100 incoming frames and 16 KiB per message.

Test a public WebSocket endpoint

Use the WebSocket tester to see the upgrade status, negotiated subprotocol, response messages and close code. The tester listens for up to three seconds or ten messages. Private addresses and redirects are blocked. Send one text or base64 test message from an approved workspace. A mock access token goes in the separate secret option and requires WSS.

Agents use run_tool with toolId network-websocket-tester. HTTP clients send input and options to POST /api/tools/network-websocket-tester/run. The SDK uses socket.run with the same tool ID and options.

printf '%s' "$ENDPOINT_URL" | socket-help run network-websocket-tester --options '{"body":"ping"}'