> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.playability.gg/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Connect External Apps Through WebSocket

PlayAbility can exchange real-time control data with another application through a WebSocket server on port `13123`. You decide whether clients may send inputs, receive PlayAbility output state, or do both.

## Before you start

- The external application must support WebSocket connections and PlayAbility's JSON messages.
- PlayAbility must remain open or running in the system tray.
- The current WebSocket server is local-only. The client must run on the same computer as PlayAbility.

Use this endpoint:

```text
ws://127.0.0.1:13123
```

## Enable the WebSocket server

1. Open **Connections** in PlayAbility.
2. Select **WebSocket & MCP**.
3. In **WebSocket Settings**, turn on **Enable WebSocket Server**.
4. Choose the minimum permissions your integration needs:
   - Turn on **Allow WebSocket Inputs** to let the client send gamepad, keyboard, or mouse input.
   - Turn on **Allow WebSocket Outputs** to broadcast PlayAbility's output state to connected clients.
5. Leave **WebSocket output full speed** off unless the client needs more than the normal rate of about 30 updates per second.

Full-speed output uses more CPU and network capacity.

## Require an authentication key

Authentication is recommended even for a local connection because other software running under your account could otherwise connect to the server.

1. Turn on **Require authentication key**.
2. Use the generated value in **Authentication key**, or select **Generate New Key**.
3. Reveal and copy the key into the trusted client.
4. Store it as a secret. Do not put it in screenshots, public configuration files, or support messages.

After connecting, the client receives a message similar to:

```json
{
  "type": "CONNECT",
  "info": "WebSocket Server Started",
  "authRequired": true
}
```

When authentication is required, the client must send this before any other request:

```json
{
  "type": "AUTH",
  "key": "YOUR_AUTHENTICATION_KEY"
}
```

A successful authentication returns:

```json
{
  "type": "AUTH_OK"
}
```

## Send a simple input test

Make sure **Allow WebSocket Inputs** is on, then send a press and a release:

```json
{
  "events": [
    {
      "type": "button",
      "code": "A",
      "value": true
    }
  ]
}
```

```json
{
  "events": [
    {
      "type": "button",
      "code": "A",
      "value": false
    }
  ]
}
```

Always send a release for controls that can remain held. Axis values use `-1` to `1`; trigger values use `0` to `1`.

## Verify the integration

1. Connect the client to `ws://127.0.0.1:13123`.
2. Confirm that it receives the `CONNECT` message.
3. If authentication is enabled, confirm that it receives `AUTH_OK`.
4. Send one button press and release.
5. Confirm that PlayAbility or the target application receives the action.

## Troubleshooting

### The connection is refused

- Confirm that **Enable WebSocket Server** is on.
- Make sure PlayAbility is still running.
- Confirm that the client uses port `13123`.
- Check whether another process is already using port `13123`.
- Use `127.0.0.1` or `localhost`, not an address from another device.

### The client disconnects with an authorization error

- Send the `AUTH` message before any inputs or requests.
- Copy the current key again and remove accidental spaces.
- If you selected **Generate New Key**, update the client with the new value.

### The client connects but inputs do not work

- Turn on **Allow WebSocket Inputs**.
- Validate the JSON and event type, code, and value.
- Make sure **Main Output** and the relevant output type are enabled.
- Send both press and release events.

### No output state is received

Turn on **Allow WebSocket Outputs**. Enable full-speed output only when the normal broadcast rate is insufficient.

## Security and network limitation

- Keep authentication enabled and give each key only to software you trust.
- Generate a new key if the current one may have been exposed.
- Do not treat **Allow WebSocket Inputs** as the only access-control boundary. Keep authentication enabled, and turn off the WebSocket server when the integration is not in use.
- The server is bound to localhost in current builds. The **Local Network IP** displayed in the panel does not make the server reachable from another computer or phone.
- Do not forward port `13123` to the internet.

## Related articles

- [Control PlayAbility with an AI Assistant Through MCP](https://help.playability.gg/en/article/control-playability-with-an-ai-assistant-through-mcp-zhekj/)
- [Control PlayAbility with Settings Actions](https://help.playability.gg/en/article/control-playability-with-settings-actions-1v2eikb/)
- [Build and Edit a Mapping](https://help.playability.gg/en/article/build-and-edit-a-mapping-u0q0bs/)