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

[productdevbook]

Summary

Wrapper exposes a small slice of Tawk_API and declares 15 hook fields it never bridges to consumers; several documented methods (popup/toggle/getStatus/isChat*/addTags/login) and config-time fields (visitor preload, customStyle.zIndex, autoStart, onBeforeLoad) are missing, and the bridged onUnreadCountChanged callback is not present in current public docs.

Gaps found

Missing API surface

• maximize() / minimize() — declared in TawkAPI interface but no public wrapper export — https://developer.tawk.to/jsapi/
• toggle() — switch between maximized/minimized — https://developer.tawk.to/jsapi/
• popup() — open chat as separate pop-out window — https://developer.tawk.to/jsapi/
• toggleVisibility() — flip widget hidden/shown — https://developer.tawk.to/jsapi/
• endChat() — only invoked internally inside shutdown(); no standalone public method — https://developer.tawk.to/jsapi/
• start({ showWidget }) — re-open socket after Tawk_API.shutdown / when autoStart: false — https://developer.tawk.to/jsapi/
• getStatus() — returns 'online' | 'away' | 'offline' — https://developer.tawk.to/jsapi/
• getWindowType() — returns 'inline' | 'embed' — https://developer.tawk.to/jsapi/
• isChatMaximized() / isChatMinimized() / isChatHidden() — boolean state queries — https://developer.tawk.to/jsapi/
• isChatOngoing() / isVisitorEngaged() — conversation-state booleans — https://developer.tawk.to/jsapi/
• addTags(tags, cb) / removeTags(tags, cb) — chat tag management (max 10 tags) — https://developer.tawk.to/jsapi/
• login(data, cb) / logout(cb) — declared in interface but never called; current identify() only sends setAttributes with hash, missing the proper login() path that restores past conversations — https://developer.tawk.to/jsapi/
• setAttributes phone field (E.164) — wrapper passes name/email/hash only; phone is documented in visitor{}, login(), and setAttributes() — https://developer.tawk.to/jsapi/

Events not bridged

• Generic public on(event, handler) / off(event, handler) subscription wrapping the 15 declared Tawk hooks; today consumers cannot subscribe to anything except unread count — https://developer.tawk.to/jsapi/
• onBeforeLoad — not declared in the wrapper's TawkAPI interface at all — https://developer.tawk.to/jsapi/
• onPrechatSubmit(data) — pre-chat form payload, not declared — https://developer.tawk.to/jsapi/
• onOfflineSubmit(data) — offline form payload, not declared — https://developer.tawk.to/jsapi/
• onStatusChange / onChatMaximized / onChatMinimized / onChatHidden / onChatStarted / onChatEnded / onChatMessageVisitor / onChatMessageAgent / onChatMessageSystem / onAgentJoinChat / onAgentLeaveChat / onChatSatisfaction / onVisitorNameChanged / onFileUpload / onTagsUpdated — declared on the interface, never bridged to a public listener API — https://developer.tawk.to/jsapi/

Config options not exposed

• Tawk_API.visitor = { name, email, hash, phone } preload — must be set before the embed script loads; wrapper sets identity post-load via setAttributes only, losing the documented preload pattern — https://developer.tawk.to/jsapi/
• Tawk_API.customStyle.zIndex — only documented customStyle field, not exposed — https://developer.tawk.to/jsapi/
• autoStart: false (paired with start()) — defer socket connection until user interaction — https://developer.tawk.to/jsapi/
• onBeforeLoad config-time hook — must be assigned before script download — https://developer.tawk.to/jsapi/
• Multi-property scenarios beyond switchWidget: docs only describe switchWidget({ propertyId, widgetId }, cb); wrapper omits the completion callback — https://developer.tawk.to/jsapi/

Auth modes

• login({ hash, userId, name, email, phone }) is the documented authenticated path and restores past conversations; wrapper currently routes everything through setAttributes({ hash }) and never calls login()/logout() — https://developer.tawk.to/jsapi/

Deprecations in our current code

• onUnreadCountChanged — bridged by onUnreadCountChange() but absent from current developer.tawk.to/jsapi/ callback list; verify it still fires or mark as undocumented/legacy — https://developer.tawk.to/jsapi/
• Tawk_API.shutdown() exists in vendor docs (disconnects socket) but wrapper's shutdown() calls endChat() instead; consider also calling vendor Tawk_API.shutdown() for full socket teardown — https://developer.tawk.to/jsapi/

Intentionally out of scope

• Customization API beyond customStyle.zIndex (no customTabs, no background/position fields documented in current public JS API).
• REST/admin APIs.
• Pop-out window callback limitations (vendor note: "Pop-out chat windows do not support most event callbacks").

Sources

• https://developer.tawk.to/jsapi/

[productdevbook]

All audit findings shipped in f4ae65f:

Methods (16): maximize, minimize, toggle, popup, toggleVisibility, endChat, start, addTags, removeTags, login, logout, plus sync getters getStatus, getWindowType, isChatMaximized, isChatMinimized, isChatHidden, isChatOngoing, isVisitorEngaged. switchWidget now forwards the completion callback. identify() adds phone.

Event bridge: new public on(event, handler) wraps every documented Tawk hook (beforeLoad/load/statusChange/chatMaximized/.../offlineSubmit). All 15 declared hooks are now reachable.

TawkLoadOptions: visitor{} preload (set before script downloads), customStyleZIndex, autoStart, onBeforeLoad.

Test coverage: test/tawk.browser.test.ts (6 cases). Closing.

onUnreadCountChanged legacy bridge retained as-is — backward-compat note in audit kept; will revisit if vendor confirms removal.