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

[productdevbook]

Summary

Audit of src/providers/chatwoot.ts against the live chatwoot/chatwoot SDK source (app/javascript/entrypoints/sdk.js, app/javascript/sdk/IFrameHelper.js, app/javascript/widget/constants/sdkEvents.js) on 2026-04-16, performed because the Mintlify-based developers.chatwoot.com site no longer hosts the visitor SDK reference at the historical URLs.

Gaps found

Missing API surface

• deleteCustomAttribute(key) — vendor exposes $chatwoot.deleteCustomAttribute(key) but our setAttribute has no delete counterpart for contact-scope attrs — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/entrypoints/sdk.js
• deleteConversationCustomAttribute(key) — vendor exposes $chatwoot.deleteConversationCustomAttribute(key); needed to symmetrize setAttribute({scope:"conversation"}) — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/entrypoints/sdk.js
• popoutChatWindow() — vendor first-class method to detach widget into its own window; not exposed — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/entrypoints/sdk.js
• setColorScheme(mode) — vendor exposes $chatwoot.setColorScheme('light'|'auto'|'dark'); our setTheme currently mutates .woot-widget-holder CSS instead of calling the official method — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/entrypoints/sdk.js

Events not bridged

• chatwoot:opened — fires when widget opens (no detail payload); useful for analytics/auto-pause — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/widget/constants/sdkEvents.js
• chatwoot:closed — fires when widget closes (no detail payload); pairs with above — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/widget/constants/sdkEvents.js
• chatwoot:on-start-conversation — fires when a visitor starts a new conversation; useful for funnel/attribution — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/widget/constants/sdkEvents.js
• chatwoot:postback — fires on interactive button/postback in widget; not bridged — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/sdk/IFrameHelper.js

Config options not exposed

• type ('standard' | 'expanded_bubble') — bubble design; only reachable via opaque settings blob, no typed field — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/entrypoints/sdk.js
• widgetStyle ('standard' | 'flat') — widget chrome variant; same as above — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/entrypoints/sdk.js
• darkMode ('light' | 'auto' | 'dark') — first-class theming; setTheme should consume this and the runtime setColorScheme — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/sdk/settingsHelper.js
• position ('left' | 'right'), locale, useBrowserLanguage, hideMessageBubble, showPopoutButton, showUnreadMessagesDialog, launcherTitle, baseDomain — common visitor settings; only reachable through the opaque settings pass-through, not on ChatwootLoadOptions — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/entrypoints/sdk.js

Deprecations in our current code

• setTheme() — our impl mutates color-scheme on .woot-widget-holder and admits "setWidgetColor may not exist"; vendor now ships setColorScheme(darkMode) which is the correct call — https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/entrypoints/sdk.js

Intentionally out of scope

• Client APIs (/public/api/v1/inboxes/.../contacts) — these are server-to-server / mobile alternatives to the JS widget, not part of the visitor JS SDK.
• Admin/Platform/Application APIs surfaced under developers.chatwoot.com/api-reference/*.
• chatwoot:ready, chatwoot:on-message, chatwoot:on-unread-message-count-changed, chatwoot:error — already bridged.
• setLabel / removeLabel / setLocale / setBubbleVisibility (toggleBubbleVisibility) / setUser / setCustomAttributes / setConversationCustomAttributes / toggle (show/hide) / reset (shutdown) — already exposed.
• The Mintlify-restructured developers.chatwoot.com no longer publishes the visitor SDK reference at /sdk/javascript, /docs/product/channels/live-chat/sdk/*, or /help-center/sdk/* (all 404 / 502 / redirect to chatwoot.com root) — vendor source-of-truth is now the chatwoot/chatwoot repo itself.

Sources

• https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/entrypoints/sdk.js
• https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/sdk/IFrameHelper.js
• https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/widget/constants/sdkEvents.js
• https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/sdk/settingsHelper.js
• https://github.com/chatwoot/chatwoot/blob/develop/app/javascript/sdk/constants.js

[productdevbook]

Partially addressed in 87fbc3b:

Shipped:

• setColorScheme(mode) exposed; setTheme() now delegates to it (CSS hack kept only as a fallback for older SDKs).
• deleteAttribute({scope, key}) — symmetric with setAttribute({scope, key, value}), routes to deleteCustomAttribute / deleteConversationCustomAttribute.
• popoutChatWindow() bridges the SDK's detach-to-window method.
• Bundle budget bumped 9KB → 10KB to fit the four new methods.
• 4 jsdom tests added in test/chatwoot.browser.test.ts.

Still open in this issue:

• 4 events not bridged (chatwoot:opened, chatwoot:closed, chatwoot:on-start-conversation, chatwoot:postback)
• Typed config fields (type, widgetStyle, darkMode, position, locale, useBrowserLanguage, hideMessageBubble, showPopoutButton, showUnreadMessagesDialog, launcherTitle, baseDomain) still only reachable through the opaque settings blob.

[productdevbook]

Event bridges shipped in c6ee227:

Now bridged: opened, closed, startConversation, postback — subscribe via chatwoot.on(name, listener). Test coverage: test/chatwoot.browser.test.ts.

Remaining in this issue: typed config fields on ChatwootLoadOptions (type, widgetStyle, darkMode, position, locale, useBrowserLanguage, hideMessageBubble, showPopoutButton, showUnreadMessagesDialog, launcherTitle, baseDomain) — currently only reachable through the opaque settings blob.

[productdevbook]

Typed config fields shipped in 34915c9. All four sub-tasks of this audit are now resolved:

• ✅ setColorScheme + setTheme delegation, deleteAttribute, popoutChatWindow (87fbc3b)
• ✅ Event bridges: opened, closed, startConversation, postback (c6ee227)
• ✅ 11 typed ChatwootLoadOptions fields: type, widgetStyle, darkMode, position, locale, useBrowserLanguage, hideMessageBubble, showPopoutButton, showUnreadMessagesDialog, launcherTitle, baseDomain — opaque settings kept as escape hatch (34915c9)

Closing.