# Building a custom Webex Contact Center Agent Desktop widget

Systems: Webex Contact Center

For Webex Contact Center administrators and front-end developers building custom Agent Desktop widgets.

Canonical: https://warmtransfer.net/guides/wxcc-desktop-widget-setup

Last verified: 2026-09-30

Webex Contact Center Agent Desktop is a micro-frontend single-page application that hosts widgets built on a web components architecture[^64]. Custom widgets are developed using web components, and their layout and placement are controlled via desktop layout configurations[^64][^38].

## Before you start

Confirm that you have administrative access to Control Hub and that the developer environment meets the following requirements:
- Access to **Services** > **Contact Center** > **Desktop Experience** > **Desktop Layouts** in Control Hub[^38].
- A test team configured with agent-based routing[^63]. A team with an existing custom layout does not appear in the team drop-down when creating a new desktop layout[^37].
- Node.js package managers (`npm` and `yarn`) to build the widget[^48][^62].
- A supported browser on agent test machines: Chrome 144+, Microsoft Edge 144+, or Firefox 140+[^65].

## What changes by situation

- Where on the Agent Desktop does the widget live? Header widget (always-visible element in the 64 px top bar); Panel widget (tab in the Auxiliary Information pane during an interaction).
- Where is the built widget script hosted? Public HTTPS CDN or object storage; Organisation-controlled internal HTTPS web server.

## Step 1: Clone the starter repository and choose a component name

### Do
Clone the Cisco DevNet `webex-contact-center-widget-starter` repository and install dependencies using `yarn`[^62]. The starter repository provides React (listed at 95% completion), Lit Element web components (95% completion), and Angular (20% completion) starters[^58]. Select either the Lit Element or React starter and work inside `src/components`[^58][^62]. Choose a custom HTML element tag name for the widget (for example, `my-custom-widget`), which will be entered as the `comp` property in the desktop layout without angle brackets (`<` or `>`)[^16][^17].

### Verify
Run `yarn start` in the repository root to start the local playground sandbox on localhost[^62].

### Rollback
Suggested rollback: delete the cloned repository directory.

## Step 2: Scaffold the widget component layout

**Header widget (always-visible element in the 64 px top bar)**

### Do
Design the component to fit within the Agent Desktop horizontal header height of 64 pixels[^19]. Configure the component to present inline information or a drop-down interface[^4]. Remove any interaction-specific or task-specific code paths from the starter, as the starter was designed specifically for the panel area and task functions may not work outside of it[^60].

### Verify
In the starter sandbox, verify that the component layout renders legibly when constrained to a 64-pixel vertical container[^19][^61].

### Rollback
Suggested rollback: discard changes made in `src/components`.

**Panel widget (tab in the Auxiliary Information pane during an interaction)**

### Do
Maintain the starter's standard component structure, as the starter widget is designed specifically for the panel area[^60].

### Verify
In the starter sandbox, toggle between light and dark themes and resize the preview container to verify responsive behaviour[^61].

### Rollback
Suggested rollback: discard changes made in `src/components`.

## Step 3: Install and initialize the Desktop JavaScript SDK

### Do
Install the `@wxcc-desktop/sdk` npm package using `npm install @wxcc-desktop/sdk`, and import the root module with `import { Desktop } from '@wxcc-desktop/sdk'`[^48]. On 2026-09-30, the latest published version of `@wxcc-desktop/sdk` was 3.0.1[^55]. Initialise the SDK before calling any other service modules by calling `Desktop.config.init({ widgetName, widgetProvider })`[^47]. Create a namespaced logger using `Desktop.logger.createLogger('my-custom-widget')` to output prefixed diagnostic logs to the browser console[^50].

### Verify
Suggested check: verify that the project compiles with no missing module errors for `@wxcc-desktop/sdk`.

### Rollback
Suggested rollback: run `npm uninstall @wxcc-desktop/sdk` and remove the import and initialization statements.

## Step 4: Bind data and handle events

**Header widget (always-visible element in the 64 px top bar)**

### Do
Query agent state and team details through `Desktop.agentStateInfo.latestData`, which returns `teamId`, `teamName`, `dn`, `status`, `subStatus`, `idleCodes`, and `wrapupCodes`[^49]. Subscribe to agent state updates with `Desktop.agentStateInfo.addEventListener('updated', handler)` to refresh the widget when the agent changes state[^53]. To change agent availability directly from the widget, invoke `await Desktop.agentStateInfo.stateChange(...)`[^54]. If passing data from the layout configuration, define bindings to `$STORE` values, such as `$STORE.agent.agentName`[^30][^31].

