liveagent: audit vs current vendor docs (2026-04-16)

[productdevbook]

Summary

Wrapper is missing several documented LiveAgent.* visitor/ticket APIs, button-level callbacks (onOnline/onOffline/onClick/onCloseFunction_), and the auto-tracking control hook; current track() and hide() implementations don't match documented semantics.

Gaps found

Missing API surface

• LiveAgent.addUserDetail(key, value) — modify a single user property (email/firstName/lastName/phone) without resetting the others — https://support.liveagent.com/147815-Set-visitor-specific-values-with-javascript
• LiveAgent.addTicketField(key, value) — assign custom ticket-field values from the visitor side (currently we only use addContactField) — https://support.liveagent.com/147815-Set-visitor-specific-values-with-javascript
• LiveAgent.clearAllUserDetails() — clear all customer data and contact/ticket fields (since v5.17); needed for proper shutdown()/identity reset — https://support.liveagent.com/147815-Set-visitor-specific-values-with-javascript
• LiveAgent.setUserDetails() (no-arg form) — clears all customer data (since v5.17); we never invoke this on shutdown — https://support.liveagent.com/147815-Set-visitor-specific-values-with-javascript
• LiveAgent.setVisitorLocation(url) — set the customer's current page URL into the conversation thread; this is the closest thing to an explicit pageView() call — https://support.liveagent.com/147815-Set-visitor-specific-values-with-javascript
• LiveAgent.disableOnlineVisitorsTracking() — must be callable BEFORE createButton; currently no way to opt out of the per-few-seconds visitor-update polling — https://support.liveagent.com/334470-Disable-online-visitors-tracking-for-high-load-websites
• LiveAgent.instance.hasOpenedWidget() — returns true if any widget is currently open; missing helper for visibility/state queries — https://support.liveagent.com/207659-JavaScript-API
• LiveAgent.createForm(id, element) — alternative to createButton for offline contact-form widgets; not exposed — https://support.liveagent.com/418636-Prefill-email-and-name-for-customer
• LiveAgent.createButton(id, element) second argument — docs use the wrapping element (e) as the second arg; our call only passes the id, which silently drops custom-HTML container support — https://support.liveagent.com/258695-Creating-a-multi-widget

Events not bridged

• button.onOnline = fn (per-button "agents available" callback, since v4.17.3) — https://support.liveagent.com/461948-ButtononOnline-ButtononOffline
• button.onOffline = fn (per-button "agents unavailable" callback, since v4.17.3) — https://support.liveagent.com/461948-ButtononOnline-ButtononOffline
• Chat-started bridge — documented pattern is to monkey-patch mybutton.onClick on the button returned from createButton; we currently expose only an unused, top-level LiveAgent.onChatStarted that the vendor does not document — https://support.liveagent.com/691328-Start-and-Close-chat-events
• Chat-closed bridge — same: docs say override mybutton.onCloseFunction_; not bridged — https://support.liveagent.com/691328-Start-and-Close-chat-events
• Agent-message / customer-message events — only available through the server-side "Live Chat Tracking" plugin (admin configures JS snippets that the server pushes to the client); worth documenting that there is no pure client-side hook — https://support.liveagent.com/839467-Live-chat-tracking-plugin

Config options not exposed

• Button language / position / dimensions / pre-chat form / online-vs-offline design are all configured server-side per buttonId in the LiveAgent admin (Chat Button Settings); document that buttonId carries this configuration and there is no JS override — https://support.liveagent.com/373207-Creating-chat-buttons
• Inline / mobile chat URL parameters (cwid, phone, email, firstName, lastName, note, pt) — no helper for building an inline-chat URL — https://support.liveagent.com/498003-Chat-for-mobile-apps-and-inline-chat

Deprecations in our current code

