> ## Documentation Index > Fetch the complete documentation index at: https://bluebubbles.anmho.com/llms.txt > Use this file to discover all available pages before exploring further. # The BlueBubblesClient: SDK entry point > Learn how to instantiate BlueBubblesClient, configure authentication and HTTP options, and navigate its resource-grouped service properties. `BlueBubblesClient` is the single entry point for every operation in the BlueBubbles SDK. You construct one instance, pass your server address and credentials, and then call methods on its resource-grouped properties — `client.chats`, `client.messages`, `client.attachments`, and so on — instead of managing URLs or HTTP headers yourself. ## Constructing the client The constructor accepts a partial `OpenAPIConfig` object so you only need to supply the fields that differ from the defaults. At a minimum, provide `BASE` (your BlueBubbles Server URL) and `PASSWORD` (your server password). ```typescript theme={null} import { BlueBubblesClient } from "bluebubbles-sdk"; const client = new BlueBubblesClient({ BASE: "https://your-server-address", PASSWORD: "your-server-password", }); ``` ### Full configuration reference | Field | Type | Default | Description | | ------------------ | ----------------------------------------- | -------------------- | -------------------------------------------------------------- | | `BASE` | `string` | `"http://localhost"` | Base URL of your BlueBubbles Server instance. | | `VERSION` | `string` | `"1.0.0"` | API version string. You rarely need to change this. | | `PASSWORD` | `string \| Resolver` | `undefined` | Server password used for authentication. | | `TOKEN` | `string \| Resolver` | `undefined` | Bearer token, if your server is configured to use token auth. | | `USERNAME` | `string \| Resolver` | `undefined` | Username for HTTP Basic authentication. | | `WITH_CREDENTIALS` | `boolean` | `false` | Whether to include cookies in cross-origin requests. | | `CREDENTIALS` | `"include" \| "omit" \| "same-origin"` | `"include"` | Controls the `credentials` mode for `fetch`. | | `HEADERS` | `Record \| Resolver<...>` | `undefined` | Custom headers merged into every request. | | `ENCODE_PATH` | `(path: string) => string` | `undefined` | Override path-segment encoding for special character handling. | `PASSWORD`, `TOKEN`, `USERNAME`, and `HEADERS` each accept either a static value or an async resolver function — `(options: ApiRequestOptions) => Promise` — so you can fetch credentials dynamically at request time. ```typescript theme={null} const client = new BlueBubblesClient({ BASE: "https://your-server-address", // Resolve the password asynchronously (e.g., from a secrets manager) PASSWORD: async (_options) => { return await secretsManager.getSecret("bluebubbles-password"); }, // Attach a custom header to every request HEADERS: { "X-Client-Version": "1.0.0", }, }); ``` ## Available services The client exposes eleven service properties, each scoping methods to a particular resource domain. You access them directly on the client instance. Create, query, update, and delete chats. Manage participants, read status, typing indicators, and group icons. Send text messages and attachments, react to messages, query message history, and schedule future messages. Fetch attachment metadata and download attachment files by GUID. Query and retrieve handle records — the contact addresses associated with iMessage conversations. Access and search contacts stored on the macOS server. Retrieve server metadata, check server health, and read diagnostic information. Manage server-side backups of your iMessage database and settings. Configure Firebase Cloud Messaging for push notification delivery. Access iCloud-related operations, including contact card sharing. Execute macOS-level operations on the host machine running BlueBubbles Server. Manage web-facing features and webhook configurations. ### Usage example ```typescript theme={null} // Query the 20 most recent chats including last message and participants const chats = await client.chats.list({ requestBody: { limit: 20, offset: 0, with: ["lastMessage", "participants"], sort: "lastmessage", }, }); // Fetch messages for a specific chat const messages = await client.chats.listMessages({ chatGuid: "iMessage;+;+15550001234", }); // Send a text message await client.messages.sendText({ requestBody: { chatGuid: "iMessage;+;+15550001234", message: "Hello from the SDK!", tempGuid: crypto.randomUUID(), }, }); // Get server info const info = await client.server.getServerMetadata(); ``` ## Custom HTTP request backend The second argument to the constructor is an optional `HttpRequest` class — any class that extends `BaseHttpRequest`. By default the SDK uses an internal `FetchHttpRequest` implementation that calls the native `fetch` API. You can substitute your own implementation to add logging, retry logic, or use a different transport layer. ```typescript theme={null} import { BlueBubblesClient, BaseHttpRequest, CancelablePromise, } from "bluebubbles-sdk"; import type { OpenAPIConfig } from "bluebubbles-sdk"; class LoggingHttpRequest extends BaseHttpRequest { constructor(config: OpenAPIConfig) { super(config); } public request(options: any): CancelablePromise { console.log(`[BlueBubbles] ${options.method} ${options.url}`); // Delegate to your own fetch implementation or super if available return new CancelablePromise((resolve, reject) => { fetch(`${this.config.BASE}${options.url}`, { method: options.method, headers: options.headers as HeadersInit, body: options.body ? JSON.stringify(options.body) : undefined, }) .then((res) => res.json() as T) .then(resolve) .catch(reject); }); } } const client = new BlueBubblesClient( { BASE: "https://your-server-address", PASSWORD: "secret" }, LoggingHttpRequest, ); ``` ## The `request` property Every `BlueBubblesClient` instance exposes a `request` property of type `BaseHttpRequest`. This gives you direct access to the configured HTTP layer so you can issue raw API calls to endpoints not yet covered by named service methods. ```typescript theme={null} // Call a hypothetical endpoint not wrapped by a service method const result = await client.request.request({ method: "GET", url: "/api/v1/some/custom/endpoint", query: { password: "secret" }, }); ``` The `request` property uses the same configuration (BASE URL, credentials, custom headers) you passed to the constructor, so you don't need to repeat them for raw calls. ## Error handling All service methods return a `CancelablePromise` and throw an `ApiError` on non-2xx responses. The `ApiError` class extends `Error` and carries structured context about the failure. ```typescript theme={null} import { ApiError } from "bluebubbles-sdk"; try { const chat = await client.chats.get({ chatGuid: "iMessage;+;+15550001234" }); } catch (err) { if (err instanceof ApiError) { console.error(`HTTP ${err.status} — ${err.statusText}`); console.error("Response body:", err.body); console.error("Request URL:", err.url); } } ``` | Property | Type | Description | | ------------ | ------------------- | ----------------------------------------------------- | | `status` | `number` | HTTP status code returned by the server. | | `statusText` | `string` | HTTP status text (e.g., `"Not Found"`). | | `url` | `string` | The full URL of the failed request. | | `body` | `any` | Parsed response body from the server. | | `request` | `ApiRequestOptions` | The original request options that caused the failure. |