### Verify
Suggested check: verify in the sandbox or local test environment that state change handlers respond to mock agent updates.

### Rollback
Suggested rollback: remove the event listeners and SDK calls from the header component script.

**Panel widget (tab in the Auxiliary Information pane during an interaction)**

### Do
Retrieve the agent's current interactions by calling `await Desktop.actions.getTaskMap()`[^45]. Bind interaction context from the desktop layout using `$STORE.agentContact.taskSelected`[^31]. Register event listeners on `Desktop.agentContact` for contact lifecycles, such as `eAgentContactAssigned`, `eAgentContactEnded`, and `eAgentContactWrappedUp`[^43]. When the component unmounts or tears down, call `Desktop.agentContact.removeEventListener(eventName, listener)` or `Desktop.agentContact.removeAllEventListeners()`[^52]. If making authenticated backend API requests on behalf of the agent, obtain the Desktop access token using `await Desktop.actions.getToken()`[^46].

### Verify
Suggested check: verify that contact event listener callbacks and task map queries execute in the development environment.

### Rollback
Suggested rollback: remove the contact event listeners and task map calls from the panel component script.

## Step 5: Test the component in the local sandbox

### Do
Execute `yarn start` to launch the local development server[^62]. Use the playground sandbox to verify how the custom element behaves across container dimensions and when switching between light and dark themes[^61].

### Verify
Suggested check: verify that the component renders without errors in the browser developer console and adapts cleanly to container resizing.

### Rollback
Suggested rollback: stop the local sandbox development process.

## Step 6: Add the widget configuration to the desktop layout JSON

**Header widget (always-visible element in the 64 px top bar)**

### Do
Download `Default Desktop Layout.json` from the Control Hub Desktop Layouts page[^33]. In the layout JSON, navigate to the `agent` persona section, and optionally `supervisorAgent` if users with combined roles require the widget[^26]. Depending on your downloaded layout structure, custom header widgets are placed in the `header` object inside `area` (which defines an `id`, a `widgets` map with `comp`, and a `layout` object with `areas` and `size`) or under `advancedHeader`[^13][^20][^1]. The help article uses `advancedHeader` for configuring the visibility and order of horizontal header icons, while the developer blog places custom header widgets under `advancedHeader`[^12][^1]. Set `comp` to the custom element tag name without angle brackets[^16][^17]. Set `script` to your local development URL (such as `http://localhost:8000/index.js`), which is exempt from mixed-content blocking[^2][^28][^41]. Add any required `attributes` or `properties`[^15]. Note that re-uploading an unchanged default layout file is still treated as a modified layout[^18], and teams on unmodified layouts receive new layout-based features automatically[^32].

### Verify
Suggested check: validate that the JSON file is syntactically valid and that the widget identifier is referenced in both the widget definitions and layout areas.

### Rollback
Suggested rollback: discard edits and re-download an unmodified copy of `Default Desktop Layout.json`.

**Panel widget (tab in the Auxiliary Information pane during an interaction)**

### Do
Download `Default Desktop Layout.json` from the Control Hub Desktop Layouts page[^33]. In the layout JSON, navigate to the `agent` persona section (and `supervisorAgent` if applicable) under `area.panel`[^26][^24]. Add the custom widget using an `md-tab` and `md-tab-panel` pair alongside the default Cisco-offered tabs in the Auxiliary Information pane[^24]. Set `comp` to the element tag name without angle brackets[^16][^17]. Set `script` to the local development server URL (for example, `http://localhost:8000/index.js`), which loopback addresses allow as secure origins without mixed-content blocking[^2][^28][^41]. Set `wrapper` if a title toolbar with a maximize button is required[^15]. Note that uploading a downloaded default layout file is treated as a modified layout even if unchanged[^18], and teams using unmodified layouts receive new layout features automatically upon sign-in or reload[^32].

### Verify
Suggested check: validate that the JSON is syntactically valid and that the `md-tab` and `md-tab-panel` entries are properly declared under the panel area.

### Rollback
Suggested rollback: discard edits and revert to the original layout file.

## Step 7: Create and assign the desktop layout in Control Hub

### Do
In Control Hub, go to **Services** > **Contact Center** > **Desktop Experience** > **Desktop Layouts** and click **Create desktop layout**[^38]. Enter a name and description, select the test team from the team drop-down, upload the modified layout JSON, and click **Create**[^33]. If the test team already has a custom layout assigned, select and edit that layout instead[^34]. Alternatively, select the layout under the team settings in the **Desktop layout** drop-down[^63].

