# Heilo chat widget and JavaScript SDK The Heilo chat widget is the chat button and chat window on your website or web app: one script, `widget.js`, and your team answers in the Heilo Inbox. The same script gives your page a small JavaScript API, `Heilo('command', …)`, to open the chat from your own button, tell Heilo who the visitor is, fill in contact fields and react to new messages. Building the chat into your own interface instead of using the widget? That is the Chat UI SDK (`HeiloChat`): [Chat Client API and Chat UI SDK](https://app.heilo.chat/docs/client-api). - **Plans**: the widget, this API and identity tokens work on every plan, Free included. Contact custom fields (section 4) need Pro, Business or the free trial. - **Script**: `https://app.heilo.chat/widget.js`, one file with no dependencies, loaded with `async`. - **Website id** (`ws_…`): Websites & widget → your website → Install. The install code there already has it filled in. It is public, so it is fine in your page. - **Global**: `window.Heilo`, a function: `Heilo('open')`, `Heilo('identify', { … })` and so on. ## 1. Install ### The snippet Paste this on every page, right before `` (once in a shared layout or footer file is enough): ```html ``` - The first script is the queue stub. It defines `Heilo` at once, so your code can call `Heilo('…')` before `widget.js` has downloaded: the calls are queued and run in order once the chat is ready. Without the stub, `Heilo` doesn't exist until `widget.js` has run. If you never call `Heilo` yourself, the second tag alone is enough. - `async` keeps your page from waiting for the script. The widget waits for the DOM by itself, so the tags also work in ``. - Load `widget.js` from your Heilo server, don't copy the file: the widget talks to the server it was loaded from, and it gets updates there. - One widget per page: a second copy of `widget.js` on the same page is ignored. The Install tab also has step-by-step guides for common platforms (WordPress, Wix, Google Tag Manager and more), a test page (**Open widget test page**) and an **Is it working?** check that turns green as soon as the widget loads on your site. ### What it adds to your page - One element, `

