# WebSockets in the Fern Definition

> Learn how to define WebSockets in the Fern Definition

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 and the API documentation.

## WebSocket definition

Each WebSocket is defined in its own file, where it is described by the `channel` object.

### 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

<CodeBlock title="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. 
  ```
</CodeBlock>

## WebSocket API Reference

### WebSocket Reference

Fern renders a unique reference page for WebSockets. 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)).

<Frame caption="Hume's WebSocket Reference Page">
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/8cfb35c6732ef30faa111faf65069fac069a066c2a55fadf72e9487c82785e5f/products/api-def/ferndef-pages/wss-reference.png" alt="The WebSocket Reference" />
</Frame>