JavaScript API

Once the widget loads, it exposes a small global object at window.Zev. Use it to open or close the chat, attach details about the visitor, and verify who they are.

Every method is safe to call at any time. Calls made before the widget finishes loading are queued and run once it is ready, so you never have to wait or check whether it is available.

Methods

Zev.open()

Opens the chat panel. Does nothing if it is already open.

Zev.open();

Use it to open chat from your own button:

<button onclick="Zev.open()">Talk to support</button>

Zev.close()

Closes the panel and returns to the floating bubble. Does nothing if it is already closed.

Zev.close();

Zev.toggle()

Opens the panel if it is closed, closes it if it is open.

Zev.toggle();

Zev.set(attributes)

Attaches display attributes to the current visitor. These show on the conversation in your workspace so your team has context. Anything you put in metadata appears alongside the visitor.

Zev.set({
  name: 'Jane Doe',
  email: 'jane@example.com',
  metadata: {
    plan: 'pro',
    signupDate: '2026-01-12',
  },
});

Field	Type	Description
`name`	string	The visitor’s display name.
`email`	string	The visitor’s email address.
`metadata`	object	Any extra key and value pairs to show on the visitor.

Zev.identify(externalId, hmac, attributes?)

Establishes a verified identity for the visitor and links the conversation to a contact in your workspace. Your backend signs the visitor’s id with your brand’s identify secret, and the widget passes the id and the signature through. The secret never enters the browser.

Zev.identify('user_12345', 'the_hmac_your_backend_computed', {
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
});

See Identifying visitors for the full flow, including how to compute the signature on your backend.

The widget loads lazily, so window.Zev may not exist the instant your page runs. You have two safe options.

The simplest is to guard the call:

window.Zev?.open();

If you need to queue calls that should run as soon as the widget is ready, create the queue before the loader runs. Pushes to it are drained in order once the widget mounts:

<script>
  window.Zev = window.Zev || [];
  window.Zev.push({ m: 'set', a: [{ name: 'Jane Doe' }] });
</script>

Next step

Verify who your visitors are in Identifying visitors.