> This page is for API Definitions.

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# WebSockets in the Fern Definition

> Learn how to define WebSockets in the Fern Definition

> **Warning**
>
> Fern Definition isn't recommended for new customers and Fern isn't accepting feature requests for this format. It remains supported for existing users.

WebSockets enable a user to create a connection with a server, over which bidirectional communication can be sent.

In Fern, you can specify WebSockets in your API definition. The WebSockets will be included in both the [generated SDKs](/learn/sdks/deep-dives/websocket-clients) and the API documentation.

## WebSocket definition

Each WebSocket is defined in its own file, where it is described by the `channel` object. Put your WebSocket definition files in your `fern` folder alongside your other API definition files.

### The channel object

A `channel` is defined by the following fields:

* `auth`: The authentication scheme for the WebSocket
* `path`: The path of the WebSocket
* `headers` *(Optional)*: Any headers the WebSocket will send
* `path-parameters` *(Optional)*: Any path parameters in the WebSocket path
* `query-parameters` *(Optional)*: Any query parameters used in the initial request of the WebSocket
* `messages` *(Optional)*: The schemas of the messages the WebSocket can send and receive once connected
  * `origin`: The entity that sent the message (e.g. `client` or `server`)
  * `body`: The schema of the message
* `examples`: Example WebSocket connection *(Optional)*

### WebSocket example

#### chat.yml

```yaml
channel:
  path: /chat
  auth: false
  query-parameters:
    model_id:
      type: optional<string>
      docs: The unique identifier of the model.
    model_version:
      type: optional<integer>
      docs: The version number of the model.
  messages:
    publish:
      origin: client
      body: PublishEvent
    subscribe:
      origin: server
      body: SubscribeEvent
  examples: 
    - query-parameters: 
        model_id: "123"
      messages: 
        - type: publish
          body:
            text: "Hello, world."
        - type: subscribe
          body: 
            id: "23823049"
            message: "Hello there, how are you?"
types:
  PublishEvent:
    docs: The input from the user to send through the WebSocket. 
    properties: 
      text: 
        type: string
        docs: The user text to send into the conversation. 
  SubscribeEvent:
    docs: The response from the server sent through the WebSocket.
    properties: 
      id: 
        type: string
        docs: The id of the message. 
      message:
        type: string
        docs: The message sent through the socket. 
```

## WebSocket API Reference

### WebSocket Reference

Fern renders a [unique reference page for WebSockets](/learn/docs/api-references/generate-websocket-ref). The **Handshake** section outlines the protocol for connecting with the server, while the **Send** and **Receive** sections outline the message schemas that can be sent between the client and server.

Users can connect to and use WebSockets from right within the API Reference (check one of Hume's WebSockets [here](https://dev.hume.ai/reference/text-to-speech-tts/stream-input)).

![The WebSocket Reference](/learn/_fern-img/8cfb35c6732ef30faa111faf65069fac069a066c2a55fadf72e9487c82785e5f.webp)