Objective

When troubleshooting performance issues, such as UI latency, unresponsive buttons, or failed state transitions, within your Twilio Flex environment, it is crucial to determine if the behavior is caused by the core Twilio Flex platform or your custom client-side plugins.

This guide explains how to perform a Vanilla UI Test. This test temporarily prevents custom plugins from loading in your local browser session. It is completely safe, does not modify your production environment, and will not affect any other active contact center agents.

Why Run a Vanilla UI Test?

Twilio Flex is highly programmable, and most organizations deploy custom plugins to add features, integrate CRMs, or manage custom states. However, conflicts in custom plugin code (such as unoptimized Redux state management or blocking before action listeners) can cause UI performance bottlenecks that mimic platform-level outages.

By blocking custom plugins locally, we isolate the core Flex UI to verify if the issue persists on a completely "clean" instance.

Product

Twilio Flex

Procedure 

Follow these steps in Google Chrome or Microsoft Edge to load a vanilla instance of Flex UI:

Step 1: Log in to your Flex UI

1. Open your browser and navigate to your hosted Flex instance: https://flex.twilio.com/[YOUR_ACCOUNT_SID]
2. Log in with your standard credentials.

Step 2: Open Browser Developer Tools

1. Open the Developer Tools panel by pressing:
   • Windows/Linux: F12 or Ctrl + Shift + I
   • macOS: Cmd + Option + I
2. Dock the DevTools panel to the side or bottom of your browser window so you can still see the Flex UI.

Step 3: Enable Network Request Blocking

1. With the DevTools panel open and active, bring up the Command Menu:
   • Windows/Linux: Ctrl + Shift + P
   • macOS: Cmd + Shift + P
2. Type blocking into the search bar.
3. Select Show Network request blocking from the list and press Enter.
4. At the bottom of the DevTools panel, ensure the checkbox for Enable network request blocking is checked.

Step 4: Add the Block Pattern

1. In the Network Request Blocking tab at the bottom, click the + (Add pattern) button.
2. Enter the exact URL of the Flex plugin-delivery service:

https://flex.twilio.com/plugins?hosted=true&roles=admin

3. Click Add.

• See this example.

Step 5: Reload and Replicate the Issue

1. Refresh your browser page.
2. Verify that the plugin request is blocked:
   • Look at the DevTools Network tab. The request containing plugins will show in red or have a status of (blocked:devtools).
   • The Flex UI should now load in its default state (reverting to standard branding, standard layout, and omitting any of your custom widgets/CRM frames).
3. Try to reproduce the latency or UI issue you originally experienced.

Analyzing Your Test Results

Once you have performed the steps above, evaluate the behavior of your Flex UI to determine the next diagnostic steps:

Scenario A: The issue disappears in the Vanilla UI

If your UI transitions are immediate, buttons respond normally, and latency disappears:

• The Cause: The issue is rooted in your custom plugin code or configuration.
• Troubleshooting Action: Have your development team inspect your custom plugins for:
  1. Blocking Action Listeners: Ensure before action listeners (e.g., beforeAcceptTask) return a Promise or execute the original() action payload without hanging.
  2. Redux Performance: Check for unoptimized Redux state selectors or heavy mutations triggering infinite React re-renders.
  3. React Key Collisions: Ensure unique React keys are specified across custom components in the UI.

Scenario B: The issue persists in the Vanilla UI

If actions are still sluggish, state updates fail, or the interface hangs:

• The Cause: The issue is either environmental (network latency, local machine overhead) or a core Twilio platform/transit issue.
• Troubleshooting Action:
  1. Network Diagnostics: Check for local WebSocket connection interruptions or corporate firewalls blocking WebSocket traffic.
  2. Reporting/Event Delay: If the agent UI updates instantly but downstream systems (CRMs, dashboards) lag, compare the Twilio TaskRouter event creation timestamp against your AWS EventBridge or server webhook logs to pinpoint Event Streams delivery latency.

Additional Information 

What to Provide to Twilio Support

If you need to escalate the issue to Twilio Support after confirming it persists in the Vanilla UI, please capture and provide the following details to accelerate resolution:

1. Account SID: Your unique Twilio account identifier (ACxx...).
2. Worker SID: The SID of the affected agent (WKxx...).
3. Task SID(s): The SIDs of the specific tasks showing the issue (WTxx...).
4. HAR File & Console Logs:
   • Record a network trace (HAR file) in DevTools while replicating the issue.
   • Export and copy any console errors/warnings showing in red.
5. Exact Timestamps: Provide UTC timestamps of when the delay occurred vs when the action completed.