Skip to main content
Version: ZIO 2.x


In the WebSocket protocol, communication happens using frames. ZIO HTTP's WebSocketFrame is the representation of those frames. The domain defines the following type of frames:

  • Text
  • Binary
  • Continuation
  • Close
  • Ping
  • Pong


To create a Text frame that models textual data in the WebSocket protocol, you can use the text constructor.

val text = WebSocketFrame.text("Hello from ZIO-HTTP")


To create a Binary frame that models raw binary data, you can use the binary constructor.

import zio.Chunk

val binary = WebSocketFrame.binary(Chunk.fromArray("Hello from ZIO-HTTP".getBytes(StandardCharsets.UTF_16)))


To create a Continuation frame to model a continuation fragment of the previous message, you can use the continuation constructor.

import io.netty.buffer.Unpooled.copiedBuffer
import io.netty.util.CharsetUtil.UTF_16

val continuation = WebSocketFrame.continuation(copiedBuffer("Hello from ZIO-HTTP", UTF_16))


To create a Close frame for a situation where the connection needs to be closed, you can use the close constructor. The constructor requires two arguments:

  • Status
  • Optional reason.

Constructing Close with just status

val close = WebSocketFrame.close(1000)

Constructing Close with status and a reason

val close = WebSocket.close(1000, "Normal Closure")

More information on status codes can be found in Section 7.4 of IETF's Data Tracker.


Ping models heartbeat in the WebSocket protocol. The server or the client can at any time, after a successful handshake, send a ping frame.

val ping =


Pong models the second half of the heartbeat in the WebSocket protocol. Upon receiving ping, a pong needs to be sent back.

val ping =

Pattern Matching on WebSocketFrame

ZIO HTTP envisions the WebSocketFrame as a Sum type, which allows exhaustive pattern matching to be performed on it.

You can do pattern matching on the WebSocketFrame type in the following way:

val frame: WebSocketFrame = ...

frame match {
case WebSocketFrame.Binary(bytes) => ???
case WebSocketFrame.Text(text) => ???
case WebSocketFrame.Close(status, reason) => ???
case WebSocketFrame.Ping => ???
case WebSocketFrame.Pong => ???
case WebSocketFrame.Continuation(buffer) => ???