Client WebSockets
Ktor supports the WebSocket protocol and allows you to create applications that require real-time data transfer from and to the server. For example, WebSockets can be used to create a chat application.
The Ktor client allows you to handle a WebSocket session for exchanging messages with the server. To learn about WebSocket support in a Ktor server, see Server WebSockets.
Supported engines
The Ktor client supports WebSockets for the following engines:
CIO
OkHttp
Js
Darwin
Add dependencies
To use WebSockets, you need to include the ktor-client-websockets
artifact in the build script:
You can learn more about artifacts required by the Ktor client from Adding client dependencies.
Install WebSockets
To install the WebSockets
plugin, pass it to the install
function inside a client configuration block:
Optionally, you can configure the plugin inside the install
block by passing the required options using WebSockets.Config.
Handle a WebSockets session
API overview
A client's WebSocket session is represented by the DefaultClientWebSocketSession interface. This interface exposes the API that allows you to send/receive WebSocket frames and close a session. HttpClient
allows you to get access to a WebSocket session in one of the following ways:
The webSocket function accepts
DefaultClientWebSocketSession
as a block argument.runBlocking { client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/echo") { // this: DefaultClientWebSocketSession } }The webSocketSession function returns the
DefaultClientWebSocketSession
instance and allows you to access a session outside therunBlocking
orlaunch
scope.
Session configuration might look as follows:
Use the
send
function to send text content to the server.Use the
incoming
andoutgoing
properties to access the channels for receiving and sending WebSocket frames. A frame is represented by theFrame
class.When handling a session, you can check a frame type, for example:
Frame.Text
is a text frame. For this frame type, you can read its content usingFrame.Text.readText()
.Frame.Binary
is a binary frame. For this type, you can read its content usingFrame.Binary.readBytes()
.Frame.Close
is a closing frame. You can callFrame.Close.readReason()
to get a close reason for the current session.
Use the
close
function to send a close frame with the specified reason.
Example
The example below shows how to send a message to the echo
WebSocket endpoint and how to receive a response:
You can find the full example here: client-websockets.