Troubleshooting Webex Contact Center desktop layout and widget errors

See also

Sources

1. 1
   Webex Contact Center allows up to 200 active desktop layouts.

   System limits in Webex Contact Center · configuration limits table, Desktop layouts / Active row · Checked 2026-10-02
2. 2
   An agent who belongs to several teams probably gets the layout of the team picked at sign-in, so picking a different team is a likely cause of 'wrong layout' reports.inferred

   Sign in to Agent Desktop · Sign in procedure, team selection step · Checked 2026-10-02
3. 3
   An agent can restore the default view of a single page or widget with Edit Layout > Reset Layout and then confirming.

   Get started with Agent Desktop · Reset Layout section · Checked 2026-10-02
4. 4
   Cisco's Analyzer iFrame widget sample embeds an Analyzer report by changing the iFrame navigation widget's src in the layout JSON to the report URL, uploading the layout, and signing in to the team.

   webex-contact-center-api-samples / widget-samples / iframe-widget-sample · README.md, implementation steps · Checked 2026-10-02
5. 5
   If a team already has a custom layout assigned, that team does not appear in the team drop-down when you create another desktop layout.

   Manage desktop layouts · Create a desktop layout procedure, team selection step · Checked 2026-10-02
6. 6
   Cisco's Agent Desktop troubleshooting article lists browser minimums of Chrome 76.0.3809, Firefox ESR 68 and Edge Chromium 79.

   Troubleshoot Webex Contact Center Agent Desktop · Browser Requirements section · Checked 2026-10-02
7. 7
   Cisco names its offered widgets as Contact History, Cisco Webex Experience Management, IVR Transcript, Preview Campaign Call Guide and Screen Pop.

   Create custom desktop layout · Auxiliary Information Pane section · Checked 2026-10-02
8. 8
   The comp property holds the custom HTML element name and is entered without angle brackets.

   Create custom desktop layout · widget property definitions, comp · Checked 2026-10-02
9. 9
   In Control Hub, desktop layouts are managed under Services > Contact Center > Desktop Experience > Desktop Layouts.

   Manage desktop layouts · Create a desktop layout procedure, step 1 · Checked 2026-10-02
10. 10
    Assigning a custom layout to a team overrides the Global Layout, which is the default layout for all teams.

    Manage desktop layouts · Create a desktop layout procedure, team selection step · Checked 2026-10-02
11. 11
    A desktop layout must be set to Inactive before it can be deleted, and a confirmation prompt appears before removal.

    Manage desktop layouts · Delete a desktop layout section · Checked 2026-10-02
12. 12
    An agent can download an error report from User Profile > Help > Download Error Report, even while the Desktop is recovering from a connection failure, and share it with an administrator.

    Download error reports · Download error reports procedure · Checked 2026-10-02
13. 13
    The top-level dragDropEnabled property defaults to false; set it to true to allow drag-and-drop and resizing of widgets on custom pages.

    Create custom desktop layout · JSON Layout Top-Level Properties > dragDropEnabled · Checked 2026-10-02
14. 14
    If the browser crashes before the error report is downloaded, the logs are gone after restart, so the agent has to wait for the problem to recur and then download.

    Download error reports · Download error reports procedure, note · Checked 2026-10-02
15. 15
    The JSON examples in Cisco's layout article show a top-level version value of 0.1.0, but the article states no required or allowed values for it.

    Create custom desktop layout · JSON Layout Top-Level Properties code examples · Checked 2026-10-02
16. 16
    If a feature enabled in the JSON layout does not appear on the Desktop, Cisco says to contact Cisco Support to enable it.

    Create custom desktop layout · JSON Layout Top-Level Properties (note) · Checked 2026-10-02
17. 17
    The Agent Desktop can show a banner at the top saying some features aren't available.

    Sign in to Agent Desktop · Banner message section · Checked 2026-10-02
18. 18
    The CSP frame-ancestors directive names the parents allowed to embed a page in a frame, iframe, object or embed; the value 'none' is similar to X-Frame-Options: deny.

    CSP: frame-ancestors · introduction and syntax notes · Checked 2026-10-02
19. 19
    frame-ancestors cannot be set in an HTML meta element; it must be sent as an HTTP response header.

    CSP: frame-ancestors · note on meta element support · Checked 2026-10-02
