Issue

You may observe agents in Flex being moved to Offline status unexpectedly, experiencing missed or delayed call routing, or seeing the UI show Available without receiving tasks until a manual page refresh.

During these occurrences, you or your agents may encounter one or more of the following error messages in the UI or browser console:

• Could not connect to Twilio's servers.
• UnknownError (31000): An unknown error has occurred.
• ConnectionError (31005): A connection error occurred during the call.
• TransportError (31009): No transport available to send or receive messages.
• AccessTokenExpired (20104): The Access Token provided to the Twilio API has expired.

Product

Twilio Flex

Cause

These disconnection issues and routing failures are typically caused by:

1. Browser Tab Sleeping: Web browsers (such as Google Chrome or Microsoft Edge) placing inactive Flex tabs into sleep mode, which interrupts background WebSocket connections.
2. Session Conflicts: Enabling single-session guard settings that trigger rapid session cycling or reconnection loops when multiple tabs or reconnect attempts occur.
3. Browser Disconnects: Manual browser closures, page refreshes, or aggressive local network timeouts sending WebSocket disconnect codes 1000 or 1001, which disrupts token renewal and task reservation routing.

Resolution

Follow these steps to prevent unexpected agent disconnects and restore reliable call routing:

1. Configure Browser Tab Sleep Prevention Implement group policies or browser configurations in Google Chrome or Microsoft Edge to prevent Flex domain tabs from sleeping, discarding, or throttling background timer execution.
2. Evaluate Single-Session Guard Configuration If single-session guard was recently enabled in your environment, temporarily disable or reconfigure it to test if rapid reconnect loops and session conflicts subside.
3. Verify Custom Plugin Token Handling Ensure any custom Flex plugins running in your environment follow standard token refresh logic and do not prematurely expire or override access tokens (20104).
4. Inspect Network and Workstation Environments
   • Confirm that local firewalls, proxies, or security software permit persistent WebSocket connections (Twilsock).
   • Advise agents to avoid frequent tab reloads or running multiple Flex sessions simultaneously.

Additional Information

If issues persist for isolated agents after applying tab sleep policies, collect browser console logs and web socket event logs during the incident to analyze connection behavior.