• track(event, metadata) is implemented as LiveAgent.addContactField(event, metadata ?? true). This pollutes contact fields and is not how LiveAgent models event tracking — events are delivered via the server-configured Live Chat Tracking plugin. Either remove, throw OperationNotSupportedError, or rename and document that it writes a contact field — https://support.liveagent.com/839467-Live-chat-tracking-plugin
• LiveAgentAPI.hideButton?(buttonId) is not present in vendor docs. The optional chaining masks the fact that this method does not exist — hide() is effectively a silent no-op. Either drop it or implement via DOM/CSS on the rendered button container. Vendor docs describe show/hide via window.location.pathname conditionals around createButton, not via a runtime API — https://support.liveagent.com/551283-Advanced-widgets-integrations
• LiveAgentAPI.onChatStarted / onChatEnded declared on the typings as top-level properties of LiveAgent are undocumented — the documented surface is per-button (mybutton.onClick, mybutton.onCloseFunction_). Drop these dead types — https://support.liveagent.com/691328-Start-and-Close-chat-events
• currentSubdomain is captured but never read after load(); either expose it via getConfig() (already does) or drop the duplicate state.

Re-evaluate "unsupported" markers

• pageView() is a hard no-op. Track.js already auto-polls visitor location every few seconds, and LiveAgent.setVisitorLocation(url) exists for SPA route changes. Replace the no-op with a call to setVisitorLocation(info.path) so SPA navigations are reflected in the conversation/visitor view — https://support.liveagent.com/147815-Set-visitor-specific-values-with-javascript
• show() is a comment-only no-op. Vendor offers no runtime show API; documented pattern is to gate the createButton call by window.location.pathname. Either keep as no-op with a clearer doc-comment pointing at the docs, or implement DOM-level show on the injected button container — https://support.liveagent.com/551283-Advanced-widgets-integrations

Intentionally out of scope

• Server-side / agent-side REST ticketing API (https://www.liveagent.com/api/, LiveAgent-api-python).
• Live Chat Tracking plugin configuration (admin-side JS snippets for GA/gtag).
• Salesforce "Live Agent" (different product, frequently conflated in search results).
• Visual/CSS theming of the button (server-side admin config bound to buttonId).

Sources

• https://support.liveagent.com/207659-JavaScript-API
• https://support.liveagent.com/147815-Set-visitor-specific-values-with-javascript
• https://support.liveagent.com/461948-ButtononOnline-ButtononOffline
• https://support.liveagent.com/691328-Start-and-Close-chat-events
• https://support.liveagent.com/839467-Live-chat-tracking-plugin
• https://support.liveagent.com/334470-Disable-online-visitors-tracking-for-high-load-websites
• https://support.liveagent.com/551283-Advanced-widgets-integrations
• https://support.liveagent.com/258695-Creating-a-multi-widget
• https://support.liveagent.com/418636-Prefill-email-and-name-for-customer
• https://support.liveagent.com/373207-Creating-chat-buttons
• https://support.liveagent.com/498003-Chat-for-mobile-apps-and-inline-chat

[productdevbook]

All audit findings shipped in 733323a:

Methods (6): addUserDetail, addTicketField, clearAllUserDetails, setVisitorLocation, createForm, sync hasOpenedWidget(). pageView({path}) no longer a no-op — forwards to setVisitorLocation.

Event bridge: on(chatStarted | chatEnded | online | offline, handler) wraps the button-level callbacks (button.onClick / onCloseFunction_ / onOnline / onOffline) returned from createButton. Replaces the dead top-level type fields.

shutdown() now actually clears user details via clearAllUserDetails.

Load options: disableOnlineVisitorsTracking flag fired before createButton per docs.

Test coverage: test/liveagent.browser.test.ts (6 cases). Bundle within default 6KB. Closing.

Notes from audit retained docs-only:

• track() still writes contact fields (no client-side event API exists; documented limitation).
• hide() continues to optionally call hideButton?(buttonId) — vendor doesn't document it but kept as best-effort with optional chaining.