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

[productdevbook]

Summary

Wrapper is missing several documented Beacon commands (search, article, session-data, config, reset, toggle, ask-question, show-message, info, once), is missing five Beacon events, exposes none of the runtime/init config object (display.style/color/position/mode/labels/etc.), only forwards a flat string to init instead of the documented config object, and the prefill typings cap attachments at zero (docs allow up to 3).

Gaps found

Missing API surface

• Beacon("search", query) — open Docs and run a search — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Beacon("article", articleId, { type: "sidebar" | "modal" }) — open a specific Docs article — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Beacon("session-data", obj) — attach up to 20 conversation attributes (100-char keys, 10k-char values) — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Beacon("config", obj) — runtime reconfiguration of color/labels/mode/etc. (we only call init once with the bare beaconId) — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Beacon("reset") — clear contact-form fields without logging out the identified user — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Beacon("toggle") — toggle visibility (we only expose open/close) — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Beacon("ask-question", question) — open Beacon with a pre-loaded AI Answers query — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Beacon("show-message", id, { delay?, force? }) — programmatically trigger a Message — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Beacon("info") — return current Beacon state — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Beacon("once", event, cb) — one-shot event subscription (we only proxy on/off) — https://developer.helpscout.com/beacon-2/web/javascript-api/
• prefill should support up to 3 file attachments — current type omits the attachments field — https://developer.helpscout.com/beacon-2/web/javascript-api/
• logout accepts a clearMessages option in addition to endActiveChat; our shutdown() only forwards endActiveChat — https://developer.helpscout.com/beacon-2/web/javascript-api/
• navigate documented routes include /ask/, /ask/message/, /ask/chat/, /answers/, /ai-answers/, /previous-messages/, /docs/search?query=... — accept these as a typed union rather than free-form string — https://developer.helpscout.com/beacon-2/web/javascript-api/

Events not bridged

• search — Docs search performed ({ query }) — https://developer.helpscout.com/beacon-2/web/javascript-api/
• message-clicked — Message CTA clicked ({ id }) — https://developer.helpscout.com/beacon-2/web/javascript-api/
• message-closed — Message dismissed ({ id }) — https://developer.helpscout.com/beacon-2/web/javascript-api/
• message-triggered — Message displayed ({ id }) — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Our on() union still lists chat-ended, which is not in the documented event list — drop or document as legacy — https://developer.helpscout.com/beacon-2/web/javascript-api/

Config options not exposed

• load() only accepts beaconId; Beacon init accepts a full config object. Add an optional config field forwarded as Beacon("init", { beaconId, ...config }) — https://developer.helpscout.com/beacon-2/web/javascript-api/
• Top-level config: docsEnabled, messagingEnabled, enableFabAnimation, enablePreviousMessages, enableSounds, color, mode ("selfService" | "neutral" | "askFirst"), hideAvatars, hideFABOnMobile — https://developer.helpscout.com/beacon-2/web/javascript-api/
• display block: style ("icon" | "text" | "iconAndText"), text, position ("left" | "right"), zIndex, horizontalOffset, verticalOffset — https://developer.helpscout.com/beacon-2/web/javascript-api/
• messaging block: chatEnabled, contactForm.{customFieldsEnabled, showName, showSubject, allowAttachments} — https://developer.helpscout.com/beacon-2/web/javascript-api/
• labels block — full i18n/translation surface for Answers, Ask, Chat, Docs strings — https://developer.helpscout.com/beacon-2/web/javascript-api/

Intentionally out of scope

• Admin / Mailbox / Conversations REST API (per audit instructions).
• Mobile SDKs (iOS/Android) — wrapper targets web only.
• Beacon v3 — does not exist; v2 is the current version per the developer docs index.
• enableTranscript / attachments / instructions top-level keys — not present in current public Beacon 2 JS API docs (attachments live under messaging.contactForm.allowAttachments and prefill.attachments).
• Regional endpoints — Beacon serves from a single global CDN (https://beacon-v2.helpscout.net); no regional split documented.
• Auth: HMAC-SHA256 signature is the only documented mode (no JWT) — current wrapper already matches.

Sources

• https://developer.helpscout.com/beacon-2/
• https://developer.helpscout.com/beacon-2/web/javascript-api/
• https://developer.helpscout.com/beacon-2/web/secure-mode/
• https://docs.helpscout.com/article/1296-getting-started-beacon-2-0

[productdevbook]

All audit findings shipped in d0420d5:

Methods (10): search, article, sessionData, config, reset, toggle, askQuestion, showMessage, info, once. prefill also accepts attachments; shutdown forwards clearMessages.

Events (5 added to BeaconEvent): search, message-clicked, message-closed, message-triggered (plus chat-ended kept for backward compat).

Init config: HelpScoutLoadOptions.config now accepts a typed BeaconConfig object (docsEnabled, messagingEnabled, color, mode, display, messaging, labels, etc.) — merged into Beacon("init", { beaconId, ...config }).

Test coverage: test/helpscout.browser.test.ts (8 cases). Closing.