Widget API

Load timing#

The launcher does not appear immediately. When the DOM is ready it fetches the organization's settings (up to 3 seconds), then waits for either showAfterSeconds after the window load event (default 1 second) or, when the organization enabled lcpGated, for the page's Largest Contentful Paint to settle (up to 8 seconds; browsers that report no LCP, some older versions of Safari among them, wait for the first key press, pointer press or scroll, or the 8 seconds). Actions called before then are queued and run once the launcher exists (see Actions are queued).

When the settings request is refused (HTTP 400 to 404: a site that is not allowed, or a clientId no workspace has), the launcher stays hidden instead of showing a button that would open an empty panel. It logs one console warning, [bettercom] hidden: unknown clientId or site not allowed, and the ready event does not fire. Queued and later actions do nothing. A slow or failing settings server (no answer within 3 seconds, a 5xx, a network error) still shows the launcher with the default look, so a visitor can reach you when the server recovers.

Browsers#

The widget's scripts are ES2020 and its styles target Chrome 87, Edge 88, Firefox 78 and Safari 14 or later. On an older browser the chat may not open (the launcher then says it could not load); the host page is never affected.

Content Security Policy#

A page with a CSP needs these directives for the widget host (https://YOUR_HOST): script-src (the loader, the helper, the panel and language scripts), connect-src for https://YOUR_HOST and wss://YOUR_HOST (API requests and the chat socket), img-src for avatars, logos and uploaded images, plus blob: for the preview of an image before it is sent, and media-src for voice messages and videos, plus blob: to play a voice message back before it is sent. No 'unsafe-inline' is needed: the widget's styles are constructed stylesheets inside its shadow root, which style-src does not govern (browsers without constructable stylesheets, before Safari 16.4, use a <style> element in the shadow root instead and need style-src 'unsafe-inline'). A voice call is set up over the chat socket; its audio then travels over WebRTC through the STUN and TURN servers the server names, which we have not yet tested under a strict policy. The Performance and CSP page has the directives ready to paste.

Allowed domains#

An organization can restrict the domains the widget may load on (Settings, Installation, Allowed domains). When a list is set, the loader and the widget's API requests from any other origin are refused with HTTP 403, and the widget does not appear.

Supporting the async stub#

Sites that load the widget asynchronously can stub window.bettercom and queue calls before the launcher arrives. The launcher drains the queue on load, in order. Every call works through the queue, event handlers included:

<script>
  window.bettercom = window.bettercom || function () {
    (window.bettercom.q = window.bettercom.q || []).push(arguments)
  }
  window.bettercom('on', 'ready', function () { /* widget is on the page */ })
  window.bettercom('identify', { userId: 'u_123', userHash: '...', email: 'ada@example.com' })
  window.bettercom('update', { darkMode: true })
</script>

Without the stub, calling window.bettercom(...) before the script has loaded throws, because the function does not exist yet.

Actions are queued#

boot, identify, setLocale, consent, on and off apply immediately (consent reaches the server as soon as the visitor exists, right after the launcher's settings request; identify once the visitor exists and your page has finished loading, see User). shutdown also applies at once, also before the launcher exists. Every other action called before the launcher has finished its first load (settings fetch plus the load timing described above) is queued and replayed in order once the launcher exists. After shutdown, those actions wait the same way until the next boot. open, close, show and hide are idempotent; toggle is not, by definition.

bettercom('boot', config)#

Starts the widget if it has not started yet (or again after shutdown), and applies darkMode, user and locale from the payload. Calling it twice is safe: the second call only applies its fields.

window.bettercom('boot', {
  darkMode: true,
  user: { name: 'Ada Lovelace', email: 'ada@example.com' }
})

Accepts clientId, darkMode, user, locale and tracking.

A clientId different from the running one removes the current widget (its open panel and connection included) and starts again for the new organization, with that organization's settings, visitor and storage keys. The first organization's visitor stays stored for when you switch back.

bettercom('update', patch)#

Apply a partial update at runtime. An open conversation re-renders without losing its open/close state, scroll position, or in-flight typing.

// Switch theme
window.bettercom('update', { darkMode: true })

// Pre-identify (hides the in-widget identify form)
window.bettercom('update', { user: { name: 'Ada Lovelace', email: 'ada@example.com' } })

// Combine
window.bettercom('update', { darkMode: false, user: { email: 'guest@example.com' } })

bettercom('open') / bettercom('close') / bettercom('toggle')#

show and hide are the same as open and close (kept for existing sites).

Open / close / flip the panel. The first open lazy-loads the conversation bundle. Opening moves keyboard focus into the panel (a dialog named after your brandName); closing returns it to the launcher. The visitor can also close the panel with Escape. A closed panel is hidden and out of the tab order.

On phones (screens up to 480 px wide, and landscape phones up to 480 px tall) the open panel is a full-screen sheet: it fits the visible viewport (above the on-screen keyboard, inside the safe-area insets; on a page with viewport-fit=cover the colored header reaches under the status bar and its content stays below it), the page behind it does not scroll (the widget sets overflow: hidden on html and body while the sheet is open and restores your values when it closes), the sheet is opaque (your page never shows through it), and Tab stays inside the sheet.

bettercom('identify', user)#

Tells the widget who the visitor is: name, email, your own user id (with its hash, to prove it) and custom attributes. Fields are merged with what you sent before. A different userId never keeps the previous userHash; the same userId does, so a later call that only adds attributes or an email (identify({ userId, attributes })) stays verified.

window.bettercom('identify', {
  userId: 'u_123',
  userHash: '4f1c...e9',   // hex HMAC-SHA256 of the userId, computed on your server
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  attributes: { plan: 'pro', seats: 12, trial: false }
})

The widget sends it to the server once the visitor exists (right after the launcher's settings request, so the panel does not have to be open), and again whenever it changes. See User for every field, the limits and identity verification.

bettercom('setLocale', locale)#

Sets the visitor's language at runtime, for example when your site's own language switcher changes. locale is a BCP 47 tag ('fr', 'fr-CA'; 'pt_BR' is accepted too). It applies at once, also before the widget has finished loading, and the open panel switches its text in place (nothing reloads, the conversation and the draft stay). null or '' removes your choice, so the workspace default and the browser decide again. The choice also holds for a later boot in the same page view.

window.bettercom('setLocale', 'de')
window.bettercom('setLocale', null) // back to workspace default / browser

bettercom('consent', value)#

Grants or revokes page-view tracking at runtime, for example from your cookie banner. true or 'granted' grants, false or 'denied' revokes, null leaves it to the workspace's setting. It applies at once: storage moves between persistent and session-only, page views start or stop, and the server is told (and, on a revoke, deletes the page history it stored for the visitor). The widget does not remember the choice itself: pass it on every page load (bettercomConfig.tracking or boot), as your consent tool knows it. See Consent and tracking.

window.bettercom('consent', true)   // the visitor accepted
window.bettercom('consent', false)  // the visitor declined or withdrew

bettercom('on', event, handler) / bettercom('off', event, handler?)#

Adds or removes an event handler. off without a handler removes every handler of that event. Handlers survive shutdown and boot. A handler that throws does not affect the widget or other handlers (the error is rethrown asynchronously, so it still shows in the console). See Events.

bettercom('shutdown')#

Removes the widget and forgets the visitor on this browser. Call it on logout. It applies at once, also when the launcher has not appeared yet (a logout that navigates away right after the call leaves nothing stored), and a settings or identify answer still in flight is ignored. It:

• closes the chat connection (agents see the visitor go offline) and unmounts the panel, firing close first when the panel was open;
• ends a voice call in progress (the agent is told, the microphone and the call connection are released);
• removes the widget's host element, the helper and panel scripts and their internal handles (window.__bettercomHelper, window.__bettercomConversation), and every listener and timer the widget added; history.pushState and history.replaceState are restored (unless another script wrapped them after the widget did);
• clears the visitor id and token (both cookies and localStorage), the remembered panel state and view, the dismissed-preview marker, and the unsent-message queue in sessionStorage.

window.bettercom itself stays, and nothing starts the widget again until the next bettercom('boot'), which starts it in the same page view, as a new anonymous visitor. Event handlers stay registered; the user passed to identify is forgotten.

Identity verification#

Without verification, identity is a claim: anyone can call identify with any name, email or user id, so do not treat it as authentication. With verification, the widget joins a returning user to their earlier conversations on any device.

1. In the dashboard, create the workspace's identity secret (keep it on your server; never put it in the page).
2. On your server, compute userHash = hex(HMAC-SHA256(secret, userId)) for the signed-in user and render it into the page.
3. Pass both: bettercom('identify', { userId, userHash, ... }).

// Node.js, on your server
const userHash = require('crypto').createHmac('sha256', IDENTITY_SECRET).update(String(user.id)).digest('hex')

When the hash matches, the visitor is that user: earlier conversations of the same user (on other browsers or devices) come along, and the widget switches to that visitor if needed (an open panel reconnects as it).

When the hash does not match, or is missing while the workspace requires verification, the visitor is not verified: no earlier conversations come along, and the widget logs one console warning (identify: userHash rejected...). With Require verification on, nothing from that call is saved. With it off, the name, email and user id are saved, marked unverified for your team, and never used to join conversations; a visitor who is already verified keeps its name and email.

Consent and tracking#

Page-view tracking is on by default. It is off when your page says so (bettercomConfig.tracking: false, boot/update with tracking: false, or bettercom('consent', false)), or when the workspace turned page views off in its settings and your page has not granted consent.

With tracking off the widget:

• sends no page-view pings and installs no navigation listeners (if it already installed them, they stay but send nothing), and does not report panel opens (/v1/widget/open);
• keeps only session storage, as in the table above (granting or revoking at runtime moves what is stored, so nothing persistent is left after a revoke);
• tells the server, which then skips device and location enrichment for the visitor. A returning visitor in a new browser session starts as a new visitor, unless you identify them with a verified user id.

Chat itself works the same either way.

What the widget sends:

• Page views (tracking on only). On load and on every in-page navigation, a ping with the page's hostname, path, and hash. To observe single-page-app navigation the launcher wraps history.pushState and history.replaceState and listens for popstate, hashchange, and pagehide.
• Device and location (tracking on only). The server derives device information from the user agent and an approximate location from the IP address (GeoIP), plus the browser's time zone (the settings request leaves the time zone out when your page has declined tracking).
• Identity, when your page calls identify (see User).
• Consent, when your page sets or changes it.
• Language file. When the visitor's language is not English and the server serves it, one request for that language's strings to the widget host (no visitor data in it).
• Unread checks. While the panel is closed and the tab is visible, the launcher asks for the visitor's unread count every 30 seconds and when the tab comes back into view. Hidden tabs do not ask. When the answer carries a message preview the visitor has not dismissed, the helper is fetched (after load, about 2.3 KB; not the panel) to draw the preview bubble.

Several tabs#

Tabs of your site in the same browser share one visitor. Open panels keep each other current over a BroadcastChannel named bettercom-<id> (no storage, nothing leaves the browser): a message sent in one tab appears in the others' open conversation. The unread count and preview bubble are fetched by each tab when it comes into view, so a tab you switch to shows the current count at once (a panel opened in one tab has cleared it on the server). Each tab keeps its own unsent-message queue, so nothing is sent twice. Browsers without BroadcastChannel catch up from the server instead.

Visitor credential#

The visitor id is a public identifier. The server issues a random token with it and keeps only a hash. The token is handed to the widget exactly once: in the response to the launcher's settings request that created the visitor (or that gave a visitor stored before tokens existed its first token). The widget stores both (see the table above).

On every later page load the launcher's settings request presents the stored pair, and the server answers with the same visitor and no token. A request that presents an id without its matching token gets a brand-new, empty visitor (and that visitor's token) instead; the old id opens nothing.

The widget presents the pair the same way everywhere: on its chat connection, and as the X-Bettercom-Visitor-Id and X-Bettercom-Visitor-Token request headers on every visitor request (settings, unread count, page-view ping, panel open, identify, consent, CSAT, uploads, help-article feedback). A visitor request with an id but no matching token is refused. The token never appears in a URL.

The token cookie is readable by scripts on your page, like the id cookie. Anything that can run script on your page can read it and act as that visitor in the chat; keep third-party scripts you do not trust off pages that embed the widget.

Links and images in messages#

Messages, FAQ answers, and help articles are shown with links and images kept only when they are safe: links may use http, https, mailto, or tel; images http or https. A path that starts with a single / (for example an uploaded file at /v1/uploads/...) points at the Bettercom server, not at your site, and opens there. Other relative links (docs/x, ../x, #top) are removed and their text is shown without a link. Every link opens in a new tab.

Sending#

Messages the visitor sends while offline are queued and delivered in order when the connection comes back. The queue also survives a reload of the page (for that browser tab) and is delivered the next time the panel opens. A message the server does not confirm within 10 seconds is sent once more automatically; if that also goes unconfirmed it is marked "Not delivered" with a Retry button. Retrying never creates a duplicate, and the first messages of a new conversation never start a second one. A message that was not delivered stays in its own conversation (or, for a conversation not yet created, comes back when the visitor starts a new one). Reactions are available once a message is delivered. The visitor's latest delivered message is marked "Sent".

When the server refuses a message it says why, in plain words, under the message, and offers what helps:

A message longer than the server accepts is stopped before it is sent, with its text kept. A file over 5 MB is not attached and the visitor is told which one. A failed upload says so (too large, type not accepted, too many at once, not allowed, or a connection problem) and keeps the attachments in the composer for another try.

Connection#

The conversation shows the connection state in words under its header: "Connecting…" (only if it takes more than a moment), "Reconnecting" and "You are offline" (both say that messages sent now will go out later), "Back online." for a few seconds after a reconnect, and "Chat is not reachable right now." with a Retry button when the server closed the connection or the first connection did not succeed within 12 seconds. Screen readers hear these changes and every new message (with who wrote it) through a polite live region. When the visitor comes back to a tab that was in the background, the widget reconnects at once if needed and fetches anything it missed. The connection falls back to HTTP long polling on networks that block WebSockets.

Away and business hours#

When the workspace's business hours are over, its away mode is on, or no teammate is available, the server says so (availability in the widget settings, updated live over the chat connection). The widget then:

• shows an amber status dot and "Away" in the conversation header, with when the team is back in the visitor's own time zone and language ("Back at 9:00", "Back tomorrow at 9:00", "Back Monday at 9:00", "Back on Dec 24 at 9:00");
• shows the same line on Home in place of the reply-time line;
• shows one line above the composer, before the visitor writes: "Leave your email and we'll get back to you." Opening it shows the workspace's own away message (when set), when the team is back, and the email field; the visitor can also dismiss it for that conversation (for the rest of the tab's session). It is not shown when the visitor's email is known (identify, an earlier form, or a required pre-chat email), or when a teammate is assigned to the conversation.

Without that field (older servers) the widget counts the team as online, as before, and offers the email capture only when nobody is online and the visitor has written.

Talk to a person#

While the AI agent (Aura) is the one answering a conversation, the conversation ends with one action: "Talk to a person". Using it sends one request; the action is replaced by "The team has been notified. A teammate will reply here." (also read out to screen readers), and the AI stops answering in that conversation. If the request does not go through, the action comes back with "Could not reach the team. Try again." The row disappears once a teammate takes the conversation. A visitor who types a request for a person ("can I talk to a human?") gets the same result: the server recognizes it. The action appears only when the server supports it.