# Configure WebSocket Proxying

WebSocket provides persistent, bidirectional communication over a single TCP connection. It is commonly used for live feeds, chat, collaborative applications, and other workloads that exchange data in real time.

API7 Enterprise can proxy the initial HTTP upgrade request and keep the resulting WebSocket connection open. This guide configures a route to a WebSocket upstream and verifies bidirectional traffic through the gateway.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* An API7 Enterprise instance is running.
* A Gateway Group is created and a Gateway instance is running.
* A [token from the Dashboard](https://docs.api7.ai/api7-gateway/reference/obtain-dashboard-token.md).
* [Docker](https://docs.docker.com/get-docker/) is installed where the sample upstream will run.
* [websocat](https://github.com/vi/websocat) is installed on the client used for verification.
* [ADC is installed and connected](https://docs.api7.ai/api7-gateway/getting-started/quick-start.md#step-3-create-a-service-and-route) to the target Gateway Group if you use the ADC configuration.

## Start a Sample WebSocket Server[​](#start-a-sample-websocket-server "Direct link to Start a Sample WebSocket Server")

Set `GATEWAY_CONTAINER` to the running API7 Gateway container. Create a dedicated network and connect the gateway to it:

```
export GATEWAY_CONTAINER=replace-with-gateway-container-name



docker network create gateway-websocket-net

docker network connect gateway-websocket-net "$GATEWAY_CONTAINER"
```

Start a pinned [sample WebSocket server](https://hub.docker.com/r/jmalloc/echo-server) on the shared network:

```
docker run -d \

  --name websocket-server \

  --network gateway-websocket-net \

  jmalloc/echo-server:v0.3.7
```

The server exposes a WebSocket endpoint at `/.ws` that echoes back any message it receives.

For a non-Docker gateway deployment, run the sample server where the gateway can reach it and replace `websocket-server` in the upstream configuration with that address.

## Enable WebSocket on a Route[​](#enable-websocket-on-a-route "Direct link to Enable WebSocket on a Route")

WebSocket proxying is enabled on a per-route basis. When `enable_websocket` is set to `true`, the Gateway handles the initial HTTP Upgrade handshake and maintains the connection.

Create a Service for the sample upstream and a Route with `enable_websocket` set to `true`:

For the Admin API configuration, export the Dashboard token and replace `{gateway_group_id}` with the target Gateway Group ID. The quickstart Gateway Group uses `default`.

```
export API_KEY=replace-with-dashboard-token
```

* Admin API
* ADC

Create the Service:

```
curl -k "https://localhost:7443/apisix/admin/services/websocket-service?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "websocket-service",

    "upstream": {

      "type": "roundrobin",

      "nodes": [

        {

          "host": "websocket-server",

          "port": 8080,

          "weight": 1

        }

      ]

    }

  }'
```

Create the Route:

```
curl -k "https://localhost:7443/apisix/admin/routes/websocket-route?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "websocket-route",

    "paths": ["/.ws"],

    "service_id": "websocket-service",

    "enable_websocket": true

  }'
```

adc.yaml

```
services:

  - name: websocket-service

    labels:

      docs-example: websocket-proxy

    upstream:

      nodes:

        - host: websocket-server

          port: 8080

          weight: 1

    routes:

      - name: websocket-route

        uris:

          - /.ws

        enable_websocket: true
```

ADC reconciles services as desired state. Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=websocket-proxy
```

Synchronize the reviewed service configuration:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=websocket-proxy
```

## Verify the Connection[​](#verify-the-connection "Direct link to Verify the Connection")

Open a connection through API7 Gateway:

```
websocat "ws://127.0.0.1:9080/.ws"
```

Send `hello`. The server should echo the message:

```
Request served by <container-id>

hello

hello
```

The open connection and echoed message confirm that the gateway completed the protocol upgrade and proxies traffic in both directions.

## Next Steps[​](#next-steps "Direct link to Next Steps")

WebSocket traffic can use the same authentication, traffic-management, and observability features applied during the HTTP upgrade request.

* [Configure gRPC Proxying](https://docs.api7.ai/api7-gateway/how-to-guides/protocol-proxy/grpc-proxy.md) — learn how to handle gRPC traffic and transcoding.
* [Configure GraphQL Proxying](https://docs.api7.ai/api7-gateway/how-to-guides/protocol-proxy/graphql-proxy.md) — explore GraphQL-aware traffic management.