Web Messaging Guest API: WebSocket connection failing with 403

NICE CXone API & Integrations
1

Building a custom chat UI using the WebSocket-based Guest API instead of the default widget. The connection drops immediately after the handshake with a 403 Forbidden error. Here is the payload I’m sending:

{
 "type": "connect",
 "data": {
 "guestToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 "externalContactId": "test-123"
 }
}

The token is valid and generated via the guest session creation process. The socket closes right after this message goes out. Checked the logs and there’s no detailed error message, just the status code. Am I missing a required header in the initial WebSocket upgrade request or is the guest token format wrong?

2

You’re missing the webmessaging:guest:write scope on that token, which is why the handshake gets blocked. Also, make sure your externalContactId isn’t already tied to an active session in the org.

1 Like