Chats API reference — BlueBubbles SDK

The ChatsService lets you interact with iMessage chats at every level — from creating new conversations and managing group membership to controlling read state and presence indicators. Many operations that modify chat state (such as creating a chat, updating its name, or adding participants) require the Private API to be enabled on your BlueBubbles Server. Access the service via your initialized client:

import { BlueBubblesClient } from 'bluebubbles-sdk';

const client = new BlueBubblesClient({ BASE: 'http://your-server:1234', PASSWORD: 'your-server-password' });
const chats = client.chats;

Chat metadata

`getChatCount()`

Get the total number of chats stored in your iMessage account on the server device.

getChatCount(): CancelablePromise<any>

This method takes no parameters.

const response = await client.chats.getChatCount();
console.log(response.data); // total chat count

`get()`

Fetch a chat’s database record and icon by its GUID. For group chats, this also returns the group icon if one has been set since the macOS host was first set up.

get({ chatGuid }: { chatGuid: string }): CancelablePromise<any>

string

required

The GUID of the chat to fetch, e.g. "iMessage;+;+15550001234".

const response = await client.chats.get({
  chatGuid: 'iMessage;+;chat-guid-here',
});

`list()`

Query chats from the database with optional filtering, related data, pagination, and sorting.

list({ requestBody }: { requestBody?: Record<string, any> }): CancelablePromise<any>

number

Maximum number of chats to return. Defaults to 1000.

number

Number of records to skip for pagination. Defaults to 0.

array

Related data to include in results. Accepted values: "participants", "lastMessage", "sms", "archived", "message.attributed-body", "message.message-info-summary", "message.payload-data".

string

Sort results by last message time. Must be "lastmessage". Requires "lastMessage" to also be included in with.

const response = await client.chats.list({
  requestBody: {
    limit: 25,
    offset: 0,
    with: ['lastMessage', 'participants'],
    sort: 'lastmessage',
  },
});

Creating and modifying chats

`create()`

Create a new iMessage chat. Requires the Private API and a minimum BlueBubbles Server version of 0.3.0.

create({ requestBody }: { requestBody?: Record<string, any> }): CancelablePromise<any>

array

required

A list of participant addresses (phone numbers or email addresses) to include in the new chat.

string

An optional initial message to send into the newly created chat.

create() requires the Private API to be enabled on your server (minimum server version 0.3.0).

const response = await client.chats.create({
  requestBody: {
    addresses: ['+15550001234', '+15559876543'],
    message: 'Hey everyone!',
  },
});

`updateAChat()`

Update an existing group chat’s display name. Requires the Private API.

