---
id: web--web-socket-listener
title: "Web socket listener"
summary: "Embedded WebSocket server: accepts WebSocket connections on a port and path, emits every received message and sends messages back to a connected client. Use it for push or chat style endpoints; reply with the listener's `Input` pin or a **Web socket response** component."
audience: user
keywords: "start, output, input, authenticate, listenurl, maxparallelrequests, maxrequestbodysize, timeout, keepalivetimeout, maxrequestheadercount, usessl, sslprotocol, servercertificate"
---
# Web socket listener

Embedded WebSocket server: accepts WebSocket connections on a port and path, emits every received message and sends messages back to a connected client. Use it for push or chat style endpoints; reply with the listener's `Input` pin or a **Web socket response** component.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Start | start | | Starts the server. Called by the system at flow start when unconnected. |
| Output | output | `Viaducta.Plugins.Http.Types.WebSocketMessage` | Called for every message received from any client. |
| Input | input | `Viaducta.Plugins.Http.Types.WebSocketMessage`, `Viaducta.Plugins.TextPlugin.Types.TextRecord` | Message to send to a client. |
| Authenticate | continue | `Viaducta.Plugins.Http.Types.WebHttpRequest` | Called before a connection is accepted. See Notes. |

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `ListenUrl` | listener URL | | Required. `http://localhost:<port>/<path>` (private) or `http://0.0.0.0:<port>/<path>` (public), e.g. `http://0.0.0.0:9001/ws`. Clients connect with `ws://host:9001/ws`. |
| `MaxParallelRequests` | integer (1-4096) | `1024` | Max requests processed in parallel. Further requests wait for a free slot until the caller gives up; open (keep-alive) connections are not limited. |
| `MaxRequestBodySize` | integer | `0` | Max request body size, `0` = unlimited. |
| `Timeout` | integer | `60000` | Ignored. |
| `KeepAliveTimeout` | integer | `130` | HTTP keep-alive timeout in seconds. |
| `MaxRequestHeaderCount` | integer | `100` | Max number of request headers. |
| `UseSsl` | boolean | `false` | `true`: TLS (`wss://`). |
| `SslProtocol` | dropdown: `0` None, `12` Ssl2, `48` Ssl3, `192` Tls, `240` Default, `768` Tls11, `3072` Tls12, `12288` Tls13 | `0` | Allowed protocol(s) when `UseSsl`. |
| `ServerCertificate` | certificate | | Name of a certificate object in the repository, used when `UseSsl`. |

## Behaviour

- Non-WebSocket requests get `400`. If `Authenticate` is connected and raises an error, the handshake is answered with `401` and the error text; otherwise the connection is accepted and gets a unique session id.
- Each complete message (max 1 MB, larger messages close the connection) is emitted on `Output` as `WebSocketMessage` with `SessionId`, `MessageType` (`0` text, `1` binary), `ContentByte` and `ContentString` (UTF-8). The `WebSocketListener` metadata carries the `SessionId`. Messages of one connection are processed one after another.
- `Input`: a `TextRecord` is sent as text to the session in the metadata; a `WebSocketMessage` is sent to its own `SessionId` (`ContentByte` wins over `ContentString`). An unknown session id raises an error.
- With no `Output` connection, clients are disconnected with a message. The plugin keeps the flow running and closes all connections when the flow stops.
- Port sharing with Http listeners follows the same rules as the Http listener (same SSL/certificate/visibility, different paths under the same first segment).

## Notes

- `Authenticate` receives the raw ASP.NET request object, not a `WebHttpRequest`, and empty metadata, so **Http authentification** connected there does not work as with the Http listener; test any authentication branch carefully.
- If an Http listener on the same port starts first, WebSocket support is not enabled on that shared server and upgrades fail; use a separate port.
- `Timeout` is not used. With a single listener on a port, every path is accepted.
- To push to a client later (not as a reply), keep its `SessionId` and send a `WebSocketMessage` with that id to `Input`.

## Example

```json
{ "ListenUrl": "http://0.0.0.0:9001/ws" }
```

**Web socket listener** → Script (build reply) → Web socket response