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

[productdevbook]

Summary

Crisp's $crisp JS SDK exposes a substantially larger surface than our wrapper covers — we are missing all $crisp.is/$crisp.get getters, several do:*/set:*/config:* commands, ~half the lifecycle events, and all of safeMode / cookieDomain / cookieExpire / sessionMerge runtime config.

Gaps found

Missing API surface

• do:chat:open / do:chat:close / do:chat:toggle exposed as discrete methods (we only ship show/hide, which conflate chat:show+chat:open) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• do:message:send (programmatic visitor message) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• do:message:show (local operator message) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• do:message:read (mark all read) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• do:message:thread:start / do:message:thread:end — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• do:helpdesk:search / do:helpdesk:article:open / do:helpdesk:query — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• do:trigger:run — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• do:bot:scenario:run — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• do:overlay:open / do:overlay:close — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• set:user:avatar (we set email/nickname/phone but not avatar) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• set:session:segments — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• set:message:text (prefill input) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• is:chat:opened / is:chat:closed / is:chat:visible / is:chat:hidden / is:chat:small / is:chat:large getters — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• is:session:ongoing — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• is:website:available — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• is:overlay:opened / is:overlay:closed — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• get:session:identifier (needed for backend correlation; today our wrapper has no way to expose Crisp's session id) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/session-continuity/
• get:session:data (read-back of attributes) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• get:chat:unread:count (synchronous unread; would let us replace the "approximation" comment in load()) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• get:message:text, get:user:email, get:user:phone, get:user:nickname, get:user:avatar, get:user:company — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/

Events not bridged

• chat:opened (only chat:closed is hooked; needed for proper unread reset) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• chat:initiated (first interaction) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• message:sent (visitor outbound) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• message:compose:sent / message:compose:received (typing indicators) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• helpdesk:queried — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• user:email:changed / user:phone:changed / user:nickname:changed / user:avatar:changed (would let onIdentityChange reflect Crisp-side edits) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• website:availability:changed — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/

Config options not exposed

• safeMode (suppresses SDK errors; documented Crisp.setSafeMode(true) / configure({ safeMode })) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/npm/
• CRISP_COOKIE_DOMAIN (cookie domain restriction) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/cookie-policies/
• CRISP_COOKIE_EXPIRE (custom session lifetime, default 6 months) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/cookie-policies/
• sessionMerge runtime option — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/npm/
• lockMaximized / lockFullview runtime options — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/npm/
• config:position:reverse, config:color:theme, config:color:mode (light/dark/auto), config:layout:theme, config:tile, config:container:index, config:sound:mute, config:availability:tooltip, config:hide:vacation, config:hide:on:away, config:hide:on:mobile, config:show:operator:count — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• Dynamic locale switching after load (today locale is only honored at load() time via CRISP_RUNTIME_CONFIG; no reconfigure-less path) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/language-customization/

Deprecations in our current code

• load() registers a message:received listener with an empty body and the comment "unread counter triggers via message:received/chat:opened — approximation" — replace with the documented get:chat:unread:count getter plus the chat:opened event so onUnreadCountChange is exact instead of approximate (src/providers/crisp.ts:96–101) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• load() registers a chat:closed listener with body "leave hooks for facade wrappers" — either wire it through or drop the dead push (src/providers/crisp.ts:102–108) — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• show() pushes both chat:show and chat:open unconditionally — split into show/open so callers that only want to restore visibility don't force-open the panel — https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/

Intentionally out of scope

• do:helpdesk:* admin/operator-only operations (per task instructions; visitor-facing do:helpdesk:search/article:open/query are still flagged above).
• Multi-region (Crisp.eu vs default) — Crisp's documented loader endpoint is the single global https://client.crisp.chat/l.js; no separate EU host is documented in the public SDK reference.
• Private mode beyond safeMode — not surfaced in the public docs reviewed.

Sources

• https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/
• https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/
• https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/npm/
• https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/identity-verification/
• https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/language-customization/
• https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/cookie-policies/
• https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/session-continuity/

[productdevbook]

Most audit findings shipped in d1ae76c:

Methods (12 new): open, close, toggle (split from show()), sendMessage, showLocalMessage, markRead, setMessageText, setUserAvatar, setSessionSegments, helpdeskSearch, helpdeskArticleOpen, runTrigger. show() no longer also fires chat:open — visibility and panel state are now independent.

Event bridge: new public on(event, handler) wraps 13 documented events (chatOpened, chatClosed, chatInitiated, messageSent, messageReceived, messageComposeSent/Received, helpdeskQueried, user:email/phone/nickname/avatar:changed, websiteAvailabilityChanged). Replaces the two dead-stub listeners (message:received + chat:closed empty bodies).

Runtime config (CrispLoadOptions): safeMode, cookieDomain, cookieExpire, sessionMerge, lockMaximized, lockFullview.

Test coverage: test/crisp.browser.test.ts (5 cases). Bundle budget bumped 6KB → 10KB.

Deferred:

• $crisp.is:* / $crisp.get:* synchronous getters (get:session:identifier, get:chat:unread:count, etc.) — the queue-array $crisp.push(...) bus doesn't support a sync return value; surfacing these requires either polling for $crisp.get(...) to become a function, or building a request/response correlation. Best handled in a separate issue once we agree on the pattern.
• do:bot:scenario:run and do:overlay:open|close — niche, will add on demand.
• config:* runtime mutations (theme/color/position-flip) — overlap with the existing locale path; defer until a consumer asks.

Closing the main audit issue; the deferred items above can be tracked as follow-ups when needed.