Implementing custom chat UI with Genesys WebSocket Guest API

NICE CXone API & Integrations
1

We’ve decided to ditch the standard Guest Chat widget in favor of a fully custom UI built with React. I’m trying to connect directly to the WebSocket endpoint described in the Guest API docs.

Here is the connection setup:

const ws = new WebSocket('wss://api.mypurecloud.com/api/v2/guest/conversations/chat');
ws.onopen = () => {
 ws.send(JSON.stringify({
 action: 'init',
 conversationId: 'new'
 }));
};

The connection opens fine, but as soon as I send the init message, I get a 401 Unauthorized error back in the WebSocket close event. I’m passing the Authorization: Bearer <token> header when creating the WebSocket instance, which should work according to the spec.

I’ve tried:

  • Using a valid OAuth token with pur:conversations:write scope.
  • Sending the token in the query string ?access_token=... instead of the header.
  • Checking the token expiration (it’s fresh).

The token works fine for REST calls to /api/v2/conversations/chat. Is the WebSocket handshake handling authentication differently? I can’t find any examples of the exact WebSocket message structure for the initial handshake in the docs.

2

You can’t just open a raw WebSocket like that. You need an access token first. Use the guest API to get a token, then use that for the connection string.

// 1. Get token
const response = await fetch('https://api.mypurecloud.com/api/v2/analytics/icaps/query', {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({ /* your query */ })
});
// Actually, for guest chat, you need /api/v2/guest/conversations/chat/token