Genesys Cloud WebSocket Guest API: Handling 'session_not_found' on reconnect after network flap

We are building a custom web messaging interface for an internal tool and have decided to bypass the standard widget in favor of direct integration with the WebSocket-based Guest API. The goal is to maintain full control over the UI state and avoid the overhead of the widget bundle.

The connection logic is straightforward. We initialize the connection using the genesys-cloud-web-messaging-guest-sdk package. Here is the basic setup for establishing the socket:

const guest = new GuestSdk({
 organizationId: process.env.GENESYS_ORG_ID,
 deploymentId: process.env.GENESYS_DEPLOYMENT_ID,
 locale: 'en-US'
});

await guest.connect();

The initial connection works as expected. We receive the connected event, and subsequent sendMessage calls return the expected ACK. However, we are running into a persistent issue during network instability testing. When the client loses connectivity and attempts to reconnect, the SDK emits a disconnected event. We catch this and call guest.connect() again.

This is where things break. The reconnection attempt fails with a session_not_found error code. The payload looks like this:

{
 "code": "session_not_found",
 "message": "The session associated with this client ID is no longer valid."
}

We suspect this might be related to how the clientId is persisted in the browser’s local storage. We are currently storing the clientId returned from the initial connect promise and reusing it on reconnect. Is the expectation that a new clientId should be generated for every reconnection attempt, or is there a specific lifecycle method we need to call to refresh the session token before attempting to reconnect?

We have tried clearing the local storage before reconnecting, which forces a new clientId, but this results in the user losing their conversation history and having to start a new chat, which defeats the purpose of the custom UI.

Has anyone implemented a solid reconnection strategy with this SDK? We need to preserve the conversationId and participantId across the reconnect event without triggering the session validation error.

The session_not_found error usually isn’t a bug in the SDK. It’s a timing issue. When the network flaps, the Genesys Cloud backend might clean up the stale WebSocket session before your client tries to reconnect. The standard SDK reconnection logic assumes the session is still valid on the server side, which it often isn’t after a hard disconnect.

You’ll need to intercept the connection failure and force a fresh session initialization instead of relying on the automatic reconnect. Here is how I handle this in our instrumentation code. We listen for the specific error event and trigger a manual reset.

import { GuestSDK } from 'genesys-cloud-web-messaging-guest-sdk';

const sdk = new GuestSDK({
 orgId: 'your-org-id',
 flowId: 'your-flow-id',
 // ... other config
});

sdk.on('error', (error) => {
 if (error.code === 'session_not_found') {
 console.warn('Session expired on server. Forcing re-init.');
 
 // Stop the current instance to clear stale state
 sdk.stop();
 
 // Re-initialize with a new session ID
 // You may want to preserve the conversation ID if you have it stored locally
 sdk.init({
 orgId: 'your-org-id',
 flowId: 'your-flow-id',
 conversationId: storedConversationId || undefined 
 }).catch(err => console.error('Re-init failed', err));
 }
});

This approach prevents the client from getting stuck in a retry loop trying to attach to a ghost session. You should also check your New Relic transactions for these specific error codes. If you’re seeing a high volume of session_not_found events, your network instability is likely causing premature timeouts on the Genesys side. Adjusting the heartbeat interval in your SDK config might help keep the session alive longer during brief flaps, but the manual reset is the most reliable fix for hard disconnects.