> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket events

> Connect a dashboard to GOWA's WebSocket, handle device and pairing events, and refresh device state after reconnecting or completing a login.

GOWA pushes pairing and device events over `/ws`. Each frame contains a JSON object with a machine-readable `code`, a human-readable `message`, and a `result` whose shape depends on the event.

## Connect

Use `/ws` under your `APP_BASE_PATH`, such as `wss://gowa.example.com/gowa/ws`. Select a device with `?device_id=<id>`. When Basic Auth is enabled, browser clients pass the URL-encoded base64 value of `user:password` as `authorization`. Clients that can set the `Authorization` header can use Basic Auth through that header. Use `wss://` and redact the query string in proxy logs. Add the dashboard origin to GOWA's [trusted browser origins](https://gowa-docs.mintlify.site/authentication.md#cors) if you host it separately.

Every connected socket receives each broadcast, even when the connection specifies a device. Use `result.device_id` to identify the affected slot when present. Grant WebSocket access only to callers trusted with all devices.

## Event payloads

| `code` | When it arrives | `result` |
| - | - | - |
| `LIST_DEVICES` | A client sends `FETCH_DEVICES`. | Device list with `name`, `device`, and `jid` entries. |
| `LOGIN_SUCCESS` | WhatsApp pairs the device. | `null`. Refresh device status over REST. |
| `PASSKEY_REQUEST` | WhatsApp requests a passkey assertion. | `device_id`, `challenge` (WebAuthn options). |
| `PASSKEY_CONFIRMATION` | WhatsApp reports the passkey handoff result. | `device_id`, `code`, `skip_handoff_ux`. When `skip_handoff_ux` is true, the active QR flow sends the confirmation automatically. Otherwise compare the code with the phone and call `POST /app/passkey/confirm`. |
| `PASSKEY_ERROR` | Passkey pairing fails. | `device_id`, `continuation`. Read the error text from `message`. |
| `DEVICE_LOGGED_OUT` | The device logs out and keeps its slot. | `device_id` and either `reason` for a remote logout or `devices` for an API logout. The list shape depends on the logout endpoint. |
| `DEVICE_REMOVED` | The device slot is deleted. | `device_id`, `devices` (remaining slots). |
| `DEVICE_STREAM_REPLACED` | Another client connects with the same WhatsApp session. | `device_id`. |
| `DEVICE_TEMPORARY_BAN` | WhatsApp reports a temporary ban. | `device_id`, `code`, `reason`, `expires_in_seconds`, and `expires_at` when WhatsApp supplies an expiry. |
| `DEVICE_REACHOUT_TIMELOCK` | WhatsApp reports or lifts a restriction on starting new chats. | `device_id`, `is_active`, and optional `enforcement_type` and `ends_at`. |
| `DEVICE_WEBHOOK_UPDATED` | The device's webhook URL changes. | `device_id`, `webhook_url`. |
| `DEVICE_WEBHOOK_CONFIG_UPDATED` | The device's webhook settings change. | `device_id`. |

## Refresh device state

To request a list over the socket, send `{"code":"FETCH_DEVICES"}` as a text frame. GOWA broadcasts the resulting `LIST_DEVICES` event to all sockets. To get current state after reconnecting or pairing, call `GET /devices` or `GET /devices/{device_id}/status`. WebSocket events are transient.

```javascript theme={null}
const url = new URL("wss://gowa.example.com/ws");
url.searchParams.set("device_id", "my-device");
url.searchParams.set("authorization", btoa("admin:changeme"));

const socket = new WebSocket(url);
socket.addEventListener("open", () => {
  socket.send(JSON.stringify({ code: "FETCH_DEVICES" }));
});
socket.addEventListener("message", ({ data }) => {
  const { code, result } = JSON.parse(data);
  if (code === "LIST_DEVICES") {
    console.log("Device list", result);
  }
  if (code === "DEVICE_LOGGED_OUT" && result?.device_id === "my-device") {
    console.log("Device logged out", result.device_id);
  }
});
```

See [Passkey pairing](https://gowa-docs.mintlify.site/authentication.md#passkey) for the REST calls that complete a passkey request. Use [webhooks](https://gowa-docs.mintlify.site/concepts/webhooks.md) to process WhatsApp messages and receipts.


## Related topics

- [Authentication](https://gowa-docs.mintlify.site/authentication.md)
- [API Authentication](https://gowa-docs.mintlify.site/api-reference/authentication.md)
- [Multi-Device & Device Selection](https://gowa-docs.mintlify.site/concepts/multidevice.md)
- [Webhooks](https://gowa-docs.mintlify.site/concepts/webhooks.md)
- [API Reference](https://gowa-docs.mintlify.site/api-reference/introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.