The BlueBubblesClient: SDK entry point

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).

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<string>`	`undefined`	Server password used for authentication.
`TOKEN`	`string \| Resolver<string>`	`undefined`	Bearer token, if your server is configured to use token auth.
`USERNAME`	`string \| Resolver<string>`	`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<string, string> \| 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<T> — so you can fetch credentials dynamically at request time.

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.

client.chats

Create, query, update, and delete chats. Manage participants, read status, typing indicators, and group icons.

client.messages

Send text messages and attachments, react to messages, query message history, and schedule future messages.

client.attachments

Fetch attachment metadata and download attachment files by GUID.

client.handles

Query and retrieve handle records — the contact addresses associated with iMessage conversations.

client.contacts

Access and search contacts stored on the macOS server.

client.server

Retrieve server metadata, check server health, and read diagnostic information.

client.backups

Manage server-side backups of your iMessage database and settings.

client.fcm

Configure Firebase Cloud Messaging for push notification delivery.

client.icloud

Access iCloud-related operations, including contact card sharing.

client.macos

Execute macOS-level operations on the host machine running BlueBubbles Server.

client.web

Manage web-facing features and webhook configurations.

Usage example

// 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.

import {
  BlueBubblesClient,
  BaseHttpRequest,
  CancelablePromise,
} from "bluebubbles-sdk";
import type { OpenAPIConfig } from "bluebubbles-sdk";

class LoggingHttpRequest extends BaseHttpRequest {
  constructor(config: OpenAPIConfig) {
    super(config);
  }

  public request<T>(options: any): CancelablePromise<T> {
    console.log(`[BlueBubbles] ${options.method} ${options.url}`);
    // Delegate to your own fetch implementation or super if available
    return new CancelablePromise<T>((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.

// 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.

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.

Get Started

Core Concepts

Guides

Resources

The BlueBubblesClient: SDK entry point

Constructing the client

Full configuration reference

Available services

client.chats

client.messages

client.attachments

client.handles

client.contacts

client.server

client.backups

client.fcm

client.icloud

client.macos

client.web

Usage example

Custom HTTP request backend

The `request` property

Error handling

​Constructing the client

​Full configuration reference

​Available services

client.chats

client.messages

client.attachments

client.handles

client.contacts

client.server

client.backups

client.fcm

client.icloud

client.macos

client.web

​Usage example

​Custom HTTP request backend

​The request property

​Error handling

Constructing the client

Full configuration reference

Available services

Usage example

Custom HTTP request backend

The `request` property

Error handling