zendesk-classic: audit vs current vendor docs (2026-04-16) — Chat SDK removal in progress

[productdevbook]

Summary

Web Widget (Classic) is restricted to Zendesk accounts created before 2023-06-05 and the underlying Chat Web SDK / Chat Conversation APIs entered active removal on 2025-04-30; the wrapper should warn loudly and close gaps (logout, setLocale, toggle, events, chat/help-center commands) while it is still maintained.

Gaps found

Missing API surface

• zE('webWidget', 'open') / zE('webWidget', 'close') — not exposed as independent methods (our show() conflates show+open, no close()) — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget', 'toggle') — not exposed — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget', 'setLocale', locale) — pageView({ locale }) ignores locale entirely — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget', 'identify', data) — Chat-dashboard identify is different from prefill; today we only call prefill — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget', 'clear') — not exposed — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget', 'reset') — not exposed — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget', 'helpCenter:setSuggestions', {...}) — not exposed — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget', 'chat:end') / chat:reauthenticate — not exposed — https://developer.zendesk.com/api-reference/widget/core/

Events not bridged

• zE('webWidget:on', 'open', cb) — not bridged — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget:on', 'close', cb) — not bridged — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget:on', 'userEvent', cb) — not bridged (cross-channel user interaction telemetry) — https://developer.zendesk.com/api-reference/widget/core/
• zE('webWidget:on', 'chat:unreadMessages', cb) — not bridged; wrapper has no onUnreadCountChange for Classic — https://developer.zendesk.com/api-reference/widget/core/

Config options not exposed

• zE('webWidget', 'updateSettings', { webWidget: { ... } }) — only contactForm.tags is written today; color, position, launcher, chat, helpCenter, answerBot, talk, contactForm, contactOptions are all unreachable — https://developer.zendesk.com/api-reference/widget/core/
• window.zESettings pre-init config object — the wrapper never seeds it before the snippet injects — https://developer.zendesk.com/documentation/classic-web-widget-sdks/web-widget/

Auth modes

• JWT authentication (Chat / Support) via zE('webWidget', 'updateSettings', { webWidget: { authenticate: { chat: { jwtFn } } } }) — wrapper declares "Auth: None" but vendor supports JWT; should model this — https://developer.zendesk.com/api-reference/widget/core/

Deprecations in our current code

• shutdown() calls zE('webWidget', 'logout') — verify signature and consider also calling clear — https://developer.zendesk.com/api-reference/widget/core/
• show() issues both show and open — vendor treats them independently; conflating breaks launcher-only mount — https://developer.zendesk.com/api-reference/widget/core/
• track() overwrites contactForm.tags to Object.keys(metadata) on every call — destructive (replaces, not merges) and uses keys instead of values; should use array values or merge — https://developer.zendesk.com/api-reference/widget/core/
• pageView() calls updatePath with no args — vendor signature is updatePath({ url, title }); no-arg call is a no-op for many account types — https://developer.zendesk.com/api-reference/widget/core/

Vendor product status

• Web Widget (Classic) is only available on Zendesk accounts created before 2023-06-05; newer accounts cannot use this wrapper — add a runtime warning in load() and in the package README — https://support.zendesk.com/hc/en-us/articles/4429429087002-Comparing-the-Zendesk-Web-Widgets
• Underlying Chat Web SDK and Chat Conversation APIs (CCAPIs) — announced for removal 2025-04-25, removal started 2025-04-30. Classic's chat channel is directly affected — https://support.zendesk.com/hc/en-us/articles/4408843026714-What-is-being-removed-updated-February-2026
• Migration path: Zendesk recommends converting Web Widget (Classic) to the messaging Web Widget (same ze-snippet URL, server-side conversion). Recommend that ahize/zendesk-classic emit a console.warn on load() pointing users to ahize/zendesk — https://support.zendesk.com/hc/en-us/articles/4408832031898-Setting-up-Web-Widget-for-messaging-when-using-live-chat-and-Web-Widget-Classic
• Consider marking the package deprecated in npm metadata once a concrete Zendesk-announced Classic EOL date is published.

Intentionally out of scope

• Full modelling of every updateSettings sub-object (color, position, contactOptions, etc.) — offer an escape hatch instead.
• Talk (voice) and Answer Bot channel APIs — niche, and tied to removed Chat SDK.
• Mobile Classic SDKs (iOS/Android/Unity).
• Building a compatibility shim that auto-detects and forwards to ahize/zendesk — too much surface drift between the two.

Sources

• https://developer.zendesk.com/api-reference/widget/core/
• https://developer.zendesk.com/api-reference/widget/introduction/
• https://developer.zendesk.com/documentation/classic-web-widget-sdks/web-widget/
• https://support.zendesk.com/hc/en-us/articles/4429429087002-Comparing-the-Zendesk-Web-Widgets
• https://support.zendesk.com/hc/en-us/articles/4408843026714-What-is-being-removed-updated-February-2026
• https://support.zendesk.com/hc/en-us/articles/4408832031898-Setting-up-Web-Widget-for-messaging-when-using-live-chat-and-Web-Widget-Classic
• https://developer.zendesk.com/documentation/classic-web-widget-sdks/web-widget/getting-started/chat_api_migration/

[productdevbook]

Shipped a @deprecated JSDoc header + one-shot console.warn on load() in 837ec44 — points users at ahize/zendesk (Messenger) for new integrations. Remaining API gaps (logout/setLocale/toggle/events/JWT) stay open.