20. 20
    The Global Layout is system-generated, and when you create a team it is set automatically as that team's desktop layout.

    Create custom desktop layout · Overview section, Global Layout definition · Checked 2026-10-02
21. 21
    The Desktop header container is only 64 pixels high, so header widgets should use a single-row layout.

    Create custom desktop layout · Header Widgets section · Checked 2026-10-02
22. 22
    For iframe-based header widgets, Cisco recommends the style height:64px;display:flex.

    Create custom desktop layout · Header Widgets section · Checked 2026-10-02
23. 23
    Agents cannot rearrange or resize header widgets or default page widgets such as Agent Performance Statistics.

    Get started with Agent Desktop · Drag-and-Drop and Resize section · Checked 2026-10-02
24. 24
    Widgets in the headless section are hidden from the Agent Desktop and run logic in the background.

    Create custom desktop layout · Headless Widgets section · Checked 2026-10-02
25. 25
    An agentx-wc-iframe widget that renders blank or 'refused to connect' most likely points at a page whose frame-ancestors or X-Frame-Options does not allow the Desktop's origin; the fix belongs on the embedded site's response headers.inferred

    CSP: frame-ancestors · introduction; combined with cisco-help-ng08gqeb-custom-desktop-layout agentx-wc-iframe definition · Checked 2026-10-02
26. 26
    The built-in widget agentx-wc-iframe places any web page into an iFrame as a Desktop widget.

    Create custom desktop layout · Navigation (Custom Pages) widget component description · Checked 2026-10-02
27. 27
    A custom logo can be hosted on a CDN in PNG, JPG, JPEG, GIF, SVG or WebP, and an incorrect URL shows a broken image on the Desktop.

    Create custom desktop layout · JSON Layout Top-Level Properties > logo · Checked 2026-10-02
28. 28
    Because Cisco auto-updates only unmodified layouts, a team on a modified or re-uploaded layout probably will not get new Cisco layout features until an administrator merges them into its JSON.inferred

    Create custom desktop layout · Overview section, unmodified versus modified layout note · Checked 2026-10-02
29. 29
    Drag-and-drop is not supported for additional custom components or widgets added to the More Actions drop-down list.

    Create custom desktop layout · Auxiliary Information Pane section (limitation note) · Checked 2026-10-02
30. 30
    Cisco's navigation widget walkthrough defines custom pages in layout.json with paired nav and page objects and embeds content with agentx-wc-iframe.

    Enhancing Agent Productivity by Creating Navigation Widgets in Webex Contact Center · layout.json code examples · Checked 2026-10-02
31. 31
    A custom navigation page entry uses label, icon, iconType (momentumDesign or other), a unique navigateTo page name and align (top or bottom), with isDefaultLandingPage optional.

    Create custom desktop layout · Navigation (Custom Pages) section, nav properties · Checked 2026-10-02
32. 32
    Cisco's layout administration articles reviewed here publish no catalogue of the validation or rejection messages Control Hub shows when a layout JSON upload fails.inferred

    Manage desktop layouts · whole article; checked against cisco-help-ng08gqeb-custom-desktop-layout whole article · Checked 2026-10-02
33. 33
    Persistent widgets show on all Desktop pages, but they appear as a new tab in the Auxiliary Information pane only while there is an active contact request or conversation.

    Create custom desktop layout · Persistent Widgets Configuration section · Checked 2026-10-02
34. 34
    If you assign a new desktop layout while an agent is signed in, the agent must reload the page to see it.

    Create custom desktop layout · Overview section · Checked 2026-10-02
35. 35
    An agent can restore the default view across all pages and custom tabbed widgets with User Profile > Reset Entire Desktop Layout.

    Get started with Agent Desktop · Reset Entire Desktop Layout section · Checked 2026-10-02
36. 36
    Downloading Default Desktop Layout.json and uploading it again counts as a modified layout, even if the content is unchanged.

    Create custom desktop layout · Overview section, unmodified versus modified layout note · Checked 2026-10-02
37. 37
    The optional script property of a widget is needed only when the widget or component loads from a remote location such as a CDN.

    Create custom desktop layout · widget property definitions, script · Checked 2026-10-02
38. 38
    Cisco tells administrators not to change the script URL for the same component in the layout JSON.

    Create custom desktop layout · widget property definitions, script (note) · Checked 2026-10-02
