Skip to content
API reference

Web SDK API reference

Browser runtime, identity, messenger, feedback and integration event contracts.

Runtime and lifecycle

Import BTX from @btx-hq/web, or use the hosted script's global BTX object. Call it in the browser after the page body exists. See installation for setup and the publishable key, and configuration for every option. Server identity helpers are exported separately from @btx-hq/web/server and must stay on your backend.

BTX facade
interface BTXWebSDK {
  configure(configuration: BTXWebConfiguration): Promise<void>
  identify(customer: BTXWebCustomer | null): Promise<void>
  identifyAnonymous(contact?: { name?: string; email?: string }): Promise<void>
  reset(): Promise<void>
  shutdown(): Promise<void>
  readonly messenger: BTXWebMessenger
  readonly feedback: BTXWebFeedback
}
MethodBehavior
BTX.configure(configuration)Creates the runtime and SDK UI. Identical configuration with the same capture callback is a no-op. Changed configuration replaces the runtime and disposes unsent UI state; identify the signed-in customer again afterward.
BTX.identify(customer)Switches to a backend-verified account. Renewing the token for the same external ID preserves open chat and feedback drafts. Switching accounts clears drafts and the previous transport.
BTX.identify(null)Signs out into a fresh anonymous identity, equivalent to reset.
BTX.identifyAnonymous(contact?)Creates a fresh anonymous identity on every call, optionally with unverified name/email metadata. It does not restore history by email.
BTX.reset()Rotates to a fresh guest and clears the contact-completion marker, drafts and prior UI. It keeps the SDK configuration and does not delete server history.
BTX.shutdown()Removes SDK UI and stops SDK-owned networking. It does not delete server history or rotate the stored guest ID. Configure again when mounting a new host.

Await configuration and identity changes before opening a module. Wrap awaited calls in try/catch: invalid input can throw immediately, and connection or identity failures can reject the returned promise. See troubleshooting for recovery.

Customer identity

Signed customer
interface BTXWebCustomer {
  externalId: string
  identityToken: string
  name?: string
  email?: string
}

externalId is the stable account ID trusted by your backend. identityToken is required and must be signed by your authenticated backend for this Web client. Name and email are optional; signed token values own the account profile. Do not use email alone as identity proof or an ID beginning with btx-anonymous- for an identified account.

Tokens live for at most one hour. The host obtains fresh proof on sign-in/page load and before expiry; BTX does not silently renew it. Guest contact information stays in memory, while a browser-local guest ID and completion marker can persist. Guest and account histories do not automatically merge. See identity setup for the owner-only key setup and server signing example.

Messenger

Messenger module
interface BTXWebMessenger {
  open(): Promise<void>
  close(): void
}

open() shows chat and restores the latest thread. Anonymous visitors complete any required contact form first. close() hides the chat surface; it does not sign out or stop reply delivery for an engaged, visible page. The SDK's Your threads control opens earlier threads, and a reply preview opens the specific thread that received the reply.

The public module does not expose programmatic thread selection, message sending, transcript reads or read-state mutation. Those actions belong to the SDK UI. Use custom launchers to connect your own Support button.

Feedback

Feedback module
interface BTXWebFeedbackInput {
  attachments?: readonly Blob[]
}

interface BTXWebFeedback {
  open(input?: BTXWebFeedbackInput): Promise<void>
  close(): void
}

// Capture the visible page and open the report.
await BTX.feedback.open()
// Open without an initial screenshot.
await BTX.feedback.open({ attachments: [] })
// Start with existing images or videos. File extends Blob.
await BTX.feedback.open({ attachments: [imageBlob, videoFile] })

open() opens the report UI; its promise is not a report-delivery receipt. Omitting attachments captures the current viewport locally. Supplying an array uses those images/videos instead, including an empty array for note-only reporting. Call from a deliberate user action. The customer reviews, edits and sends through SDK UI.

close() dismisses and discards the unsent report. Account switches and reset also discard it. A failed send keeps the draft for retry. Screenshot capture failure leaves Attach and note-only reporting available. See feedback for drawing, mosaic, crop, upload limits and delivery behavior.

There is no public programmatic submit, editor-state or upload API.

Browser events

Events are dispatched on document. Register listeners before configuring if you need the first unread-count update, and remove host listeners during teardown.

EventDetailMeaning
btx:unread{ count: number }Current unread thread count, emitted when it changes. Use this for a custom badge.
btx:feedback-sentNo payloadThe API accepted a feedback report. It does not mean an operator read it.
btx:interaction{ surface: string, control: string }Deliberate SDK control activation using stable names. It contains no note, filename, email or customer ID.
Custom unread badge lifecycle
function onUnread(event) {
  supportBadge.textContent = String(event.detail.count)
}
document.addEventListener('btx:unread', onUnread)

// When your host surface is removed:
document.removeEventListener('btx:unread', onUnread)
await BTX.shutdown()

The host owns any DOM element used for its badge, such as supportBadge above. These events are integration hooks, not a general product telemetry or message-stream API.