0
# Ktor Client WebSockets
1

2
Ktor Client WebSockets provides comprehensive WebSocket client support for the Ktor HTTP client framework. It enables full-duplex real-time communication over a single TCP connection, supporting both text and binary message types with automatic connection management, configurable frame sizes and ping intervals, and seamless integration with Ktor's multiplatform architecture.
3

4
## Package Information
5

6
- **Package Name**: ktor-client-websockets
7
- **Package Type**: Maven (Kotlin Multiplatform)
8
- **Language**: Kotlin
9
- **Installation**: `implementation("io.ktor:ktor-client-websockets:3.2.0")`
10
- **Platforms**: All Kotlin Multiplatform targets including JVM, Android, iOS, JavaScript, and Native
11

12
## Core Imports
13

14
```kotlin
15
import io.ktor.client.*
16
import io.ktor.client.plugins.*
17
import io.ktor.client.plugins.websocket.*
18
import io.ktor.websocket.*
19
```
20

21
## Basic Usage
22

23
```kotlin
24
import io.ktor.client.*
25
import io.ktor.client.plugins.websocket.*
26
import io.ktor.websocket.*
27

28
// Install WebSocket plugin
29
val client = HttpClient {
30
    install(WebSockets) {
31
        pingIntervalMillis = 20_000  // 20 seconds
32
        maxFrameSize = Long.MAX_VALUE
33
    }
34
}
35

36
// Basic WebSocket connection
37
client.webSocket("ws://localhost:8080/websocket") {
38
    // Send text message
39
    send("Hello, WebSocket!")
40
    
41
    // Receive and handle incoming frames
42
    for (frame in incoming) {
43
        when (frame) {
44
            is Frame.Text -> {
45
                val receivedText = frame.readText()
46
                println("Received: $receivedText")
47
            }
48
            is Frame.Binary -> {
49
                val receivedBytes = frame.readBytes()
50
                println("Received binary data: ${receivedBytes.size} bytes")
51
            }
52
            is Frame.Close -> {
53
                println("Connection closed")
54
                break
55
            }
56
            else -> {}
57
        }
58
    }
59
}
60
```
61

62
## Architecture
63

64
Ktor Client WebSockets is built around several key components:
65

66
- **WebSockets Plugin**: The main plugin that manages WebSocket connections and handles protocol upgrades
67
- **Client Sessions**: Specialized WebSocket session interfaces that integrate with Ktor's HTTP client call lifecycle
68
- **Builder Functions**: Convenient extension functions for establishing WebSocket connections with various configuration options
69
- **Content Serialization**: Optional content converters for automatic serialization/deserialization of messages
70
- **Platform Abstraction**: Multiplatform implementation with platform-specific optimizations (e.g., JavaScript browser WebSocket API)
71

72
## Capabilities
73

74
### Plugin Configuration
75

76
Core WebSocket plugin installation and configuration, including ping intervals, frame size limits, and content serialization.
77

78
```kotlin { .api }
79
class WebSockets(
80
    val pingIntervalMillis: Long,
81
    val maxFrameSize: Long,
82
    val contentConverter: WebsocketContentConverter? = null
83
)
84

85
class Config {
86
    var pingIntervalMillis: Long
87
    var maxFrameSize: Long
88
    var contentConverter: WebsocketContentConverter?
89
    fun extensions(block: WebSocketExtensionsConfig.() -> Unit)
90
}
91
```
92

93
[Plugin Configuration](./plugin-configuration.md)
94

95
### Connection Management
96

97
Functions for establishing and managing WebSocket connections with support for various URL formats and request configurations.
98

99
```kotlin { .api }
100
suspend fun HttpClient.webSocket(
101
    request: HttpRequestBuilder.() -> Unit,
102
    block: suspend DefaultClientWebSocketSession.() -> Unit
103
)
104

105
suspend fun HttpClient.webSocketSession(
106
    block: HttpRequestBuilder.() -> Unit
107
): DefaultClientWebSocketSession
108

109
suspend fun HttpClient.wss(
110
    request: HttpRequestBuilder.() -> Unit,
111
    block: suspend DefaultClientWebSocketSession.() -> Unit
112
)
113
```
114

115
[Connection Management](./connection-management.md)
116

117
### Message Handling
118

119
Client-specific WebSocket session interfaces providing access to HTTP call context and message serialization capabilities.
120

121
```kotlin { .api }
122
interface ClientWebSocketSession : WebSocketSession {
123
    val call: HttpClientCall
124
}
125

126
class DefaultClientWebSocketSession(
127
    override val call: HttpClientCall,
128
    delegate: DefaultWebSocketSession
129
) : ClientWebSocketSession, DefaultWebSocketSession by delegate
130

131
suspend fun <T> DefaultClientWebSocketSession.sendSerialized(data: T)
132
suspend fun <T> DefaultClientWebSocketSession.receiveDeserialized(): T
133
```
134

135
[Message Handling](./message-handling.md)
136

137
## Types
138

139
```kotlin { .api }
140
data object WebSocketCapability : HttpClientEngineCapability<Unit>
141

142
data object WebSocketExtensionsCapability : HttpClientEngineCapability<Unit>
143

144
class WebSocketException(message: String, cause: Throwable?) : IllegalStateException
145

146
val DefaultClientWebSocketSession.converter: WebsocketContentConverter?
147
```