Skip to content
Install and chat

BTX for Web

Add customer chat and screenshot feedback with one browser SDK.

Install

Create a Web client in BTX under Project settings → Client SDKs. Add each website origin to Allowed origins, then copy the publishable key. An origin includes the scheme, hostname and port. Add your production site and development site separately; paths and wildcard domains are not supported.

npm installation
npm install @btx-hq/web
Browser entry point
import { BTX } from '@btx-hq/web'

await BTX.configure({
  publishableClientKey: 'cfk_your_web_client_key',
  messenger: { teamName: 'Your team', launcherLabel: 'Support' }
})

The package is ESM and includes TypeScript declarations. Configure it after the page body exists. In a server-rendered app, initialize it from a client component or browser lifecycle hook.

For a website without a package bundler, load the hosted script instead. It exposes the same BTX API as a browser global:

Browser script alternative
<script src="https://btx.so/sdk/web/v1.js"></script>
<script>
  BTX.configure({
    publishableClientKey: 'cfk_your_web_client_key',
    messenger: { teamName: 'Your team', launcherLabel: 'Support' }
  }).catch(console.error)
</script>

Chat

The SDK adds a launcher and owns chat UI. It supports text, server-enabled image/video attachments, clipboard images, unread reply previews, realtime updates and retryable sends. Opening chat restores the latest thread. The chat menu can start a new thread or open feedback.

Anonymous visitors make no messaging requests until engagement. Previously engaged visitors and identified customers resume history and reply delivery on load. Realtime continues while the engaged page is visible, even with chat closed, so team replies show an unread badge and preview. Hidden tabs pause immediately and catch up when visible.

Configuration

Set messenger.teamName, launcherLabel, greeting, brandIconUrl, launcherTooltip, or launcherDelayMs to customize the entry point. launcherStyle is pill by default; notch places it at the bottom center. Set requireName and requireEmail independently to collect guest contact details. There is no general theme or headless UI API in this release. See the configuration reference for all options and defaults.

Use signed identity for a signed-in customer. Use feedback for screenshot reports.

Lifecycle and modules
await BTX.messenger.open()
BTX.messenger.close()
await BTX.feedback.open()
BTX.feedback.close()
await BTX.identify(null) // Sign out and rotate the guest identity.
await BTX.reset()        // Clear drafts and start a fresh guest identity.
await BTX.shutdown()     // Remove SDK UI and stop SDK network activity.

Await configuration and identity changes before calling another module. Configure once per page; call shutdown when the host is removed. Identity changes close SDK UI, discard unsent drafts and dispose the previous user's transport. They do not delete server-side history.

Storage and security

Only the anonymous ID and contact-completion marker are stored in browser storage, scoped to this origin, API environment and Web client. Identified customer data and identity tokens stay in memory. Message bodies, attachments and drafts are not persisted in browser storage. Guest email is unverified contact metadata and cannot authenticate or retrieve an account's history.

Keep your Content Security Policy compatible with the hosted script, BTX API connections, and image/media attachment origins used by your project. Screenshot capture needs HTTPS or a browser-supported local development context. Style isolation uses a Shadow DOM.

References