How Come I Can’t cURL a WebSocket?

Avatar photoby Eric Giannini | 04-27-2021
Why I can't cURL a Websocket

WebSocket is a communication protocol used for applications that transfer voice, video, or messaging over the Internet in real time. To test and debug WebSocket connections, many turn to a common tool for testing API endpoints: cURL. Except cURL is designed for unidirectional HTTP request-response connections and can’t establish the bidirectional connection that WebSockets operate on.

One of the most common questions for API developers building experiences around text, voice, or video software is how to debug a WebSocket. The first tool that comes to mind is cURL, which is the go-to for testing API endpoints. The only problem is: it doesn’t work on WebSockets.

Let’s get to the bottom of why you can’t cURL a WebSocket and what you can do instead.

What’s a WebSocket?

WebSocket is a communication protocol for real-time applications that requires two-way messaging (known as “full duplex”) over a single Transmission Control Protocol (TCP) connection.

Basically, it enables applications running within web browsers to send and receive data in real time. The full-duplex connection is what lets you watch your teammate running in the wrong direction (while they’re doing it) during a multiplayer game. It’s also the protocol that allows you to instantly exchange messages over chat apps, check sports scores or stock price changes as they happen, or watch several people editing a shared spreadsheet during a conference call.

WebSockets are also known for:

  • Establishing unlimited connections per conversation, connection, or call.
  • Using HTTP semantics but without the HTTP request-response overhead for each message, resulting in low-latency messaging and simple deployment.
  • Enabling interactive communication between a browser and server in real time, which in turn allows for reactive, real-time programming.

What’s cURL?

cURL, which stands for client URL, is a command-line tool for transferring data to and from a server using URL syntax. In short, the URL tells cURL what server to talk to and what data you want to send.

This versatile tool is a developer favorite due to its ample support for many commonly-used protocols, including HTTP (by default), HTTPS, and FTP. This makes it ideal for testing communication between a local server and almost any platform or device —  including cars, television sets, media players, routers, printers, audio equipment, smartphones, and tablets.

Although you can use cURL for everything from downloading web pages to proxy support, developers primarily use it for executing HTTP verbs on an API endpoint. For context, an API endpoint is designed in two parts: the protocol and the object(s).

Take the following example of an API endpoint for authenticating with Symbl.ai:

How come I can't cURL a Websocket 3

The first part is HTTPS:// (where the “S” at the end stands for Secure Sockets Layer or encryption), and the second part is api.symbl.ai/oauth2/token:generate. Here, we’re using the industry standard for creating API endpoints, which is api followed by the URL.

After the URL, we indicate where the object or collection of objects is located – in this case the endpoint object is a JSON Web Token (JWT). So, users who hit the API endpoint to authenticate have to go through a standard protocol for authorization called oauth2.

To use cURL to transfer data to an endpoint, a cURL user must figure out which HTTP verb will successfully execute the command. The authentication API endpoint is a POST request. Plus, there are two query parameters: one for the appId, and another for the appSecret, which are needed for authentication Ultimately, the API endpoint returns a response with the JWT

The bad news: you can’t cURL a WebSocket

Simply put: WebSocket doesn’t use the HTTP request-response model that cURL is designed for.

This is because HTTP is half duplex, meaning its messaging ability is unidirectional, where the client app sends a request and then the server sends a response.

How come I can't cURL a Websocket 1

HTTP communication stream between server and client. (Source.)

On the other hand, a WebSocket connection establishes an HTTP-based handshake between the client and the server, then “upgrades” the connection from HTTP to WebSockets to enable full-duplex data transfer.

How come I can't cURL a Websocket 2

WebSocket communication stream between server and client. (Source.)

Since cURL can’t establish the full-duplex connection that WebSockets operate on, you can’t cURL a WebSocket. So no, it’s not a lack of caffeine on your part, it simply can’t be done.

So how can you debug your WebSockets?

You don’t have to dig much to find dated forum threads with all sorts of attempted hacks and workarounds to cURL a WebSocket, but it’s easier to just use testing tools that actually support WebSocket connections. Here are a few you can try out:

Take your real-time app the extra mile

Once you have your WebSocket stream set up, you can start thinking about augmenting your real-time application with APIs.

Symbl.ai’s Voice API for WebSockets, for instance, lets you quickly integrate real-time conversation intelligence into your voice, video, chat, or broadcast applications. This highly flexible API enables developers, like yourself, to:

  • Surface insights in real time to improve human to human conversations—such as buyer’s intent, emotional states, and relevant customer information.
  • Tap into accurate conversation analysis for insightful metrics like speaker ratio, sentiments, talk time, silence, pace, and overlap.
  • Leverage contextual understanding to generate live transcriptions of voice/video sessions and intelligently highlight important topics, questions, or action items.

With scalable AI capabilities and out-of-the-box integrations at the ready, you can develop vastly more enhanced experiences around conversations with a fraction of the effort.

Additional reading

To learn more about WebSockets and cURL, check out these helpful sources:

Avatar photo
Eric Giannini
Lead Developer Evangelist & Advocate