Articles on: Integrations

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:

ws://127.0.0.1:13123

Enable the WebSocket server

Open Connections in PlayAbility.
Select WebSocket & MCP.
In WebSocket Settings, turn on Enable WebSocket Server.
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.
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.

Turn on Require authentication key.
Use the generated value in Authentication key, or select Generate New Key.
Reveal and copy the key into the trusted client.
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:

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

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

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

A successful authentication returns:

{
  "type": "AUTH_OK"
}

Send a simple input test

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

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

{
  "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

Connect the client to ws://127.0.0.1:13123.
Confirm that it receives the CONNECT message.
If authentication is enabled, confirm that it receives AUTH_OK.
Send one button press and release.
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.

Updated on: 30/07/2026

Was this article helpful?

Thank you!