Web Chat has no public JavaScript API for production pages today. It does not expose methods such as open() or close(), and it does not dispatch DOM events or postMessage calls your page can listen to. You configure it with data attributes and control it by when you load it.
This page lists what does exist on window, so you know what is safe to ignore and what to avoid depending on.
Summary
| Name | Status | What it is |
|---|---|---|
<natiq-webchat-wrapper> | Public tag name | The custom element that holds the widget. The loader adds it to <body>. |
#natiq-chat-script | Public id | The script tag the widget reads its attributes from. |
data-* attributes | Public | See Configuration. |
window.NatiqWebchat | Preview only | Installed only when data-preview is on. Used by the dashboard's Design tab. |
window.natiqChatScript | Internal | A handle the widget keeps to its own script tag. |
window.__natiqWebchatChunks | Internal | A registry for the widget's lazy-loaded parts. |
localStorage keys | Internal | The visitor id, name, email and colour-scheme preference, scoped to your widget key. |
"Public" means Natiq will not rename it: existing embeds depend on the tag name, the script id and the attribute names. "Internal" means it can change without notice.
Preview-only: window.NatiqWebchat
When a page loads the widget with data-preview="true", the widget becomes a read-only mock with canned conversation content and no backend, and it installs three functions the dashboard uses to show an unsaved design live:
| Method | Argument | Effect |
|---|---|---|
applyPreviewConfig(design) | A design document (plain JSON) | Applies it to the mock widget immediately. |
setPreviewMenuOpen(open) | Boolean | Shows or hides the persistent-menu sheet. |
setPreviewIntroOpen(open) | Boolean | Shows or hides the welcome screen. |
You can queue calls before the bundle arrives by defining a stub with a _q array of [method, argument] pairs; they run in order once the widget loads.
window.NatiqWebchat = { _q: [['applyPreviewConfig', { colors: { mode: 'dark' } }]] }Do not use preview mode on a live site
With data-preview on, a visitor cannot chat: there is no session and no messages are sent. These functions are not installed on a normal embed, so calling window.NatiqWebchat.applyPreviewConfig on your site throws. The design document's shape is the dashboard's own and is not published as a contract.
Patterns that work without an API
Load only when you want the chat
The widget starts when the script tag is inserted. To wait for consent, a login or a route, insert the tag yourself at that moment (see Single-page apps).
Open the chat on first paint
Add data-open="true" to start with the card open. Use it sparingly: it unfolds a panel over your own page.
Show it only on some pages
Include the script tag only on the templates where you want the bubble. The widget stores nothing about which page it was on.
Remove it
Remove the <natiq-webchat-wrapper> element from the DOM to unmount the widget; inserting a new one starts a fresh instance. This follows from how the element is built and is not a documented call, so verify it in your own app first.
Unread badge, chime and title
These are on by default and switched off with the data-notify-badge, data-notify-sound and data-notify-title attributes. The badge and the page-title prefix are the only visible effects on your page; there is no event to hook your own notification to.
Need something that is missing?
If you need to open or close the chat from your own button, read the unread count, or react to a conversation starting, tell support which one. Until a public method exists, do not reach into the widget's shadow DOM or the internal globals above.