39. 39
    Cisco's Desktop SDK widget walkthrough calls Desktop.config.init() in its sample widget code.

    Leveraging the Webex Contact Center Agent Desktop SDK in Your Custom Widgets · sample widget code · Checked 2026-10-02
40. 40
    Cisco's widget starter repository is boilerplate for React, Angular and Web Components (Lit Element) widgets and uses the @wxcc-desktop/sdk package.

    CiscoDevNet/webex-contact-center-widget-starter · README, overview and installation · Checked 2026-10-02
41. 41
    For a custom widget to receive real-time Desktop data through properties or attributes, the layout JSON must assign the appropriate $STORE values.

    Create custom desktop layout · Share Data from Desktop to Widgets section · Checked 2026-10-02
42. 42
    When a supervisor signs in to the Desktop, the layout of their primary team is applied.

    Create custom desktop layout · JSON Layout Top-Level Properties > Roles (supervisor) · Checked 2026-10-02
43. 43
    An agent's custom Auxiliary Information pane tab order survives navigation, browser reload, cache clearing and sign-out, but the tab selection is lost when the cache is cleared.

    Get started with Agent Desktop · Auxiliary Information pane tab ordering · Checked 2026-10-02
44. 44
    The selected Auxiliary Information pane tab resets to the default tab when the user signs out, reloads the browser, or clears the browser cache.

    Create custom desktop layout · Auxiliary Information Pane section · Checked 2026-10-02
45. 45
    An agent chooses a team from the Team drop-down when signing in, and the Desktop's appearance depends on the layout the administrator configured.

    Sign in to Agent Desktop · Sign in procedure, team selection step and introduction · Checked 2026-10-02
46. 46
    Changes to Teams and Desktop Layouts are linked bidirectionally, so an update to one can affect the other and both may appear together in audit logs.

    Manage desktop layouts · note on Teams and Desktop Layouts bi-directional relationship · Checked 2026-10-02
47. 47
    For agent-based teams, the team create or edit page has a Desktop Layout drop-down for selecting the team's layout.

    Manage teams in Webex Contact Center · Create a team procedure, Desktop Layout field · Checked 2026-10-02
48. 48
    After changing the notification timeout settings in the layout, the browser must be refreshed for the change to take effect.

    Create custom desktop layout · JSON Layout Top-Level Properties > notificationTimer · Checked 2026-10-02
49. 49
    When an API request or event fails to load data, the Desktop shows an error dialog whose Error Details link lets the user copy a Tracking ID for the administrator.

    Resolve error issues · Resolve error issues procedure · Checked 2026-10-02
50. 50
    Each widget needs a unique area name, and each component a unique identifying value.

    Create custom desktop layout · area and widget property definitions · Checked 2026-10-02
51. 51
    With an unmodified layout, new layout-based features appear automatically, and Desktop users see them when they sign in or reload the browser.

    Manage desktop layouts · Create a desktop layout procedure, note on unmodified layouts · Checked 2026-10-02
52. 52
    Creating a custom layout in Control Hub means downloading the Default Desktop Layout.json file, customising it, uploading the edited JSON, and clicking Create.

    Manage desktop layouts · Create a desktop layout procedure, steps 4-6 · Checked 2026-10-02
53. 53
    The visibility property controls whether Cisco-offered widgets in a custom layout are shown, and its values are built in and defined in the default JSON file.

    Create custom desktop layout · Auxiliary Information Pane, visibility property · Checked 2026-10-02
54. 54
    Cisco Developer Relations presents iFrame widgets and Web Components as the two ways to build custom Desktop widgets, both defined through layout.json.

    Unlocking the Power of Custom Widgets in Webex Contact Center · widget types section · Checked 2026-10-02

Documents

Cite this page

WarmTransfer. (2026, October 2). Troubleshooting Webex Contact Center desktop layout and widget errors. WarmTransfer. https://warmtransfer.net/knowledge/wxcc-desktop-layout-troubleshooting

@misc{warmtransfer-wxcc-desktop-layout-troubleshooting,
  title  = {Troubleshooting Webex Contact Center desktop layout and widget errors},
  author = {{WarmTransfer}},
  year   = {2026},
  url    = {https://warmtransfer.net/knowledge/wxcc-desktop-layout-troubleshooting},
  note   = {Verified 2026-10-02}
}