WebSocket
Postguy connects to WebSocket servers. It sends text and binary frames, answers pings and records every event in a log.
e.connect, e.composer, e.timeline, e.binary and e.settings as partial, and e.saved-messages as planned. The app's panel is minimal. The richer features (binary frames, ping, reading the log by sequence number) are reachable through the automation tools. Scripts and the collection runner skip WebSocket requests.Create a WebSocket request
- Select a collection or folder in the sidebar.
- Open the plus menu and choose
New WebSocket request.
The protocol is fixed when a request is created.
The request tab
| Control | Notes |
|---|---|
| URL field | Placeholder wss://example.com/socket. |
Connect / Disconnect | One button, depending on whether the socket is open. A status line reads Connected or Not connected. |
Save | Appears when the request has unsaved changes. |
| Event log | One row per event: direction, kind, sequence number and text. The panel draws at most 2,000 rows. |
Message box and Send | A multi-line text field labelled Message. Send is enabled while connected and sends a text frame. |
The tab connects the current draft, so you do not have to save first. Variables are resolved when you connect.
The tab edits only the URL. A request also stores the fields below. The UI does not edit them, but the engine uses them at connect time. Set them with the request_update tool, or by importing a request that carries them.
| Field | Behaviour |
|---|---|
params | Enabled rows are appended to the URL as an encoded query string. |
headers | Enabled rows are sent as handshake headers. Values resolve variables. |
protocols | Sent as Sec-WebSocket-Protocol. The protocol the server picked is shown in the open event. |
savedMessages | Named messages with a format (see below). Stored only; there is no UI for them yet. |
Message formats
A stored message has a format: Text, JSON, XML, HTML or Binary (payload stored as base64 or hex).
The panel always sends text. To send binary frames, use the ws_send tool (binary_base64).
The event log
Each event has a sequence number, a timestamp, a direction and a kind.
| Direction | Meaning |
|---|---|
sent | frames you sent |
received | frames from the server |
network | connection events |
Kinds are text, binary, ping, pong, open, close and error. Binary, ping and pong payloads are kept as base64, up to 1 MiB each.
Log limits for one session:
- It keeps the newest 10,000 events.
- It keeps at most 64 MiB of payload in total.
Session limit:
- At most 32 sessions can be open.
- Opening one more evicts the oldest disconnected session.
- If none is disconnected, it fails with
at most 32 WebSocket sessions can be open; close one first.
Settings
Each WebSocket request has its own settings:
| Setting | Default | Behaviour |
|---|---|---|
verifySsl | on | Applies to wss://. WebSocket uses this per-request switch only. The global SSL setting is not consulted. With verification on, the system roots, the custom CA bundle and the PEM client certificate are used. |
handshakeTimeoutMs | 0 | 0 means 30,000 ms. |
maxMessageMb | 0 | Largest accepted message. 0 still enforces a hard ceiling of 64 MiB. Larger values are capped to 64 MiB. |
reconnectAttempts, reconnectIntervalMs | 0 | Stored, but not acted on. Nothing reconnects automatically. |
Not supported
These return an actionable error instead of silently falling back:
permessage-deflatecompression.- HTTP proxies. The proxy settings do not apply to WebSocket connections.
- Redirects during the handshake.
Also missing in the UI: search and filters in the log, hexdump view, saved-message management, and a warning for managed handshake headers.
Headless
| Tool | Purpose |
|---|---|
ws_connect | Connect a saved WebSocket request; returns a session id |
ws_send | Send text or binary_base64 to a session |
ws_messages | Read events after sequence number since (default 0); read-only |
ws_disconnect | Close with code (default 1000) and optional reason; the session id is dropped afterwards |
Each postguy-cli call runs in a fresh process, so a session does not outlive the call. To chain steps in one process, use run --script or an agent that keeps the process alive. See Automation tools.