> ## Documentation Index
> Fetch the complete documentation index at: https://wiredesk.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget settings reference

> Every window.wiredeskSettings field and data-* attribute widget.js reads, with types, defaults, allowed values and precedence.

`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

<CodeGroup>
  ```html Settings object theme={null}
  <script>
    window.wiredeskSettings = {
      key: "wk_...",
      side: "left",
      offsetY: 96,
      hideOnMobile: true
    };
  </script>
  <script src="https://wiredesk.ai/widget.js" async></script>
  ```

  ```html Tag attributes theme={null}
  <script
    src="https://wiredesk.ai/widget.js"
    data-widget="wk_..."
    data-side="left"
    data-offset-y="96"
    data-hide-on-mobile="true"
    async
  ></script>
  ```
</CodeGroup>

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

## The key

| `wiredeskSettings` field | Attribute     | Type   | Notes                                                           |
| ------------------------ | ------------- | ------ | --------------------------------------------------------------- |
| `key`                    | `data-widget` | string | Your widget key, `wk_` followed by 32 hex characters. Required. |
| `widgetKey`              |               | string | Alias for `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

| `wiredeskSettings` field | Type   | Notes                                                                            |
| ------------------------ | ------ | -------------------------------------------------------------------------------- |
| `user`                   | object | `{ id, hash, name, email }` for a [verified visitor](/docs/widget/verified-visitors). |
| `identity`               | object | Alias for `user`.                                                                |

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.

| `wiredeskSettings` field | Attribute                | Type                  | Default      | Saved-config range     | Dashboard label                     |
| ------------------------ | ------------------------ | --------------------- | ------------ | ---------------------- | ----------------------------------- |
| `side`                   | `data-side`              | `"right"` \| `"left"` | `"right"`    | `right`, `left`        | **Side of the page**                |
| `launcherColor`          | `data-color`             | string                | `"#111111"`  | 6-digit hex, `#rrggbb` | **Bubble colour**                   |
| `launcherLabel`          | `data-label`             | string                | `""`         | up to 40 characters    | **Label**                           |
| `autoOpenSeconds`        | `data-auto-open`         | number                | `0`          | 0–120                  | **Open by itself after**            |
| `offsetX`                | `data-offset-x`          | number (px)           | `24`         | 0–200                  | **Distance from the edge** (side)   |
| `offsetY`                | `data-offset-y`          | number (px)           | `24`         | 0–200                  | **Distance from the edge** (bottom) |
| `zIndex`                 | `data-z-index`           | number                | `2147483000` | 0–2147483647           | **Stacking order**                  |
| `hideOnMobile`           | `data-hide-on-mobile`    | boolean               | `false`      |                        | **Hide on phones**                  |
| `mobileFullscreen`       | `data-mobile-fullscreen` | boolean               | `true`       |                        | **Full screen on phones**           |

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.

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

### 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`.

```js theme={null}
// Works if side is not set on the tag or in wiredeskSettings
wiredesk("update", { side: "left", offsetY: 96 });
```

| Source                   | Scope                   | Beats                                               |
| ------------------------ | ----------------------- | --------------------------------------------------- |
| Built-in defaults        | every page              | nothing                                             |
| Saved config (dashboard) | every page              | defaults                                            |
| `update`                 | this page, until reload | saved config and defaults                           |
| `wiredeskSettings` field | this page               | everything else                                     |
| `data-*` attribute       | this page               | everything except the same `wiredeskSettings` field |

<Note>
  `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.
</Note>

## Markup hooks

Any element can open, close or toggle the widget when clicked. No JavaScript is needed:

```html theme={null}
<button data-wiredesk-open>Chat with us</button>
<button data-wiredesk-open="I need help with billing">Billing help</button>
<button data-wiredesk-close>Close chat</button>
<button data-wiredesk-toggle>Chat</button>
<a href="#wiredesk">Talk to support</a>
```

| Hook                     | Effect on click                                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `data-wiredesk-open`     | Opens the panel.                                                                                   |
| `data-wiredesk-open="…"` | Opens the panel with that text already typed into the message box. The visitor still presses send. |
| `data-wiredesk-close`    | Closes the panel.                                                                                  |
| `data-wiredesk-toggle`   | Opens it if closed, closes it if open.                                                             |
| `href="#wiredesk"`       | Opens the panel, the same as `data-wiredesk-open`.                                                 |

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.

| Key              | Storage          | Holds                                                                                                           |
| ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- |
| `wd_cfg_<key>`   | `localStorage`   | The last saved config, so the launcher draws in your style right away on the next page.                         |
| `wd_open_<key>`  | `sessionStorage` | Whether the panel was open, so it stays open when the visitor moves to another page.                            |
| `wd_auto_<key>`  | `sessionStorage` | That auto-open already fired in this tab.                                                                       |
| `wd_reset_<key>` | `localStorage`   | That `wiredesk("reset")` was called and no panel has cleared the stored conversation yet. Removed once one has. |

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.

## Related

* [JavaScript API](/docs/widget/javascript-api)
* [Events](/docs/developers/events)
* [Install the widget](/docs/widget/install)
* [Widget appearance](/docs/widget/appearance)