Install the live chat widget

Add the widget to your site with a single script tag. It works on plain HTML, and on any framework or site builder that lets you insert a script.

Add the script

Paste this near the end of your page, just before the closing </body> tag, on every page that should show the chat:

index.html

<script
  src="https://widget.zevworkspace.com/v1/loader.js"
  data-zev-key="pk_live_your_brand_embed_key"
  defer
></script>

Replace pk_live_your_brand_embed_key with your brand’s embed key. That is the only value you need to change.

Get your embed key

1. Open the ZevWorkspace dashboard and go to Settings → Brands.

2. Open the brand you want the chat to belong to.

3. Copy the Public embed key. It looks like pk_live_.... You can also copy the ready-made Embed snippet from the same screen and paste it straight into your page.

The embed key is public. It identifies which brand a conversation belongs to, and it is safe to include in your page source.

Set your embed domains

In the same brand editor, add every domain the widget will run on to the Embed domains list, for example www.example.com and app.example.com.

Caution

The allowlist is the real security boundary, not the key. When the widget connects, the server checks the page’s origin against your allowlist and rejects any origin that is not on it. If the widget loads but never connects, an unlisted domain is the first thing to check.

Optional settings

You can pass a few optional attributes on the same script tag.

Attribute	Purpose	Default
data-zev-launcher	Where the floating bubble appears: default, none, desktop, mobile.	default
data-zev-launcher-selector	CSS selector for your own elements that open the chat on click.	[data-zev-chat]
data-zev-eager	Set to "true" to load the widget immediately instead of lazily. Useful while testing.	false

The launcher options are covered in Custom launchers. Everything else about how the widget looks and behaves is configured in the dashboard, with no code changes. See Customizing the widget.

When the widget loads

The loader is tiny and stays out of your page’s critical path. It waits to fetch the main widget bundle until one of these happens first:

• The browser goes idle after the page finishes loading.
• The visitor interacts with the page by scrolling, tapping, or pressing a key.

This keeps the cost on first paint to just the loader. During development you can skip the wait with data-zev-eager="true".

Framework notes

• Static sites and site builders. Paste the script into your global layout, footer, or a custom HTML block so it appears on every page.
• Single-page apps (React, Vue, and similar). Add the script once in your root HTML document, not inside a component that mounts and unmounts. The widget tracks in-app navigation on its own, so you do not need to re-add it on route changes.
• Next.js. Render the script from your root layout. Loading it after the page is interactive is fine, since the widget is designed to load lazily anyway.

Verify the install

1. Open a page that includes the script.
2. Interact with the page, then look for the chat bubble in the corner.
3. Open it and send a test message. It should appear in your workspace inbox within a second or two.

If the bubble never appears, open your browser console and look for a message starting with [Zev]. A missing or empty data-zev-key and an unlisted embed domain are the two most common causes.

Next step

Make the widget yours in Customizing the widget, or wire up your own trigger in Custom launchers.