WebSocket Client
Rostyman includes a full-featured WebSocket client for testing real-time APIs. It supports text, JSON, XML, and HTML message formats, query parameter injection, custom headers, per-connection settings, and a searchable message log — all within a dedicated tab that persists independently from HTTP request tabs.
Opening a WebSocket Tab
Click + New Tab and select WebSocket, or open a saved WebSocket request from the sidebar. Each tab maintains its own connection, message history, and settings independently.
The URL Bar
The URL bar runs across the top of the tab and accepts any valid WebSocket URL:
ws://localhost:3000
wss://echo.websocket.org
wss://api.example.com/live?room={{roomId}}
ws://— unencrypted WebSocket connectionwss://— TLS-encrypted WebSocket connection
Environment variables are supported anywhere in the URL using {{variableName}} syntax. Variables are resolved from the active environment of the tab's collection at connect time, so the raw variable name is stored but the resolved value is what actually reaches the server.
The URL bar uses the same smart input component as HTTP requests, including variable highlighting: known variables appear highlighted in green, undefined variables in red.
Connection Status Indicator
A colored pill badge in the URL bar shows the current connection state at all times:
| Status | Color | Meaning |
|---|---|---|
| Disconnected | Gray | No active connection |
| Connecting | Amber/Yellow | Handshake in progress |
| Connected | Green | Connection is open and ready |
| Error | Red | Connection failed or was closed with an error |
When connected, a live elapsed timer (e.g., 12s, 1m 4s) appears next to the status badge, counting up from the moment the connection opened.
Environment Selector
The Environment dropdown sits in the URL bar row and controls which environment's variables are used to resolve {{variables}} in the URL, query parameters, headers, and message body. This is a collection-level selector — it sets the active environment for the entire collection, not just this tab.
Connect and Disconnect
Click Connect (or press Enter in the URL bar) to open the connection. The button shows a plug icon and is styled in the accent color.
Once connected, the same button changes to Disconnect (red, with an unplug icon). Clicking it closes the connection immediately. The message log is preserved in the tab after disconnecting — messages are not cleared when the connection closes.
If the connection fails (network error, refused, TLS error, etc.), the status changes to Error and a system message appears in the log with the error detail.
Sub-tabs
Below the URL bar, four sub-tabs control what you configure before connecting:
Message Tab
The Message tab is where you compose the message to send over the open connection.
Format selector — A dropdown in the bottom toolbar selects the message format:
| Format | Monaco Language | Use case |
|---|---|---|
| TEXT | plaintext | Raw string messages, binary-safe text |
| JSON | json | Structured JSON payloads with syntax highlighting |
| XML | xml | XML documents with tag highlighting |
| HTML | html | HTML fragments |
The Monaco editor's language mode switches to match the selected format, giving you syntax highlighting, bracket matching, and code folding for JSON, XML, and HTML.
Message editor — A full Monaco editor fills the upper portion of the tab. It supports:
- Syntax highlighting matched to the selected format
- Line numbers
- Word wrap
{{variable}}interpolation (variables are resolved at send time, not while typing)
Beautify — A Beautify button (and { } shortcut button for JSON) in the toolbar auto-formats the message body. For JSON, it runs JSON.parse followed by JSON.stringify with 2-space indentation. Beautify is only active when the format is set to JSON.
Send button — Click Send or press Enter (when focus is in the editor area) to transmit the current message. The button is disabled and dimmed if there is no active connection or the message body is empty. Sent messages appear immediately in the Message Log below.
Params Tab
The Params tab manages query parameters that are appended to the WebSocket URL during the HTTP upgrade handshake. These parameters are sent as part of the initial GET request and are visible to the server in request.query.
| Column | Description |
|---|---|
| Enabled checkbox | Toggle a parameter on or off without deleting it |
| Key | Parameter name (supports {{variables}}) |
| Value | Parameter value (supports {{variables}}) |
Parameters are serialized and appended to the URL in the format ?key=value&key2=value2. If the URL already contains a query string, parameters are appended with &.
Add a row by clicking + Add Parameter. Remove a row with the × button. All changes are reflected in the resolved URL used at connect time, but the raw URL field in the URL bar is not modified.
Headers Tab
The Headers tab contains two sections:
Auto-Generated Headers (read-only)
The WebSocket protocol requires a specific set of HTTP headers on the upgrade request. Rostyman generates these automatically and displays them for reference. They cannot be edited. An eye/hide toggle collapses this section if you prefer not to see it.
| Header | Value |
|---|---|
Host | Calculated at runtime from the URL |
Connection | Upgrade |
Upgrade | websocket |
Sec-WebSocket-Key | Random base64 nonce, calculated at runtime |
Sec-WebSocket-Version | 13 |
Sec-WebSocket-Extensions | permessage-deflate; client_max_window_bits |
Hovering the ⓘ info icon next to any auto-generated header shows a popover explaining what the header does and why it is required by the WebSocket protocol.
Custom Headers
Add your own headers that are merged with the auto-generated set and sent on the upgrade request:
| Column | Description |
|---|---|
| Enabled checkbox | Toggle a header without deleting it |
| Key | Header name — supports {{variables}} with live highlighting |
| Value | Header value — supports {{variables}} |
| × | Remove the row |
Common use cases: Authorization: Bearer {{token}}, X-Tenant-Id: acme, Cookie: session={{sessionId}}.
Toolbar shortcuts for the custom headers section:
- Copy All — copies all custom headers as a tab-separated key-value list
- Paste — parses clipboard content and appends rows
- Clear All — removes all custom header rows
Settings Tab
The Settings tab provides per-connection configuration options. These settings take effect on the next Connect — changing them does not affect an already-open connection.
| Setting | Type | Default | Description |
|---|---|---|---|
| SSL/TLS Verification | Toggle | Off | When enabled, the server's TLS certificate is verified against trusted CAs. Disable for self-signed certificates in development. |
| Handshake Timeout | Number (ms) | 0 | Maximum time to wait for the upgrade handshake to complete. 0 means no timeout. |
| Reconnect Attempts | Number | 0 | How many times to automatically reconnect if the connection drops unexpectedly. 0 disables auto-reconnect. |
| Reconnect Interval | Number (ms) | 5000 | How long to wait between reconnect attempts. |
| Max Message Size | Number (MB) | 10 | Maximum size of a single received message. Messages larger than this are dropped. 0 means unlimited. |
Message Log Panel
The Message Log is a persistent panel at the bottom of the WebSocket tab. It shows every message for the current session in chronological order (oldest at top, newest at bottom) and auto-scrolls to the latest entry. Scroll up at any time to review earlier messages.
Collapse / Expand
A chevron button on the left of the log header toggles the log between collapsed (just the header bar) and expanded views. This is useful when you want to give more vertical space to the message editor.
Filter Buttons
Four filter buttons narrow the log to a specific message direction:
| Filter | What it shows |
|---|---|
| All | Every message in the session |
| Sent | Only messages you sent |
| Received | Only messages received from the server |
| System | Connection lifecycle events (Connected, Disconnected, Error messages) |
Each button shows the count in parentheses (e.g., Sent (3)).
Search / Filter
A search box in the log header filters messages in real time. Typing any string hides messages whose data does not contain that string (case-insensitive). The filter works in combination with the direction filter buttons.
Message Rows
Each row in the log displays:
| Element | Description |
|---|---|
| Direction icon | ↑ (green) for sent, ↓ (blue/accent) for received, · for system |
| Timestamp | HH:MM:SS when the message was added to the log |
| Message data | Full text of the message, displayed in the monospace font |
| Copy button | Appears on hover — copies the full message data to the clipboard |
The log retains the last 500 messages per session. Older messages are dropped as new ones arrive.
Saving to a Collection
Press Ctrl+S (or Cmd+S on macOS) to save the WebSocket connection.
- If the tab is not yet associated with a collection, the Save As dialog opens. Choose a collection and optionally a folder, then name the request.
- If the tab is already linked to a saved request, the Save button is highlighted in the accent color when there are unsaved changes. Clicking it saves immediately.
What is persisted:
- Server URL (with variable placeholders intact)
- Custom headers (keys, values, enabled state)
- Query parameters (keys, values, enabled state)
- Message body and format selection
- Settings (SSL verify, timeouts, reconnect options, max message size)
The message log is session-only and is not saved to the collection.
Tips
- Use
wss://with SSL verification disabled (Settings tab) for local development with self-signed certificates - Store server URLs and auth tokens in environments and reference them with
{{variable}}— switch environments without editing the request - The Params tab is the cleanest way to pass room IDs, tokens, or version flags on the upgrade URL without manually editing the query string
- The Beautify button is handy before sending JSON to make sure your payload is well-formed
- System messages in the log include WebSocket close codes (e.g.,
code: 1006) which can help diagnose unexpected disconnections