Connecting to a WebSocket server
Create a WebSocket request, configure its handshake and open a connection.
Overview
A WebSocket request describes a connection: the URL to connect to, the opening handshake and the messages you plan to send. When you connect, Relay sends the handshake as an HTTP GET request with the request's headers, authentication and cookies. Once the server accepts it, the connection stays open, in both directions, until you or the server close it.
WebSocket requests live in drafts and collections alongside HTTP requests. They're marked WSS in the sidebar, and they use the same variables, inherited authentication and settings.
Create a WebSocket request
Do one of the following:
- Choose File > New WebSocket Draft, or press Option-Shift-Command-N.
- In the sidebar, click the Add button (+) and choose New WebSocket Draft.
- In the sidebar, Control-click a collection or folder and choose New WebSocket Request.
- In an HTTP request, click the method at the start of the URL bar and choose WebSocket.
- In an HTTP request, enter or paste a URL that starts with
ws://orwss://.
Then enter the server's URL in the URL bar, such as wss://echo.example.com/. A new WebSocket request starts with one empty JSON message, named Message 1, in its Messages tab.
When you turn an HTTP request into a WebSocket request, an http:// or https:// URL becomes ws:// or wss://, and Relay keeps the HTTP body in case you switch back. To turn a WebSocket request back into an HTTP request, click WSS in the URL bar and choose HTTP Request. Its saved messages and WebSocket settings are removed; choose Edit > Undo to get them back.
Tip
ws:// or wss:// URL, choose File > Import > cURL Command… to create the request from it.Configure the handshake
The handshake is built from the request the same way an HTTP request is:
- URL and query parameters: Edit them in the URL bar and the Params tab.
- Headers: Add headers in the Headers tab, such as an
Originheader or a token the server expects. - Authentication: Set it in the Auth tab, or let the request inherit it. Every type works except Digest Auth, which Relay can't use for a WebSocket handshake.
- Cookies: Relay sends the workspace's cookies for the URL, and stores cookies the server sets in its handshake response.
Choose WebSocket settings
The request editor's Settings tab has a WebSocket section at the top:
- Subprotocols: The subprotocols the handshake offers, such as
graphql-transport-ws, sent in order as aSec-WebSocket-Protocolheader. Click Add Subprotocol to add one. If you add aSec-WebSocket-Protocolheader yourself, it's sent instead. - Automatic Pings: Sends a ping every 10, 20, 30 or 60 seconds to keep an idle connection open. Off by default.
- Maximum Message Size: The largest message the connection accepts, from 1 MB to 256 MB. The default is 16 MB. A larger message closes the connection.
Below it, Handshake Timeout sets how long Relay waits for the server to accept the connection, and Use Proxy and Verify Certificates work as they do for HTTP requests, with the workspace's client and CA certificates. A WebSocket handshake doesn't follow redirects, so the redirect settings don't appear. For more, see Configuring request settings.
Run a script before connecting
A WebSocket request runs one script phase, Before Connecting, in its Scripts tab, along with its folders' and collection's pre-request scripts. Use it to fetch a token or set variables and headers for the handshake. Values a script sets with relay.variables.set also fill in the messages you send on that connection. For more, see Running scripts before and after requests.
Connect
Click Connect in the URL bar, or press Command-Return.
The dot beside the URL shows the connection's state: amber while connecting, green once it's open, and red when the last attempt failed. To stop connecting before the server answers, click Cancel; nothing is recorded.
Once the connection is open, the response inspector shows the handshake's status, 101, with a Connected capsule beside it. Click Headers to see the handshake's request and response headers, and Timeline to see how long each stage took. The Messages tab shows everything sent and received; see Sending and receiving messages.
If the server refuses the handshake, the inspector shows its status and headers, such as 401 Unauthorized. If a Before Connecting script fails, Relay doesn't connect, and the Tests tab shows the error.
Reconnect after a change
Changes to the request's URL, query parameters, headers, authentication, subprotocols or settings apply to the next connection. While a connection is open, the Messages tab shows a banner when the request has changed since it connected. Click Reconnect to close the connection and open a new one.
Disconnect
Click Disconnect in the URL bar, or press Command-Period. Relay closes the connection with the normal close code, 1000, and records it in History. You can also Control-click a WebSocket request in the sidebar and choose Connect or Disconnect.
When the server closes the connection, or it fails, the inspector keeps everything that was exchanged, and the last row of the Messages tab shows the close code and reason or the error.
Manage open connections
A connection belongs to its request, not to a window. It stays open when you select another request or close the window, and a green dot marks its request in the sidebar.
While any connection is open, the toolbar shows a button with the number of open connections. Click it to see them. Click a connection to show its request. To close one, click the button with three dots on its row and choose Disconnect. To close every connection, click Disconnect All at the bottom of the list, or choose Request > Disconnect All.
Relay also closes a connection, with the close code 1001, when you delete its request, and closes every connection when you quit.
Review past connections
Each connection that ends appears in History, with its handshake, its status and the messages it exchanged. Select it to read them again. A connection in History can't reconnect; to open it again, select the request in the sidebar, or click Edit as New Draft in the URL bar to make a new request from it. For more, see Reviewing request history.
See Also
- Sending and receiving messages: Send saved text, JSON and binary messages, and read the connection's transcript.
- Inheriting authentication: Set authentication once on a workspace, collection or folder and let requests inherit it.
- Configuring request settings: Set the timeout, redirect behavior, proxy and certificate checks for a request or a group of requests.
- Generating code from requests: Turn a request into code for curl, Python, JavaScript, Swift and other languages.