macOS API reference

Find configuration, window registration, messaging, feedback, telemetry, and notification APIs.

Configuration and identity

Call configuration, identity, and messenger presentation APIs on the main actor. These methods describe the macOS API; see package availability before integrating.

API	Purpose
`BTX.configure(_:)`	Configures BTX using `BTXConfiguration`.
`BTXConfiguration(publishableClientKey:features:messengerOptions:)`	Supplies the macOS client key and enabled features. The default feature set is `.messenger`; `.logs` opts into telemetry.
`BTX.identify(_:)`	Sets the active `BTXCustomer`, or clears identity with `nil`.
`BTXCustomer(externalID:name:email:phone:)`	Supplies a stable customer ID and optional profile fields.
`BTXAppContext`	Supplies app version, build number, and app attributes.

Window registration

API	Purpose
`View.btxMessenger()`	Registers a SwiftUI window for native support and feedback. Apply once at each window root.
`BTX.messenger.attach(to:)`	Registers an AppKit `NSWindow` after its content view is set.

Messages and feedback

API	Purpose
`BTX.messenger.present()`	Opens conversation history.
`BTX.messenger.presentSupport()`	Opens the support surface in a registered window.
`BTX.messenger.presentThread(id:)`	Opens an existing conversation for the active customer.
`BTX.messenger.presentFeedbackReport(includeScreenshot:)`	Opens feedback with an optional window screenshot. The default is `true`.
`BTX.messenger.dismiss()`	Dismisses the presented SDK surface.
`BTX.messenger.unreadCount`	Returns the current unread count.
`BTX.messenger.onUnreadCountChange(_:)`	Observes unread changes and returns an `AnyCancellable`; retain it while observing.
`BTXMessengerOptions.theme`	Applies a shared `BTXTheme` to support and feedback.

Presentation methods return BTXMessengerPresentationResult: .presented or .failed(BTXMessengerPresentationFailure). Failures include .notConfigured, .featureDisabled, .notIdentified, and .unavailable.

Reply notifications

API	Purpose
`BTXPushConfiguration(automaticallyRequestsAuthorization:)`	Controls automatic permission and APNs registration. The default is `true`.
`BTX.messenger.setDeviceToken(_:)`	Accepts the APNs token as `Data` from the host's AppKit delegate.
`BTX.isMessengerNotification(_:)`	Recognizes a potential messenger notification payload.
`BTX.handleNotificationResponse(_:)`	Accepts a recognized notification response for handling and returns `Bool`.
`BTX.messenger.unregisterPushDevice()`	Asynchronously unlinks the active registration; can throw. Await before clearing or switching identity.

Recognition does not confirm that a window or identity is ready, or that a conversation has opened. See the full APNs setup and testing sequence.

Telemetry

BTX.log(_:level:message:properties:occurredAt:) enqueues a structured event from any thread and returns BTXLogDisposition. Enqueue acceptance does not establish network delivery. Enable .logs and identify the customer to deliver telemetry.