Guest API WebSocket handshake failing with 401 on custom chat UI

NICE CXone API & Integrations
1

So we’re trying to ditch the default widget for a custom chat UI in our React app. I’ve been following the Guest API docs, but the WebSocket handshake keeps failing with a 401 Unauthorized.

Here’s the flow:

  1. Call POST /api/v2/engagements/conversations/guest to get the guest token.
  2. Use that token to connect to the WebSocket endpoint provided in the response.

The token generation works fine. The issue is when I try to establish the WebSocket connection. I’m passing the token in the Authorization header during the handshake. The browser console shows the connection is being refused immediately.

const ws = new WebSocket(wsUrl, ['token', guestToken]);

I’ve also tried passing it as a query param ?token=... but that throws a 400 Bad Request. The docs are a bit vague on the exact header format for the WebSocket upgrade request. Is there a specific header name I should be using? Or is this a known issue with the current version of the API?

I’m using the latest version of the genesys-cloud npm package for the initial REST calls, but the WebSocket part is raw JS. Any pointers?