Web SDK configuration
Configure launchers, guest contact fields and screenshot capture with documented defaults.
Configuration
Pass configuration once after the hosted script loads and the browser body exists. Await it before identity or module calls. Options are independent unless noted below; omitted values use the defaults shown.
await BTX.configure({
publishableClientKey: 'cfk_your_web_client_key',
messenger: {
teamName: 'Acme support',
greeting: 'How can we help?',
launcherLabel: 'Support',
launcherStyle: 'pill',
requireName: false,
requireEmail: false
}
})| Option | Type | Default | Behavior |
|---|---|---|---|
publishableClientKey | string | Required | Publishable key from your BTX Web client. An empty key is rejected. |
apiBaseUrl | string or URL | https://btx.so | BTX API endpoint. Usually omit this. |
messenger | BTXWebMessengerConfiguration | Default UI | Launcher, presentation and guest contact options below. |
feedback.capture | () => Promise<Blob> | Local page rendering | Optional host callback supplying a screenshot image. |
The publishable key may be in browser code. Identity signing keys and owner credentials must stay on your backend. Configure each allowed website origin in BTX; the key alone does not authorize an arbitrary origin.
Changing configuration replaces the active runtime and discards unsent UI state. Repeating an identical configuration, including the same capture callback reference, is a no-op. Avoid creating a new callback or reconfiguring on every render. For signed-in users, identify again after replacing configuration.
Messenger options
All options below are under messenger.
| Option | Type | Default | Behavior |
|---|---|---|---|
showLauncher | boolean | true | Shows SDK-owned Feedback and chat entry points. Set false when using your own buttons. |
launcherLabel | string | Chat | Label on the chat launcher. |
launcherStyle | 'pill' or 'notch' | 'pill' | Pill floats at bottom right; notch uses a bottom-center entry point and sheet presentation. Other values are rejected. |
launcherDelayMs | number | 0 for pill | Non-negative finite delay in milliseconds. The first notch presentation per page defaults to 3400ms; later notch mounts default to zero. Explicitly set zero for immediate display. |
launcherTooltip | string | None | Helper text on launcher hover or keyboard focus. |
brandIconUrl | string | None | Decorative brand image for the launcher and generic chat header. Relative URLs resolve against the host page. Named responders use their own avatar. |
teamName | string | our team | Team name used by messenger presentation. The generic header is “Chat with us”; named responders can replace it. |
greeting | string | How can we help? | Empty-thread text. |
requireName | boolean | false | Requires a guest name before starting a thread or sending feedback. Independent of email. |
requireEmail | boolean | false | Requires a guest email before starting a thread or sending feedback. Independent of name. |
preChatSubtitle | string | None | Optional subtitle under the contact form heading. |
Blank optional text is treated as omitted. There is no public palette, CSS override, panel-position or headless UI configuration. SDK styles are isolated in a Shadow DOM and respect reduced-motion preferences.
Calling BTX.messenger.open() reveals chat immediately even while its launcher delay is running. A hidden launcher does not disable chat, feedback, reply previews or custom unread-count events.
Guest contact settings
In BTX desktop, open Settings → Project → Client SDKs, select a Web client, and enable Ask for name or Ask for email. Both default off. The SDK resolves enabled fields when an anonymous visitor engages, and applies them to chat and feedback. Identified accounts skip contact capture.
These client-management switches require an updated BTX app. With SDK 0.1.0, you can collect either field directly through messenger.requireName and messenger.requireEmail.
Integration options can also require fields. A true requirement from either client settings or your integration applies; setting a local option to false does not override a requirement enabled for the client. Contact values are unverified and do not authenticate an account. See guest identity for storage and reset behavior.
Custom launchers
Hide the SDK launchers and wire your own controls to the public modules. The SDK continues to render chat, feedback, success toasts and reply previews.
await BTX.configure({
publishableClientKey: 'cfk_your_web_client_key',
messenger: { showLauncher: false }
})
supportButton.addEventListener('click', () => {
BTX.messenger.open().catch(showSupportError)
})
feedbackButton.addEventListener('click', () => {
BTX.feedback.open().catch(showSupportError)
})The host supplies supportButton, feedbackButton, and its error presentation, represented by showSupportError above. Listen for btx:unread to add a badge to your Support button. Your click handlers should catch failures, including connection and expired-identity errors.
Screenshot capture
The default capture renders the visible page locally using JavaScript, without a screen-sharing prompt. If your host can supply a better image, provide an async callback returning an image Blob:
await BTX.configure({
publishableClientKey: 'cfk_your_web_client_key',
feedback: {
capture: async () => {
// Your host returns an image Blob for the current screen.
return await captureAppScreen()
}
}
})captureAppScreen is your host implementation, not a BTX method. If capture fails, customers can still attach supported media or send a note. Cross-origin frames and assets without CORS access may be absent from the default image. See feedback for media limits and editing.