### Verify
Verify that the layout appears in the layout list with its status set to Active and is assigned to the test team[^36].

### Rollback
Revert the team's assigned layout by editing the team settings and choosing the previous layout in the **Desktop layout** drop-down[^63]. To delete a custom layout, first toggle its status to Inactive, then select delete[^36].

## Step 8: Test live in Agent Desktop against the local development server

**Header widget (always-visible element in the 64 px top bar)**

### Do
Ensure the local server hosting the development script bundle is running[^2]. Sign in an agent assigned to the test team on the same workstation, or reload the Agent Desktop browser if already signed in[^2][^27][^39].

### Verify
Verify that the custom header widget renders within the 64-pixel top bar of the Agent Desktop[^19]. Change the agent's state between Available and Idle to verify that the widget updates without a page reload[^53].

### Rollback
Suggested rollback: stop the local development server and reload the Agent Desktop page.

**Panel widget (tab in the Auxiliary Information pane during an interaction)**

### Do
Ensure the local server hosting the development script bundle is running[^2]. Sign in an agent assigned to the test team on the same workstation, or reload the Agent Desktop browser if already signed in[^2][^27][^39].

### Verify
Accept an incoming contact request to initiate an active interaction[^23]. Verify that the custom panel tab appears in the Auxiliary Information pane and loads data from the active contact[^23][^24].

### Rollback
Suggested rollback: stop the local development server and reload the Agent Desktop page.

## Step 9: Build and publish the production widget bundle

**Public HTTPS CDN or object storage**

### Do
Build the single distribution bundle by running `yarn dist`, which compiles the entire widget into `dist/index.js`[^57]. Note that browsers block HTTP script tags on HTTPS pages as mixed content, so the production script must be served over HTTPS[^42]. Cisco advises against changing the `script` URL for an existing component; if an update is deployed, keep the URL stable or use dynamic imports from the original URL[^29]. Upload `dist/index.js` to a publicly accessible HTTPS CDN or cloud storage service, such as an AWS S3 bucket configured with HTTPS[^3][^59].

### Verify
Suggested check: request the production bundle URL from an external network browser to confirm it returns over HTTPS.

### Rollback
Suggested rollback: remove the uploaded bundle from the CDN or revert to the previously deployed bundle version.

**Organisation-controlled internal HTTPS web server**

### Do
Build the single distribution bundle by running `yarn dist`, which compiles the entire widget into `dist/index.js`[^57]. Note that browsers block HTTP script tags on HTTPS pages as mixed content, so the production script must be served over HTTPS[^42]. Cisco advises against changing the `script` URL for an existing component; if an update is deployed, keep the URL stable or use dynamic imports from the original URL[^29].

### Verify
Suggested check: open the HTTPS URL from a remote agent workstation on VPN to confirm that the script downloads with no certificate errors.

### Rollback
Suggested rollback: remove or unpublish the bundle file on the internal web server.

## Step 10: Update the desktop layout with the production URL

### Do
Open the custom desktop layout in Control Hub by clicking on it to enter editable mode[^34]. Update the `script` property in the JSON file from the localhost URL to the production HTTPS URL[^28]. Save the updated layout[^34]. Have signed-in agents clear their browser cache and reload the Agent Desktop, as recommended by Cisco when updating a component script URL[^27][^29].

### Verify
Suggested check: on an agent workstation without the local development server running, sign in to the Agent Desktop and confirm that the widget loads successfully from the hosted HTTPS location.

### Rollback
Edit the desktop layout in Control Hub and revert the `script` URL to the prior endpoint[^34].

## Step 11: Diagnose common runtime and loading issues

### Do
If the widget fails to load or behave as expected, verify the following configuration items:
- If the widget does not appear, verify that the `comp` value in the layout JSON matches the custom element name practical value and contains no angle brackets (`<` or `>`)[^17].
- Ensure the `script` location uses HTTPS (or localhost for local testing), because non-secure HTTP scripts are blocked by browsers on HTTPS sites[^41][^42].
- If updates are not reflected in the desktop, have the agent clear browser cache and reload to clear cached script definitions[^29].
- For panel widgets, confirm that the agent has accepted an active contact request, as panel tabs do not appear without an active conversation or request[^23].
- If troubleshooting an iFrame widget using `agentx-wc-iframe` that renders a blank space, confirm that the target website does not block embedding via `Content-Security-Policy: frame-ancestors 'none'` or `X-Frame-Options: deny`[^22][^40].
- Check the browser developer console for messages logged via `Desktop.logger`[^50].
- For Desktop-level diagnostic logs, instruct a signed-in agent to download an error report by navigating to **User Profile** > **Help** > **Download Error Report**[^6]. This must be gathered before restarting a crashed browser, as browser logs are cleared on restart[^7].

