Kotlin WebSocket Guest API 403 on wss://{subdomain}.mypurecloud.com

Building a custom chat UI in Kotlin instead of using the default widget. Trying to connect to the Guest API WebSocket endpoint at wss://{subdomain}.mypurecloud.com/api/v2/guest/conversations/websocket. The connection attempt immediately returns a 403 Forbidden. I’m passing the authorization header with a valid OAuth token generated via client credentials. The token works fine for REST calls to /api/v2/users/me. Here’s the setup:

kotlin
val request = WebSocketRequest.Builder()
 .url(wsUrl)
 .addHeader("Authorization", "Bearer $token")
 .build()

The docs say the token needs webmessaging:guest scope, which it has. Any idea why the handshake is failing?

val authHeader = "Bearer ${accessToken}"

Client credentials tokens don’t carry user context. You’ll need to swap to a resource owner password grant or inject a valid X-Genesys-User-Id header to stop the 403.

Cause: Guest WebSocket requires specific scopes like guest:websocket:write. Client credentials often miss these.

Solution: Ensure the token has the right scope. Also, pass the token in the access_token query param, not just headers.

val url = "wss://$subdomain.mypurecloud.com/api/v2/guest/conversations/websocket?access_token=$token"