Skip to main content
widget.js takes its settings from four places: the defaults built into the script, the config saved in the dashboard, the page (window.wiredeskSettings or attributes on the script tag), and wiredesk("update", …) calls at runtime. This page lists every field it reads and explains which source wins. Most of the widget’s look is saved in the dashboard under Agents → your agent → Playground. Only the launcher fields below can be changed per page. Styling inside the panel, such as theme, accent colour, typeface, greeting and suggested questions, always comes from the saved config.

​
Two ways to set a field

window.wiredeskSettings must be set before the script runs. The script reads it once, when it starts.

​
The key

The script looks for the key in this order: wiredeskSettings.key, then wiredeskSettings.widgetKey, then data-widget on its own script tag. When a tag manager injects the script, the browser does not tell the script which tag loaded it. So the script searches the page for a tag whose src starts with https://wiredesk.ai/widget.js, and falls back to any script tag that has a data-widget attribute. If there is no key anywhere, the script logs a warning and draws nothing.

​
The visitor

There is no attribute for this. Set it on wiredeskSettings, or call wiredesk("identify", { … }) after the page loads. The identity is only sent when it has an id. The server trims and caps the fields: id to 128 characters, name to 120, and email to 254. An email that is not a valid address is dropped. hash must be the 64-character lowercase hex HMAC-SHA256 of id.

​
Launcher fields

These can be set per page, and each one overrides the saved config on that page only. What each one does:
  • side: Which bottom corner the launcher and panel sit in. Any value other than "left" means right.
  • launcherColor: The launcher’s background. The icon and label colour is chosen for contrast, black or white, but only from a 6-digit hex. With any other colour format the icon is white.
  • launcherLabel: Text next to the icon, which turns the round bubble into a pill. An empty string keeps the round bubble. The label is hidden while the panel is open.
  • autoOpenSeconds: Opens the panel by itself this many seconds after the page loads, once per browser tab. 0 turns it off. It does not fire if the visitor has already opened the panel on this page, or left it open on a previous page, because that conversation is restored instead.
  • offsetX, offsetY: The gap from the side and bottom of the window to the launcher. The panel sits 68 px above the launcher’s offset.
  • zIndex: The launcher’s stacking order. The panel uses zIndex + 1. The default is just below the browser maximum, so you can still put a cookie banner or checkout overlay above it.
  • hideOnMobile: Hides the launcher when the window is 480 px wide or narrower. You can still open the panel from your own code or from data-wiredesk-open.
  • mobileFullscreen: At 480 px wide or narrower, the open panel fills the visible screen and the page behind it stops scrolling. Set it to false to keep it as a floating card.
The dashboard keeps saved values inside the ranges above. Per-page values do not go through the same check: widget.js converts their type but does not clamp them. Keep per-page values inside the same ranges.
Give boolean attributes a value. data-hide-on-mobile="true" works. A bare data-hide-on-mobile does not, because the script ignores attributes with an empty value.

​
How values are converted

  • Attributes are always strings. Number fields go through Number(). If an offset does not parse as a number, the script falls back to 24.
  • Booleans: "false" and "0" mean false, and any other value means true. On wiredeskSettings you can pass a real true or false.
  • Empty values: an attribute with an empty value, or a wiredeskSettings field set to null or undefined, counts as not set.

​
Precedence

When the page loads, the script builds the launcher from these layers. Later layers win:
  1. The defaults built into widget.js, as listed above.
  2. The saved config this browser cached on a previous page view.
  3. The page’s launcher fields.
It then fetches the current saved config and applies it, with the page’s launcher fields on top again. Each launcher field is read from wiredeskSettings first. The tag attribute is only used when wiredeskSettings does not set that field. Afterwards, wiredesk("update", { … }) merges new values into the running launcher, but page fields still win. If a field is set on the tag or in wiredeskSettings, update cannot change it. To control a field at runtime, leave it off the tag and out of wiredeskSettings.
autoOpenSeconds is checked again whenever the config changes: when the fresh saved config arrives, and on update. A delay saved in the dashboard works on a visitor’s very first page view, with no cached config yet. The delay still counts from when the page loaded, so a config that arrives late does not push the panel back. A page value set on the tag or in wiredeskSettings, including 0, still wins over the saved one.

​
Markup hooks

Any element can open, close or toggle the widget when clicked. No JavaScript is needed:
The script listens for clicks on the whole document, so hooks work on elements added after it loaded, such as after a route change or inside a modal. A click on a child of a hooked element counts too. The script cancels the click’s default action, so a hooked link does not navigate. While the widget is hidden with wiredesk("hide"), open and toggle do nothing.

​
Browser storage

The script keeps a little state in the host page’s storage, keyed by widget key. If storage is blocked, the script keeps working without it. The conversation itself, and the anonymous visitor id, are stored by the panel on WireDesk’s own origin, not on your page. wiredesk("reset") is how you clear them.