Skip to main content
The server service exposes administrative operations for the BlueBubbles Server running on your macOS machine. You can read server metadata and logs, acknowledge alerts, trigger restarts at varying levels of severity, pull media and entity statistics, and manage server updates — all through the SDK. Access the service through client.server.

​
Metadata and logs

​
getServerMetadata()

Returns metadata about the BlueBubbles Server and the underlying operating system — including the server version, macOS version, and other environment details. Signature 
client.server.getServerMetadata(): CancelablePromise<any>
Example 
const info = await client.server.getServerMetadata();
console.log(info.data.server_version);
console.log(info.data.os_version);

​
getServerLogs()

Fetches recent log output from the BlueBubbles Server. Signature 
client.server.getServerLogs(): CancelablePromise<any>
Example 
const logs = await client.server.getServerLogs();
console.log(logs.data);

​
Alerts

​
getServerAlerts()

Returns all alerts generated by the BlueBubbles Server. Alerts include connectivity warnings, configuration issues, and other notable server events. Signature 
client.server.getServerAlerts(): CancelablePromise<any>
Example 
const alerts = await client.server.getServerAlerts();

for (const alert of alerts.data) {
  console.log(`[${alert.type}] ${alert.message}`);
}

​
markAlertsAsRead()

Marks one or more alerts as read on the server. You must pass the IDs of the alerts you want to mark — a catch-all endpoint is intentionally not provided to avoid race conditions. Signature 
client.server.markAlertsAsRead({
  requestBody,
}: {
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
Request body parameters
​
ids
number[]
required
An array of alert IDs to mark as read. Retrieve alert IDs using getServerAlerts() first.
Example 
// Fetch unread alerts and mark them all as read
const alerts = await client.server.getServerAlerts();
const ids = alerts.data.map((a: any) => a.id);

await client.server.markAlertsAsRead({
  requestBody: { ids },
});

​
Restart

​
restartServer()

Performs a full restart of the BlueBubbles Server application. The server closes itself completely and reopens. Signature 
client.server.restartServer(): CancelablePromise<any>
Example 
await client.server.restartServer();
restartServer() closes and reopens the BlueBubbles Server app entirely. Your SDK connection will drop during the restart. The Mac itself is not restarted. Build in reconnection logic if you call this programmatically.

​
restartServices()

Performs a soft restart of the individual services running inside BlueBubbles Server — including the HTTP service, the FCM service, and the Private API service. The server application itself stays running. Signature 
client.server.restartServices(): CancelablePromise<any>
Example 
// Restart services without a full app restart
await client.server.restartServices();
Prefer restartServices() over restartServer() when you only need to re-initialize a specific service (e.g., after rotating FCM credentials).

​
Statistics

​
getMediaTotals()

Returns aggregate totals for different media types (images, videos, etc.) across all chats. Signature 
client.server.getMediaTotals(): CancelablePromise<any>
Example 
const totals = await client.server.getMediaTotals();
console.log(totals.data);
// { images: 1402, videos: 87, ... }

​
getMediaTotalsPerChat()

Returns media totals broken down by individual chat. Useful for identifying which conversations contain the most media. Signature 
client.server.getMediaTotalsPerChat(): CancelablePromise<any>
Example 
const perChat = await client.server.getMediaTotalsPerChat();

for (const entry of perChat.data) {
  console.log(entry.chatGuid, entry.images, entry.videos);
}

​
getImessageEntityTotals()

Returns row counts for the core iMessage database entities: handles, messages, and chats. Signature 
client.server.getImessageEntityTotals(): CancelablePromise<any>
Example 
const totals = await client.server.getImessageEntityTotals();
console.log(totals.data);
// { handles: 412, messages: 98301, chats: 57 }

​
Updates

​
checkForServerUpdate()

Checks whether a new version of the BlueBubbles Server app is available. Returns update metadata if an update exists. Signature 
client.server.checkForServerUpdate(): CancelablePromise<any>
Example 
const update = await client.server.checkForServerUpdate();

if (update.data?.available) {
  console.log(`Update available: ${update.data.version}`);
}

​
installServerUpdate()

Installs an available update. By default the call returns immediately without waiting for the installation to complete. Pass wait=true as a URL parameter (via requestBody) to block until the update finishes. Signature 
client.server.installServerUpdate({
  requestBody,
}: {
  requestBody?: any;
}): CancelablePromise<any>
Example 
// Start install and return immediately
await client.server.installServerUpdate({ requestBody: null });

// Wait for the update to complete before resolving
await client.server.installServerUpdate({ requestBody: { wait: true } });
Always call checkForServerUpdate() before installServerUpdate() to confirm an update is actually available. Installing when no update exists will return an error.