`, at the end of ``. Everything else lives in its shadow root, so your CSS doesn't reach the widget and the widget's CSS doesn't touch your page. No iframe. - The button sits in the bottom right or bottom left corner (website settings), `position: fixed` with `z-index: 2147483000`. On phones (up to 480 px wide, or up to 500 px tall) the open chat fills the screen and the page behind it doesn't scroll. - Browser storage, no cookies: `localStorage` keys `heilo:YOUR_WEBSITE_ID` (the visitor's chat session) and `heilo:YOUR_WEBSITE_ID:lead` (pre-chat form answered or skipped), `sessionStorage` keys `heilo:YOUR_WEBSITE_ID:open` and `heilo:YOUR_WEBSITE_ID:peek` (window open, message preview dismissed, for this tab). With storage blocked, the chat still works for that page view. - What it sends to Heilo: when the chat starts, the page URL, title and referrer, the browser language, time zone and screen size; then every new URL or title, whether the tab is in the background and a small heartbeat while the visitor uses the page (for the live visitors list); and the visitor's messages, typing and files. - The live connection comes back by itself after a network drop, a computer that slept or a server restart. The messages your team sent meanwhile then show up in the chat without reloading the page, with the sound and the new message preview while the chat is closed. A chat your team ended meanwhile shows as ended, as it would have live. - After-chat rating: when your team closes a chat, the widget asks "How was this chat?" with a thumbs up and a thumbs down, then an optional comment. The visitor can rate within 7 days of the close and change their mind for 24 hours after the first rating (the card shows again on later page loads during that time, until they start a new chat). Turn it off per website under Websites & widget → Automation → **Ask for a rating after the chat** (on by default). Ratings show in the Inbox, in Analytics (CSAT) and in the `conversation.rated` webhook. Messenger and Instagram chats are never asked. ### Attributes and `window.HeiloSettings` | Script attribute | `HeiloSettings` key | What it does | | --- | --- | --- | | `data-website-id` | `websiteId` | Your website id. Required. | | `data-identity-token` | `identityToken` | A signed-in customer's identity token (section 3). | | `data-language` | `language` | Your page's language, used while the widget language is Auto (see `setLanguage`). | | none | `apiBase` | The Heilo server address. Default: the origin of the script's `src`. | ```html ``` - `window.HeiloSettings` must be set before `widget.js` runs, and it wins over the attributes. - The Heilo WordPress plugin also sets `HeiloSettings.identity` (a WordPress customer signed by the plugin). Don't set it yourself. - Queued before `widget.js` loads, `Heilo('init', { websiteId: 'YOUR_WEBSITE_ID' })` also sets the website id. It only works from the queue: once `widget.js` has loaded, `init` is an unknown command. - Embed codes from before the rename to Heilo (`window.ChatMe`, `window.ChatMeSettings`) keep working, and their visitors keep their chat. ### Adding it from your JavaScript code Single-page apps (React, Vue, Svelte, Angular…) can add the script from code. A small helper module: ```js // heilo.js const HEILO_SRC = 'https://app.heilo.chat/widget.js'; /** Heilo('command', …) that also works before widget.js has loaded (calls are queued). */ export function heilo(...args) { window.Heilo = window.Heilo || function () { (window.Heilo.q = window.Heilo.q || []).push(arguments); }; return window.Heilo(...args); } /** Adds widget.js to the page once. Call it when your app starts. */ export function loadHeilo({ websiteId, language } = {}) { if (document.querySelector(`script[src="${HEILO_SRC}"]`)) return; const script = document.createElement('script'); script.async = true; script.src = HEILO_SRC; script.setAttribute('data-website-id', websiteId); if (language) script.setAttribute('data-language', language); document.head.appendChild(script); } ``` ```js import { heilo, loadHeilo } from './heilo.js'; loadHeilo({ websiteId: 'YOUR_WEBSITE_ID', language: document.documentElement.lang }); heilo('on', 'message', (message) => console.log('New reply:', message.body)); ``` - Read `window.Heilo` at call time (as the helper does), don't keep a reference to it: once `widget.js` has loaded, `window.Heilo` is a new function, and calls on an old reference to the stub are never run. - Only call it in the browser. With server rendering (Next.js, Nuxt, SvelteKit…), call it from an effect, a mount hook or an event handler. - Google Tag Manager: its Custom HTML tags drop `data-*` attributes from script tags, so create the script element with JavaScript and `setAttribute('data-website-id', …)` as above. The Install tab has this version ready for Tag Manager. TypeScript declarations: ```ts // heilo.d.ts type HeiloCommand = | 'open' | 'close' | 'toggle' | 'show' | 'hide' | 'isOpen' | 'identify' | 'setFields' | 'send' | 'on' | 'off' | 'setLanguage' | 'setCart' | 'reset'; declare global { interface Window { Heilo?: ((command: HeiloCommand, ...args: any[]) => any) & { q?: IArguments[] }; HeiloSettings?: { websiteId?: string; identityToken?: string; language?: string; apiBase?: string }; } } export {}; ``` ### Single-page apps - Load the widget once, when the app starts. It stays on the page through client-side navigation and notices route changes by itself (it checks the URL and the title every 1.5 seconds), so your team sees which pages the visitor is on. Nothing to call. - There is no command to remove the widget. Hide it with `Heilo('hide')` where you don't want it (section 5). If your framework replaces the whole `` on navigation, the widget goes with it until the next full page load. - Sign-in and sign-out without a page load: `Heilo('identify', { token })` and `Heilo('reset')` (section 3). Language switch: `Heilo('setLanguage', code)`. ### Content-Security-Policy If your site sends a `Content-Security-Policy` header, add: | Directive | Source | For | | --- | --- | --- | | `script-src` | `https://app.heilo.chat` | `widget.js` | | `connect-src` | `https://app.heilo.chat wss://heilo.chat` | the chat session, file uploads and the live connection (WebSocket, with HTTP long polling as a fallback) | | `img-src` | `https://app.heilo.chat` | photos and files in the chat, your logo and button image | | `img-src` | `https://*.googleusercontent.com` | your teammates' profile photos (from their Google accounts) | | `img-src` | `blob:` | optional: previews of files the visitor attaches (without it, the preview appears once the upload is done) | | `style-src` | `'unsafe-inline'` | the widget's own `