WebSocket Request

A WebSocket connection stays open. Instead of sending one request and reading one response, you connect once and then exchange messages in both directions for as long as the connection lives. A WebSocket request in Requestly stores everything needed to open that connection (the URL, handshake headers, query params, authorization, and connection settings) plus the payloads you want to send, so you can reopen the same session tomorrow without retyping anything.

​

Create a WebSocket request

​

The URL bar

The URL bar holds the address and every connection-level action.

• Connect opens the connection. It is shown while you are idle, disconnected, or sitting on a failed attempt.
• Cancel replaces Connect while the handshake is in flight, so you are not stuck waiting on an unreachable host.
• Disconnect replaces Connect once the socket is open, and closes it.
• Save stores your edits. On a saved request the arrow next to it offers Save as new, which writes a copy instead of overwriting.

While a connection is active, the URL and the Settings tab become read-only. The Messages, Headers, Params, and Authorization tabs stay editable, so you can adjust what you send next without dropping the socket.

​

When a connection fails

A failed attempt names the cause rather than resetting to a blank state. The status badge holds the reason until you connect again, and the Timeline panel records a matching error row. Reasons include Connection refused, DNS failure, Offline, TLS handshake failed, Handshake timeout, Handshake rejected, Auth rejected, Auth token expired, Reconnect attempts exhausted, Server closed connection, Connection lost, and Protocol error.

​

Editor tabs

​

Overview

A free-text description of the request, written in Markdown. Useful for recording which environment the endpoint belongs to or what the server expects first.

​

Messages

The Messages tab is a saved-payload library plus a composer. The left pane lists Saved messages that persist with the request, so a payload you use often is one click away on every future session. The right pane is the editor for the message you selected.

• The format dropdown under the editor switches between Text, JSON, XML, HTML, and Binary. JSON, XML, and HTML get syntax highlighting and a format button. Choosing Binary adds a second dropdown for Base64 or Hex encoding.
• The toggle on each saved row auto-sends that message immediately after the connection opens. Use it for a subscribe or authenticate frame that always has to go first.
• The ... menu on each row renames the message, adds a description, or deletes it.
• Send sits at the bottom right of the editor and is enabled only while you are connected.

A new request already contains one saved message called Message 1. If you connect with an empty list, Requestly adds a starter message so you always have somewhere to type.

​

Headers

Headers here are sent on the WebSocket handshake, the HTTP request that upgrades the connection. Add key and value pairs, use the checkbox to turn individual rows off without deleting them, and switch to bulk edit to paste several at once. Values accept {{variable}} references, which resolve from your environment and collection variables when you connect. If your server negotiates a subprotocol, write it here as a plain Sec-WebSocket-Protocol header.

​

Params

Query params attached to the handshake URL. This tab and the URL bar are two views of the same data: typing ?token=abc into the URL bar adds a token row here, and editing a row rewrites the URL bar’s query string. Disabled rows stay in the list but are left out of the URL.

​

Authorization

The same authorization editor the HTTP and GraphQL editors use, with the full set of types available, including inheriting from the parent collection. Whatever it produces is applied to the handshake.

​

Settings

Per-request connection tuning: Below those settings is a Device-local section with a Handshake headers table. Headers added there are sent on the handshake from this machine only and are never synced to your team. That makes it the right place for a personal credential: values accept both {{variable}} and {{vault:KEY}} references, so you can point at a Vault secret instead of pasting the secret itself.

​

The Timeline panel

The Timeline panel on the right is the record of the session. Every message you send, every message the server sends, and every connection event lands there, newest first. Each row shows a direction arrow (up for sent, down for received), the payload preview, its size, and a local timestamp down to the millisecond. Click a row to expand it into a read-only editor with the full payload and a language picker, so you can read a JSON frame as JSON even if it arrived as text. Beyond messages, the timeline records:

• Handshake rows carrying the upgrade response status and headers.
• Lifecycle rows for connecting, connected, reconnecting, and disconnected, including the close code and its standard name (for example 1000 NORMAL_CLOSURE or 1006 ABNORMAL_CLOSURE).
• Error rows carrying the failure reason.

To narrow the list, use the Search messages box to match on payload content, and the dropdown to show All, Sent, or Received. A counter on the right reads how many rows match out of the total. The clear button empties the timeline without touching your filters. Use the controls in the panel’s header bar to move it to the bottom of the editor instead of the right side, or to collapse it out of the way.

​

Save and reuse examples

An example is a saved snapshot of a request’s configuration. For WebSocket requests it captures the URL, handshake headers, query params, authorization, connection settings, and saved messages. It carries no response, because a WebSocket session has no single response to capture. An example tab never holds a live connection itself. That is deliberate: the example stays a stable reference, and the session runs in the draft that Try It spawns. See Create Request & Response Examples for renaming, duplicating, and deleting examples.

​

Import and export

WebSocket requests are carried in full by Requestly’s own collection format. Exporting a collection as a Requestly .json file includes every WebSocket request with its URL, headers, params, authorization, settings, and saved messages, and importing that file back restores them exactly. Examples ride along with their parent request. Other formats cannot represent them:

• Postman. Exporting a collection as a Postman v2.1 collection leaves WebSocket requests out, because the format has no shape for them. The export dialog tells you how many were excluded before you download.
• OpenAPI. WebSocket requests are skipped, since OpenAPI describes HTTP operations.
• HAR. Importing a .har capture skips ws:// and wss:// entries.

See Import & Export for the full matrix.

​

WebSocket requests in the Collection Runner

The Collection Runner runs a collection’s requests in sequence. You can select a WebSocket request in the run order and it appears with a WS badge, but it does not connect: the runner executes one request at a time and waits for it to finish, which a long-lived connection never does. Each WebSocket request in a run is recorded as skipped, with the reason shown on the result row reading “not supported in runner”. Skipped requests are counted in the run summary and listed under the Skipped tab, so a run stays green and you can see exactly what was left out. Connect to WebSocket endpoints from the request editor instead. Scheduled Runs behave the same way. See Scheduled Runs.

​

What’s next?