Skip to content
Troubleshooting

Web SDK troubleshooting

Resolve startup, origin, identity, capture, attachment and reply-delivery problems.

Script or launcher does not appear

Confirm that the hosted script loaded successfully before calling BTX. Initialize in the browser after the page body exists, not during server rendering. Use your Web client's publishable key, await configuration, and inspect the browser console and failed network request.

Check showLauncher, launcherDelayMs and launcherStyle. The notch can wait 3400ms on its first appearance; use BTX.messenger.open() to open it immediately. If your app supplies custom buttons, hiding the launcher is expected.

Catch initialization and connection failures
async function startSupport() {
  try {
    await BTX.configure({ publishableClientKey: 'cfk_your_web_client_key' })
    // If signed in, await BTX.identify(...) here first.
    await BTX.messenger.open()
  } catch (error) {
    // Show an actionable error in your app; keep secrets out of logs.
    console.error('Support unavailable', error)
  }
}
startSupport()

If you see “BTX Web is not configured,” await configure before opening a module. An empty key, unknown launcher style or negative/non-finite delay is invalid. Anonymous identity requires a browser context that supports crypto.randomUUID(); use HTTPS or a browser-supported local development origin.

Origin rejected or API connection blocked

Open Settings → Project → Client SDKs in BTX desktop and select the Web client whose key you use. Add the exact origin shown in the browser address bar: scheme, hostname and port, without a path. Production and development origins are separate. localhost and 127.0.0.1 are separate hosts. Wildcards do not grant access.

Check the failed request's response, not just a successful script download. A Content Security Policy may allow the script while blocking the API, realtime stream or media. Permit the BTX script/API and the attachment origins actually returned for your project; keep your site's policy otherwise scoped. Check extensions or network filters when a request is blocked before it reaches BTX.

Identity rejected or the wrong history appears

A signed-in account requires a fresh token from an endpoint that authenticates your app user. Check the client audience, external ID, expiry and server clock against the identity contract. An identity_invalid response requires fresh authenticated proof and a new identify call. Do not retry the same account as an unsigned identity.

Changing a client's credentials invalidates its signing key and existing proofs. Install the replacement signing key on your backend and issue fresh tokens. Never put a signing key or owner token in browser code or screenshots.

Call identify after configuration and await it before opening chat. Use identify(null) on sign-out. identifyAnonymous() deliberately starts a new guest on every call; do not call it on each render if you intend to retain history. Guest email cannot retrieve account history, and anonymous history does not merge automatically into an account. Browser-origin, API endpoint and Web-client boundaries also separate anonymous histories.

Screenshot capture is missing content or fails

The SDK captures the page DOM, not the operating system's screen. It does not request screen-sharing permission. Cross-origin iframes, protected assets, canvas/video content or unsupported browser rendering can be missing or differ from what you see. Configure CORS for assets you control, use a host capture callback, or let the customer attach an image.

Capture failure leaves the feedback composer available for attachments or a note. The screenshot remains local until Send. If a capture callback fails, return a supported non-empty image Blob or reject clearly; do not return HTML or a remote URL string.

An attachment is rejected or sending fails

The session supplies supported types, sizes and counts. Current feedback limits allow four attachments with at most one video; documents such as PDFs are not supported. Remove an attachment, choose a supported image/video format, or reduce its size based on the visible error. Images can be edited separately; videos are previewed, not drawn on or cropped.

A failed feedback send preserves the report. Retry from the same composer after connection or identity recovery; unchanged retries reuse the report ID to avoid duplicate threads. Closing the report, resetting or switching accounts discards the draft. Chat failures have their own Retry action on the failed message.

An accepted report shows the SDK thank-you toast and emits btx:feedback-sent. That acceptance does not mean the team has read it. If delivery remains uncertain, give your support contact the approximate time, browser/version, affected origin and any request ID returned by the failed request, without tokens or private report contents.

No unread badge or reply preview

Confirm you are using the same customer, Web client and browser origin as the original thread. A first-time guest starts messaging only after engagement. Returning engaged guests and identified accounts can receive replies with chat closed while the page is visible; hidden tabs pause and catch up when visible again. A shutdown runtime does not receive replies.

Inspect realtime/API failures if the page is visible and connected. For custom buttons, register a btx:unread listener before configuration and use its thread count, including zero. showLauncher: false hides the SDK badge's launcher, so the host must render its own badge. Open the reply preview or Your threads to find feedback replies; feedback creates a separate thread from an existing support chat.

npm install or a documented option is unavailable

The public package is @btx-hq/web; install it from the npm registry. It is ESM with TypeScript declarations, and its browser import is import { BTX } from '@btx-hq/web'. Keep @btx-hq/web/server out of browser bundles. If you do not use a bundler, use the hosted browser script instead. Check the changelog and your installed version when an option is unavailable.