updateAChat({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>

string

required

The GUID of the chat to update.

string

A new display name for the group chat.

Requires the Private API (minimum server version 0.3.0).

const response = await client.chats.updateAChat({
  chatGuid: 'iMessage;+;chat-guid-here',
  requestBody: {
    displayName: 'Weekend Plans',
  },
});

`deleteChat()`

Delete a chat from the iMessage client on the macOS server. This change only affects the macOS server’s iMessage client — it does not propagate to other Apple devices on the account.

deleteChat({ chatGuid }: { chatGuid: string }): CancelablePromise<any>

string

required

The GUID of the chat to delete.

Requires the Private API (minimum server version 1.3.0). Deletion only applies to the server’s macOS iMessage client.

const response = await client.chats.deleteChat({
  chatGuid: 'iMessage;+;chat-guid-here',
});

Group icon

`setGroupIcon()`

Set a group chat’s icon or photo. Requires the Private API.

setGroupIcon({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: any;
}): CancelablePromise<any>

string

required

The GUID of the group chat to update the icon for.

any

Multipart form data containing the image file to set as the group icon.

Requires the Private API.

const formData = new FormData();
formData.append('icon', iconBlob, 'group-icon.png');

const response = await client.chats.setGroupIcon({
  chatGuid: 'iMessage;+;chat-guid-here',
  requestBody: formData,
});

`removeGroupIcon()`

Remove or unset the icon for a group chat. Requires the Private API.

removeGroupIcon({ chatGuid }: { chatGuid: string }): CancelablePromise<any>

string

required

The GUID of the group chat to remove the icon from.

Requires the Private API.

const response = await client.chats.removeGroupIcon({
  chatGuid: 'iMessage;+;chat-guid-here',
});

Participants

`addParticipantToChat()`

Add a participant to an existing group chat. Include the country code in the address where possible. Requires the Private API.

addParticipantToChat({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>

string

required

The GUID of the chat to add the participant to.

string

required

The phone number or email address of the participant to add. Include the country code prefix (e.g. "+15550001234" for a US number).

Requires the Private API (minimum server version 0.3.0).

const response = await client.chats.addParticipantToChat({
  chatGuid: 'iMessage;+;chat-guid-here',
  requestBody: {
    address: '+15550001234',
  },
});

`removeParticipantFromChat()`

Remove a participant from an existing group chat. Requires the Private API.

removeParticipantFromChat({ chatGuid }: { chatGuid: string }): CancelablePromise<any>

string

required

The GUID of the chat to remove a participant from.

The participant address to remove is specified in the request body as address. Requires the Private API (minimum server version 0.3.0).

const response = await client.chats.removeParticipantFromChat({
  chatGuid: 'iMessage;+;chat-guid-here',
});

`leaveChat()`

Leave a group chat you are currently a member of. Throws an error if the target chat is not a group chat. Requires the Private API.

leaveChat({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>

string

required

The GUID of the group chat to leave.

Requires the Private API. An error is returned if you call this on a non-group (1-on-1) chat.

const response = await client.chats.leaveChat({
  chatGuid: 'iMessage;+;chat-guid-here',
});

Messages in a chat

`listMessages()`

Fetch all messages associated with a specific chat.

listMessages({ chatGuid }: { chatGuid: string }): CancelablePromise<any>

string

required

The GUID of the chat whose messages you want to retrieve.

const response = await client.chats.listMessages({
  chatGuid: 'iMessage;+;+15550001234',
});
console.log(response.data); // array of message objects

Read state

`markRead()`

Mark a chat as read on the server. Dispatches a read event to all connected BlueBubbles clients. Requires the Private API.

markRead({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>

string

required

The GUID of the chat to mark as read.

Requires the Private API (minimum server version 1.1.0).

const response = await client.chats.markRead({
  chatGuid: 'iMessage;+;+15550001234',
});

`markChatAsUnread()`

Mark a chat as unread and dispatch an unread event to all connected BlueBubbles clients. On macOS Ventura, this also officially marks the chat as unread for other iOS devices. Requires the Private API and macOS Ventura.

markChatAsUnread({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>

string

required

The GUID of the chat to mark as unread.

If you are not running macOS Ventura, the event is still dispatched to BlueBubbles clients but the chat will not be marked as unread for other iOS devices. Requires the Private API and a minimum server version of 1.4.0.

const response = await client.chats.markChatAsUnread({
  chatGuid: 'iMessage;+;+15550001234',
});

Typing indicators

`startSendTypingIndicator()`

Start broadcasting a typing indicator to the participants of a chat. Requires the Private API.

startSendTypingIndicator({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: any;
}): CancelablePromise<any>

string

required

The GUID of the chat to send the typing indicator to.

Typing indicators stop automatically when you send a message to the chat. Requires the Private API.

const response = await client.chats.startSendTypingIndicator({
  chatGuid: 'iMessage;+;+15550001234',
});

`stopSendTypingIndicator()`

Stop broadcasting a typing indicator to a chat. Requires the Private API.

stopSendTypingIndicator({ chatGuid }: { chatGuid: string }): CancelablePromise<any>

string

required

The GUID of the chat to stop sending the typing indicator to.

Typing indicators also stop automatically when you send any message to the chat. Requires the Private API.

const response = await client.chats.stopSendTypingIndicator({
  chatGuid: 'iMessage;+;+15550001234',
});

`shareContactInfo()`

Share your iCloud Contact Card with a chat. This sends your own contact information to the other participants.

shareContactInfo({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>

string

required

The GUID of the chat to share your contact info with.

const response = await client.chats.shareContactInfo({
  chatGuid: 'iMessage;+;+15550001234',
});

`getContactShareStatus()`

Check the current contact-sharing status for a chat.

getContactShareStatus({ chatGuid }: { chatGuid: string }): CancelablePromise<any>

string

required

The GUID of the chat to check contact share status for.

const response = await client.chats.getContactShareStatus({
  chatGuid: 'iMessage;+;+15550001234',
});
console.log(response.data); // contact share status

Messaging

Contacts & Handles

Server

Chats API reference — BlueBubbles SDK

Chat metadata

`getChatCount()`

`get()`

`list()`

Creating and modifying chats

`create()`

`updateAChat()`

`deleteChat()`

Group icon

`setGroupIcon()`

`removeGroupIcon()`

Participants

`addParticipantToChat()`

`removeParticipantFromChat()`

`leaveChat()`

Messages in a chat

`listMessages()`

Read state

`markRead()`

`markChatAsUnread()`

Typing indicators

`startSendTypingIndicator()`

`stopSendTypingIndicator()`

`shareContactInfo()`

`getContactShareStatus()`

Chat metadata

getChatCount()

get()

list()

Creating and modifying chats

create()

updateAChat()

deleteChat()

Group icon

setGroupIcon()

removeGroupIcon()

Participants

addParticipantToChat()

removeParticipantFromChat()

leaveChat()

Messages in a chat

listMessages()

Read state

markRead()

markChatAsUnread()

Typing indicators

startSendTypingIndicator()

stopSendTypingIndicator()

Contact sharing

shareContactInfo()

getContactShareStatus()

`getChatCount()`

`get()`

`list()`

`create()`

`updateAChat()`

`deleteChat()`

`setGroupIcon()`

`removeGroupIcon()`

`addParticipantToChat()`

`removeParticipantFromChat()`

`leaveChat()`

`listMessages()`

`markRead()`

`markChatAsUnread()`

`startSendTypingIndicator()`

`stopSendTypingIndicator()`

`shareContactInfo()`

`getContactShareStatus()`