# Websocket

A WebSocket session keeps one connection open in both directions, which suits devices that need low-latency
two-way messaging without re-establishing a connection for every message.

## Connecting

```bash
wss://api.opengate.es:9955/south/v80/sessions/{device.id}
```

| | |
|---|---|
| Port | `9955` |
| Path | `/south/v80/sessions/{device.id}` |
| Authentication | `X-ApiKey`, **required** |

The API key can travel either way, whichever your WebSocket client makes easier:

**As a header** of the HTTP request that establishes the connection.

**As a URL parameter** named `X-ApiKey`:

```bash
wss://api.opengate.es:9955/south/v80/sessions/your-device-id?X-ApiKey={your-api-key}
```

Replace `your-device-id` and `your-api-key` with the values of your environment.

## What travels over the session

The messages themselves are shaped by a [connector function](../connector_functions/): the URI of the
session is matched against the function's `southCriterias` with the `wss://` scheme, and the function
decides what to do with each incoming message. To send a message back down an already open connection, use
the [WebSocket JavaScript API](../connector_functions/protocol_apis/websocket/).

The `contextParams` your script receives include the session's `uri`, its relative `path` and the
`sessionIp`, which is how a single function can serve several session paths and tell them apart.