### Verify
Suggested check: verify that the widget loads cleanly in the Agent Desktop and outputs prefixed log entries into the console.

### Rollback
Suggested rollback: if diagnostic changes were made to layout JSON, re-upload the previous layout.

## Step 12: Roll out layout to production teams

### Do
When creating or configuring layouts, select the team to assign the desktop layout[^33]. Note that a custom layout overrides the global layout default for any team it is assigned to[^35], and each team can have only one custom layout assigned[^37][^63]. Instruct production agents to sign in or reload their browsers to download the newly assigned layout[^27][^39]. When maintaining custom widgets over time, keep the script URL stable to avoid cache inconsistency across agent browsers[^29].

### Verify
Confirm that agents on the assigned production teams see the widget rendered in their Agent Desktop upon reloading[^39].

### Rollback
In Control Hub, open the team settings and clear or change the **Desktop layout** selection to revert the team back to the global or prior layout[^63].

## Applicability

Applies to: Cisco Webex Contact Center, Cisco Webex Contact Center Agent Desktop widgets, Cisco Webex Contact Center Agent Desktop, Web browsers, and Cisco Webex Contact Center Desktop JavaScript SDK. Deployments: multi-tenant and n-a. Sources checked 2026-09-30. The minimum Agent Desktop browser versions are Chrome 144+, Microsoft Edge 144+, and Firefox 140+[^65]. The Desktop JavaScript SDK was verified at version 3.0.1 as of 2026-09-30[^55].

## What remains uncertain

The full list of available `$STORE` keys beyond those documented in examples is not covered by the sources below. The specific payload structures returned by `Desktop.actions.getTaskMap()` and `Desktop.agentContact` event arguments are not covered by the sources below. Whether widget `Desktop.logger` output is bundled into the Desktop error report package downloaded via the user profile is not covered by the sources below. Which fallback layout a team defaults to if an assigned custom layout is toggled Inactive or deleted is not covered by the sources below. The scope and token expiration of the access token returned by `Desktop.actions.getToken()` is not covered by the sources below. Specific CORS, CSP, or SSL certificate requirements enforced by Cisco for hosting custom script bundles are not covered by the sources below.

## Sources

