Iris.init

Usage

Pass your App ID. Every other option is optional. Calls made before iris.js loads wait in a queue.

index.html

Iris.init({ appId: "app_7Hq2xK9mPz" });

Options

All options

Iris.init({
  appId: "app_7Hq2xK9mPz",
  primary: "#D24100",
  mode: "auto",
  radius: "round",
  position: "right",
  launcher: true,
  horizontalPadding: 32,
  verticalPadding: 32,
});

Each option overrides the same setting in Settings → Widget. Leave an option out to keep the workspace value. The defaults are the values a new workspace starts with.

appIdstringRequired#

Your workspace's App ID. Copy it from Settings → Install in the dashboard. It is public, not a secret.

Length: 1 to 64 characters

Example: appId: "app_7Hq2xK9mPz"

primarystringOptional#

The colour of the launcher, the send button and links. Iris picks a readable text colour for it.

Default: "#d24100"Length: up to 100 charactersFormat: any CSS colour: hex, rgb(), hsl(), oklch()

Example: primary: "#D24100"

modestringOptional#

The colour scheme. auto follows the contact's system setting and changes with it.

One of: light dark autoDefault: "light"

Example: mode: "auto"

radiusstringOptional#

The corner style of the panel, the messages and the buttons.

One of: sharp default roundDefault: "default"

Example: radius: "round"

positionstringOptional#

The bottom corner for the launcher and the panel.

One of: left rightDefault: "right"

Example: position: "left"

launcherbooleanOptional#

Shows the launcher. Pass false to hide it and open the widget from your own button with data-iris-open or Iris.open(). To change it later, call Iris.update.

Default: true

Example: launcher: false

horizontalPaddingintegerOptional#

The launcher offset from the left or right edge of the page. The open panel moves with the launcher. Phones ignore it.

Default: 20Range: 20 to 200 px

Example: horizontalPadding: 32

verticalPaddingintegerOptional#

The launcher offset from the bottom edge of the page. The open panel moves with the launcher. Phones ignore it.

Default: 20Range: 20 to 200 px

Example: verticalPadding: 32

Init or update

To change launcher after the widget starts, call Iris.update. To change another option, reload the page with new Iris.init options.

On phones

On screens narrower than 480 px, the widget opens full screen. The launcher offset has no effect there.

Console warnings

Message	What happened	Fix
Iris: the widget did not start, because the App ID is missing or not valid.#	Iris.init got no appId, an empty one or one longer than 64 characters.	Pass your App ID as appId. Copy it from Settings → Install.
Iris: ignored <option>: <value>, because it is not a valid value.#	An Iris.init option or a widget setting is outside its limits, such as verticalPadding: 300. Iris used the workspace value.	Use a value within the limits of the Iris.init options.