KI-Support in Desktop-Apps

Show Busymate AI chat inside your desktop app using an official, versioned desktop SDK. There is one public repository per platform, each with installation instructions, a configuration reference and a buildable example-app/. Your authenticated backend supplies identity. The microphone adapter asks the operating system only when the customer taps dictation or voice.

1. Choose your platform

1. macOS SDK: a Swift package for AppKit and SwiftUI on WKWebView.
2. Windows SDK: a .NET 8 library for WPF and WinForms on Microsoft Edge WebView2.
3. Electron SDK: an npm package that creates a secure BrowserWindow or WebContentsView.
4. Linux SDK: a C library on GTK4 and WebKitGTK 6.0, with GObject Introspection bindings.
5. Tauri SDK: a Tauri v2 plugin with optional JavaScript bindings.

Pin distribution 1.0.1 on every platform. Each SDK uses identity protocol v2 (frozen bridge build 2.0.0) and microphone protocol v1 (adapter 1.0.0). These version numbers describe different components.

2. Load the chat as the window's page

Load the chat URL supplied for your assistant as the top-level page of the SDK's window, with channel=desktop_sdk. For example, https://YOUR_ASSISTANT.busymate.ai/?channel=desktop_sdk&locale=de. Keep the other supported query parameters, such as locale and theme. The chat then:

• uses the normal full-window chat layout, which your app frames;
• shows your locale from the first frame;
• labels its conversations "Desktop app (SDK)" in your Inbox and Customers.

Use channel=desktop_sdk only. channel=embed is for a chat iframed inside a web page: the chat refuses to start without an allowed parent page. channel=desktop is reserved for the Busymate AI desktop app. A channel parameter alone never identifies a customer.

3. Connect your account

Every SDK installs the identity bridge before the first load. Configure the assistant slug, any extra exact HTTPS origins, a callback returning the current account ID, and a mint callback. Your backend signs a fresh ES256 launch token for the request's nonce, with a unique jti and an expiry within 120 seconds. Keep signing keys on the server. Return no identity when signed out, and never cache a token. Tell the SDK after login, logout and account switches. Configure onClose (or your platform's close callback) to dismiss the chat window. See backend signing.

4. Enable microphone access

Declare the operating system's microphone permission where your platform needs one. Leave the adapter enabled. The first mic or voice tap sends busymate.microphone.v1.request with a correlated id and a source of dictation or voice. The adapter asks the OS and replies with the same id and a granted boolean. Chat waits for that reply before capturing audio or minting a voice token. Opening the chat never asks for permission. Denial, cancellation and timeout stop activation. The adapter grants audio only, and only to an allowed origin.

5. Artifacts and versions

The identity contract is the frozen bridge contract v2. Its CONTRACT-v2.md hashes to c891b8bae48c87d5ae901de16df0594ba3879dd84ecd535e79120761d4220c1d, the entry in https://busymate.ai/sdk/v2/2.0.0/SHA256SUMS. Electron ships the frozen kit files byte-identical to https://busymate.ai/sdk/v2/2.0.0/electron/. Each repository's release-manifest.json pins its source hashes, and a change to those bytes is always a new SDK version.

Verify

1. Build the example app for your platform, open chat signed out and send a guest message.
2. Load ?channel=desktop_sdk&locale=de: the first frame is in German, with no extra title-bar inset.
3. Connect your backend, sign in and switch accounts; verify customer history does not cross accounts.
4. Tap dictation and voice separately. Test first grant, denial, retry after changing the OS setting, and cancellation while permission is pending, on a real machine.
5. Test external links, close, window re-activation and renderer recovery.
6. Enable handoff in your workspace, request a human and check the Inbox.