[^1]: The 2023 header-widget blog places header widgets in the advancedHeader area, which it describes as the predefined layout area for header widgets. Source: [Developing With Webex Contact Center Header Widgets: An RSS Feed Reader Example](https://developer.webex.com/blog/developing-with-webex-contact-center-header-widgets-an-rss-feed-reader-example), Exploring the layout.json section. Checked 2026-09-30.
[^2]: The header-widget blog tests by serving the widget from a local development server (npm run serve:cdn, script at http://localhost:8000/...), uploading the layout, assigning it to a team, and signing in to the Agent Desktop while the local server runs. Source: [Developing With Webex Contact Center Header Widgets: An RSS Feed Reader Example](https://developer.webex.com/blog/developing-with-webex-contact-center-header-widgets-an-rss-feed-reader-example), Testing the widget section. Checked 2026-09-30.
[^3]: Cisco's header-widget blog says widgets are loaded from a publicly available URL, usually a content delivery network. Source: [Developing With Webex Contact Center Header Widgets: An RSS Feed Reader Example](https://developer.webex.com/blog/developing-with-webex-contact-center-header-widgets-an-rss-feed-reader-example), Hosting / Running the widget section. Checked 2026-09-30.
[^4]: Cisco's custom-widget blog describes header, navigation (custom page), persistent and headless widgets, built either as iFrame widgets or as web components. Source: [Unlocking the Power of Custom Widgets in Webex Contact Center](https://developer.webex.com/blog/unlocking-the-power-of-custom-widgets-in-webex-contact-center), Widget types and development approaches sections. Checked 2026-09-30.
[^5]: A team on a custom layout, including a re-uploaded copy of the default, probably does not get new Cisco layout features automatically, so the custom JSON must be compared with each new Default Desktop Layout.json (inferred). Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Default layout note, read with the Manage teams note on unmodified layouts. Checked 2026-09-30.
[^6]: A signed-in agent can download a Desktop error report from User Profile > Help > Download Error Report, even while the Desktop is recovering from a connection failure. Source: [Download error reports](https://help.webex.com/en-us/article/neidf/Download-error-reports), Download error reports: procedure and note. Checked 2026-09-30.
[^7]: If the browser crashes before the report is downloaded, the logs are gone after the restart, and the agent must wait for the problem to happen again before downloading. Source: [Download error reports](https://help.webex.com/en-us/article/neidf/Download-error-reports), Download error reports: note on browser crash. Checked 2026-09-30.
[^8]: Cisco's help article puts custom header widgets in area.header and uses advancedHeader for the order and visibility of header icons, while the 2023 developer blog places header widgets under advancedHeader. A builder should extend whichever header structure is in the Default Desktop Layout.json they download, not copy either source verbatim (inferred). Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Header widget JSON example compared with the header-widget blog layout.json section. Checked 2026-09-30.
[^9]: The widget script is loaded into each agent's browser, so its URL must be reachable from every agent's network location. A host reachable only on an internal network works only for agents on that network or VPN (inferred). Source: [Developing With Webex Contact Center Header Widgets: An RSS Feed Reader Example](https://developer.webex.com/blog/developing-with-webex-contact-center-header-widgets-an-rss-feed-reader-example), Hosting section (publicly available URL) and localhost testing section. Checked 2026-09-30.
[^10]: The Agent Desktop is itself loaded over HTTPS, so a production widget script URL has to be HTTPS. Only a localhost URL on the developer's own machine escapes mixed-content blocking. A plain-HTTP script URL, like the one HTTP CDN example in Cisco's layout article, therefore only works against localhost (inferred). Source: [Mixed content](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content), Blockable content and local resources sections, applied to the script examples in the Create custom desktop layout article. Checked 2026-09-30.
[^11]: An agentx-wc-iframe widget works only if the embedded site allows the Agent Desktop origin as a frame parent (no X-Frame-Options deny or restrictive frame-ancestors). Cisco's layout article does not discuss this (inferred). Source: [CSP: frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors), frame-ancestors introduction, applied to the agentx-wc-iframe component. Checked 2026-09-30.
[^12]: The help article describes advancedHeader as the section for customising the visibility and order of the icons on the Desktop's horizontal header. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: advancedHeader. Checked 2026-09-30.
[^13]: Each persona in the desktop layout JSON has an advancedHeader section and an area object. The area object holds header, panel, navigation, persistent and headless, plus homePage for the supervisor personas. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: area objects. Checked 2026-09-30.
[^14]: The layout article says custom logo, title and illustration images can be hosted on a CDN, an AWS S3 bucket or a similar hosting service. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: logo, appTitle and illustration properties. Checked 2026-09-30.
[^15]: A layout widget entry can also carry attributes (HTML or component attributes), properties (component-specific data) and wrapper (adds a toolbar with a title and a maximize icon). Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: widget properties (attributes, properties, wrapper). Checked 2026-09-30.
[^16]: The comp property of a layout widget is the name of the custom HTML element (a web component, or any other element used as a wrapper). Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: widget properties, comp. Checked 2026-09-30.
[^17]: The comp value is entered without angle brackets ('<' or '>'). Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: widget properties, comp. Checked 2026-09-30.
[^18]: If the Default Desktop Layout.json is downloaded and uploaded again unchanged, it is still treated as a modified layout. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: default layout note. Checked 2026-09-30.
[^19]: The Agent Desktop header is only 64 pixels high, and the combined logo and title cannot exceed 304 pixels wide. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: header section. Checked 2026-09-30.
[^20]: The help article's header example defines a header object inside area, with an id, a widgets map (for example head1 with comp header-widget-one) and a layout object that has areas and size (cols, rows). Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: header widget JSON example. Checked 2026-09-30.
[^21]: Headless widgets are hidden and do not appear on the Agent Desktop, but they run logic in the background. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: headless area. Checked 2026-09-30.
[^22]: iFrame-based widgets use the agentx-wc-iframe component, with the embedded page URL given in its src attribute. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: iFrame-based widgets. Checked 2026-09-30.
[^23]: A panel tab appears only when the agent has an active contact request or conversation. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: panel section. Checked 2026-09-30.
[^24]: The Auxiliary Information pane shows tabs for Cisco-offered widgets and custom widgets. Custom panel widgets are defined as tabs with md-tab and md-tab-panel components under the panel area. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: panel / Auxiliary Information pane. Checked 2026-09-30.
[^25]: Persistent widgets show on every Desktop page. During an active interaction they appear as tabs in the Auxiliary Information pane, and they do not show on the Home page in the same way. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: persistent area. Checked 2026-09-30.
[^26]: A Webex Contact Center desktop layout JSON has three persona sections: agent, supervisor and supervisorAgent (for users with both roles). Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: layout JSON structure / persona sections. Checked 2026-09-30.
[^27]: If a new desktop layout is assigned while an agent is signed in, the agent must reload the page to see it. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: assignment note. Checked 2026-09-30.
[^28]: The script property of a layout widget is required only when the widget or component is loaded from a remote location such as a CDN. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: widget properties, script. Checked 2026-09-30.
[^29]: Cisco says not to change the script URL for the same component. If it must change, either have agents clear the browser cache and reload the Agent Desktop, or keep the existing URL and have the JavaScript hosted there dynamically import the new bundle URL. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: script property note. Checked 2026-09-30.
[^30]: To pass real-time Desktop data into a custom widget as properties or attributes, the administrator assigns STORE values in the layout JSON. STORE is currently the only data provider. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: Share Data from Desktop to Widgets. Checked 2026-09-30.
[^31]: Examples of STORE references in the layout JSON include $STORE.agent.agentName and $STORE.agentContact.taskSelected. Source: [Create custom desktop layout](https://help.webex.com/en-us/article/ng08gqeb/Build-a-custom-Desktop-layout), Create custom desktop layout: Share Data from Desktop to Widgets; layout examples. Checked 2026-09-30.
[^32]: Teams on an unmodified layout get new layout-based features automatically when users sign in or reload the browser. Source: [Manage teams in Webex Contact Center](https://help.webex.com/en-us/article/mqf72s/Manage-teams-in-Webex-Contact-Center), Manage teams: Desktop layout field note. Checked 2026-09-30.
[^33]: Creating a desktop layout takes a name, a description and a team, then an upload of the customised JSON file (starting from the Default Desktop Layout.json downloaded from the Desktop Layout page), then Create. Source: [Manage desktop layouts](https://help.webex.com/en-us/article/60x9ji/Manage-desktop-layouts), Manage desktop layouts: Create a desktop layout, General settings and JSON upload. Checked 2026-09-30.
[^34]: An existing desktop layout opens in editable mode when clicked, and its details can be changed and saved. Source: [Manage desktop layouts](https://help.webex.com/en-us/article/60x9ji/Manage-desktop-layouts), Manage desktop layouts: Edit a desktop layout. Checked 2026-09-30.
[^35]: Assigning a custom layout on the Desktop Layouts page overrides the global layout, which is the default layout for all teams. Source: [Manage desktop layouts](https://help.webex.com/en-us/article/60x9ji/Manage-desktop-layouts), Manage desktop layouts: General settings, Team name. Checked 2026-09-30.
[^36]: A desktop layout has an Active/Inactive toggle, and it must be Inactive before it can be deleted. Source: [Manage desktop layouts](https://help.webex.com/en-us/article/60x9ji/Manage-desktop-layouts), Manage desktop layouts: Delete a desktop layout; status toggle. Checked 2026-09-30.
[^37]: A team that already has a custom layout does not appear in the team drop-down when another layout is created. Source: [Manage desktop layouts](https://help.webex.com/en-us/article/60x9ji/Manage-desktop-layouts), Manage desktop layouts: General settings, Team name. Checked 2026-09-30.
[^38]: Desktop layouts are managed in Control Hub under Services > Contact Center > Desktop Experience > Desktop Layouts, where Create desktop layout starts a new one. Source: [Manage desktop layouts](https://help.webex.com/en-us/article/60x9ji/Manage-desktop-layouts), Manage desktop layouts: Create a desktop layout, steps 1-3. Checked 2026-09-30.
[^39]: Desktop users see new layout-based features when they sign in or reload the browser. Source: [Manage desktop layouts](https://help.webex.com/en-us/article/60x9ji/Manage-desktop-layouts), Manage desktop layouts: introductory note. Checked 2026-09-30.
[^40]: The CSP frame-ancestors directive controls which parent pages may embed a page in an iframe. Setting it to 'none' is similar to X-Frame-Options: deny. Source: [CSP: frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors), frame-ancestors: introduction. Checked 2026-09-30.
[^41]: Content loaded from loopback addresses such as http://localhost or http://127.0.0.1 counts as coming from a secure origin, so it is not blocked as mixed content. Source: [Mixed content](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content), Mixed content: local resources note. Checked 2026-09-30.
[^42]: Browsers block scripts requested over HTTP from a page loaded over HTTPS, because script src is blockable mixed content. Source: [Mixed content](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content), Mixed content: Blockable content. Checked 2026-09-30.
[^43]: Desktop.agentContact.addEventListener accepts interaction events including eAgentContact, eAgentContactAssigned, eAgentContactEnded, eAgentContactWrappedUp, eAgentOfferContact, eAgentContactHeld, eAgentContactUnHeld and eAgentConsultCreated. Source: [@wxcc-desktop/sdk README (WxCC Agent Desktop JS-API)](https://unpkg.com/@wxcc-desktop/sdk/README.md), README: Desktop.agentContact section, event list. Checked 2026-09-30.
[^44]: The SDK also exposes contact operations such as Desktop.agentContact.vteamTransfer, Desktop.agentContact.pauseRecording, Desktop.dialer.startOutdial and Desktop.dialer.updateCadVariables. Source: [Leveraging the Webex Contact Center Agent Desktop SDK in Your Custom Widgets](https://developer.webex.com/blog/leveraging-the-webex-contact-center-agent-desktop-sdk-in-your-custom-widgets), Contact operations section. Checked 2026-09-30.
[^45]: await Desktop.actions.getTaskMap() returns the agent's current tasks (interactions). Source: [@wxcc-desktop/sdk README (WxCC Agent Desktop JS-API)](https://unpkg.com/@wxcc-desktop/sdk/README.md), README: Desktop.actions section. Checked 2026-09-30.
[^46]: await Desktop.actions.getToken() returns the Desktop's access token for the widget to use. Source: [@wxcc-desktop/sdk README (WxCC Agent Desktop JS-API)](https://unpkg.com/@wxcc-desktop/sdk/README.md), README: Desktop.actions section. Checked 2026-09-30.
[^47]: A widget initialises the SDK with Desktop.config.init({ widgetName, widgetProvider }) before using the other SDK modules. Source: [@wxcc-desktop/sdk README (WxCC Agent Desktop JS-API)](https://unpkg.com/@wxcc-desktop/sdk/README.md), README: Desktop.config section. Checked 2026-09-30.
[^48]: The Desktop JavaScript SDK is the npm package @wxcc-desktop/sdk. It is installed with npm install @wxcc-desktop/sdk and imported as import { Desktop } from '@wxcc-desktop/sdk'. Source: [Leveraging the Webex Contact Center Agent Desktop SDK in Your Custom Widgets](https://developer.webex.com/blog/leveraging-the-webex-contact-center-agent-desktop-sdk-in-your-custom-widgets), Getting started section: install and import snippets. Checked 2026-09-30.
[^49]: Desktop.agentStateInfo.latestData returns the agent's current data, including teamId, teamName, dn, status, subStatus, idleCodes and wrapupCodes. Source: [@wxcc-desktop/sdk README (WxCC Agent Desktop JS-API)](https://unpkg.com/@wxcc-desktop/sdk/README.md), README: Desktop.agentStateInfo section. Checked 2026-09-30.
[^50]: Desktop.logger.createLogger('name') returns a logger whose info and other methods write service-prefixed messages to the console. The starter's sdk.ts creates one this way. Source: [@wxcc-desktop/sdk README (WxCC Agent Desktop JS-API)](https://unpkg.com/@wxcc-desktop/sdk/README.md), README: Desktop.logger section. Checked 2026-09-30.
[^51]: The SDK's Desktop root module exposes config, i18n, actions, logger and shortcutKey, plus service modules including agentContact, agentStateInfo, dialer, screenpop and aiAssistant. Source: [@wxcc-desktop/sdk README (WxCC Agent Desktop JS-API)](https://unpkg.com/@wxcc-desktop/sdk/README.md), README: Desktop module overview. Checked 2026-09-30.
[^52]: Listeners are removed with Desktop.agentContact.removeEventListener(eventName, listener) or Desktop.agentContact.removeAllEventListeners(). Source: [@wxcc-desktop/sdk README (WxCC Agent Desktop JS-API)](https://unpkg.com/@wxcc-desktop/sdk/README.md), README: Desktop.agentContact section, removal snippet. Checked 2026-09-30.
[^53]: A widget can subscribe to agent state changes with Desktop.agentStateInfo.addEventListener('updated', handler). Source: [@wxcc-desktop/sdk README (WxCC Agent Desktop JS-API)](https://unpkg.com/@wxcc-desktop/sdk/README.md), README: Desktop.agentStateInfo section, addEventListener snippet. Checked 2026-09-30.
[^54]: The SDK can move the agent to Available or Idle through Desktop.agentStateInfo.stateChange, which is awaited. Source: [Leveraging the Webex Contact Center Agent Desktop SDK in Your Custom Widgets](https://developer.webex.com/blog/leveraging-the-webex-contact-center-agent-desktop-sdk-in-your-custom-widgets), Changing agent state section. Checked 2026-09-30.
[^55]: On 2026-09-30 the latest published version of @wxcc-desktop/sdk was 3.0.1, under the ISC license, with entry point ./dist/index.js and bundled TypeScript types. Source: [@wxcc-desktop/sdk package.json](https://unpkg.com/@wxcc-desktop/sdk/package.json), package.json: version, license, main, types. Checked 2026-09-30.
[^56]: To add a widget to a layout, the administrator needs the HTTPS URL of the built JS file, the widget's required properties and attributes, and its preferred preview size or aspect ratio. Source: [webex-contact-center-widget-starter / lit-element README](https://github.com/CiscoDevNet/webex-contact-center-widget-starter/tree/master/lit-element), lit-element README: Integration with Agent/Supervisor Desktop. Checked 2026-09-30.
[^57]: yarn dist builds a dist folder with a single index.js that contains the whole widget. Source: [webex-contact-center-widget-starter / lit-element README](https://github.com/CiscoDevNet/webex-contact-center-widget-starter/tree/master/lit-element), lit-element README: Build section. Checked 2026-09-30.
[^58]: Cisco DevNet's MIT-licensed webex-contact-center-widget-starter offers React (listed 95% complete), Lit Element web components (95%) and Angular (20%) starters. Source: [CiscoDevNet/webex-contact-center-widget-starter](https://github.com/CiscoDevNet/webex-contact-center-widget-starter), README: framework table. Checked 2026-09-30.
[^59]: The starter README says to host the built file on a publicly accessible CDN, giving AWS S3 with HTTPS as an example. Source: [webex-contact-center-widget-starter / lit-element README](https://github.com/CiscoDevNet/webex-contact-center-widget-starter/tree/master/lit-element), lit-element README: Build / deploy section. Checked 2026-09-30.
[^60]: The starter widget is designed for the panel area. The README warns that some task-specific functions may not work if it is placed in another area of the layout. Source: [webex-contact-center-widget-starter / lit-element README](https://github.com/CiscoDevNet/webex-contact-center-widget-starter/tree/master/lit-element), lit-element README: Integration with Agent/Supervisor Desktop. Checked 2026-09-30.
[^61]: The starter sandbox lets a developer switch light and dark themes and resize the container to test widget responsiveness. Source: [webex-contact-center-widget-starter / lit-element README](https://github.com/CiscoDevNet/webex-contact-center-widget-starter/tree/master/lit-element), lit-element README: sandbox section. Checked 2026-09-30.
[^62]: In the Lit Element starter, yarn installs dependencies and yarn start runs a playground sandbox on localhost. Work happens in src/components, with generally no need to change anything outside it. Source: [webex-contact-center-widget-starter / lit-element README](https://github.com/CiscoDevNet/webex-contact-center-widget-starter/tree/master/lit-element), lit-element README: Getting started. Checked 2026-09-30.
[^63]: When editing an agent-based team, the administrator can optionally select a desktop layout from the team's Desktop layout drop-down. Source: [Manage teams in Webex Contact Center](https://help.webex.com/en-us/article/mqf72s/Manage-teams-in-Webex-Contact-Center), Manage teams: create/edit team, Desktop layout field. Checked 2026-09-30.
[^64]: Agent Desktop is a micro-frontend single-page application that hosts widgets built on a web components architecture. Source: [Webex Contact Center Architecture](https://help.webex.com/en-us/article/utqcm7/Webex-Contact-Center-Architecture), Functional Components section, Agent Desktop. Checked 2026-09-30.
[^65]: The minimum supported Agent Desktop browsers are Chrome 144+, Microsoft Edge 144+ and Firefox 140+. Cisco recommends the latest stable versions. Source: [System requirements for Webex Contact Center Desktop](https://help.webex.com/en-us/article/besrkt/System-requirements-for-Webex-Contact-Center), Supported browsers table, Minimum column. Checked 2026-09-30.