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

# Chats API reference — BlueBubbles SDK

> Create and manage iMessage chats, control participants, set group icons, handle read state, and send typing indicators with the 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:

```typescript theme={null}
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.

```typescript theme={null}
getChatCount(): CancelablePromise<any>
```

This method takes no parameters.

```typescript theme={null}
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.

```typescript theme={null}
get({ chatGuid }: { chatGuid: string }): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to fetch, e.g. `"iMessage;+;+15550001234"`.
</ParamField>

```typescript theme={null}
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.

```typescript theme={null}
list({ requestBody }: { requestBody?: Record<string, any> }): CancelablePromise<any>
```

<ParamField body="limit" type="number">
  Maximum number of chats to return. Defaults to `1000`.
</ParamField>

<ParamField body="offset" type="number">
  Number of records to skip for pagination. Defaults to `0`.
</ParamField>

<ParamField body="with" type="array">
  Related data to include in results. Accepted values: `"participants"`, `"lastMessage"`, `"sms"`, `"archived"`, `"message.attributed-body"`, `"message.message-info-summary"`, `"message.payload-data"`.
</ParamField>

<ParamField body="sort" type="string">
  Sort results by last message time. Must be `"lastmessage"`. Requires `"lastMessage"` to also be included in `with`.
</ParamField>

```typescript theme={null}
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.

```typescript theme={null}
create({ requestBody }: { requestBody?: Record<string, any> }): CancelablePromise<any>
```

<ParamField body="addresses" type="array" required>
  A list of participant addresses (phone numbers or email addresses) to include in the new chat.
</ParamField>

<ParamField body="message" type="string">
  An optional initial message to send into the newly created chat.
</ParamField>

<Warning>
  `create()` requires the Private API to be enabled on your server (minimum server version 0.3.0).
</Warning>

```typescript theme={null}
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.

```typescript theme={null}
updateAChat({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to update.
</ParamField>

<ParamField body="displayName" type="string">
  A new display name for the group chat.
</ParamField>

<Warning>
  Requires the Private API (minimum server version 0.3.0).
</Warning>

```typescript theme={null}
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.

```typescript theme={null}
deleteChat({ chatGuid }: { chatGuid: string }): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to delete.
</ParamField>

<Warning>
  Requires the Private API (minimum server version 1.3.0). Deletion only applies to the server's macOS iMessage client.
</Warning>

```typescript theme={null}
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.

```typescript theme={null}
setGroupIcon({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: any;
}): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the group chat to update the icon for.
</ParamField>

<ParamField body="requestBody" type="any">
  Multipart form data containing the image file to set as the group icon.
</ParamField>

<Warning>
  Requires the Private API.
</Warning>

```typescript theme={null}
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.

```typescript theme={null}
removeGroupIcon({ chatGuid }: { chatGuid: string }): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the group chat to remove the icon from.
</ParamField>

<Warning>
  Requires the Private API.
</Warning>

```typescript theme={null}
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.

```typescript theme={null}
addParticipantToChat({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to add the participant to.
</ParamField>

<ParamField body="address" type="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).
</ParamField>

<Warning>
  Requires the Private API (minimum server version 0.3.0).
</Warning>

```typescript theme={null}
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.

```typescript theme={null}
removeParticipantFromChat({ chatGuid }: { chatGuid: string }): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to remove a participant from.
</ParamField>

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

```typescript theme={null}
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.

```typescript theme={null}
leaveChat({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the group chat to leave.
</ParamField>

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

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

***

## Messages in a chat

### `listMessages()`

Fetch all messages associated with a specific chat.

```typescript theme={null}
listMessages({ chatGuid }: { chatGuid: string }): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat whose messages you want to retrieve.
</ParamField>

```typescript theme={null}
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.

```typescript theme={null}
markRead({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to mark as read.
</ParamField>

<Warning>
  Requires the Private API (minimum server version 1.1.0).
</Warning>

```typescript theme={null}
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.

```typescript theme={null}
markChatAsUnread({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to mark as unread.
</ParamField>

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

```typescript theme={null}
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.

```typescript theme={null}
startSendTypingIndicator({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: any;
}): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to send the typing indicator to.
</ParamField>

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

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

***

### `stopSendTypingIndicator()`

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

```typescript theme={null}
stopSendTypingIndicator({ chatGuid }: { chatGuid: string }): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to stop sending the typing indicator to.
</ParamField>

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

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

***

## Contact sharing

### `shareContactInfo()`

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

```typescript theme={null}
shareContactInfo({
  chatGuid,
  requestBody,
}: {
  chatGuid: string;
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to share your contact info with.
</ParamField>

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

***

### `getContactShareStatus()`

Check the current contact-sharing status for a chat.

```typescript theme={null}
getContactShareStatus({ chatGuid }: { chatGuid: string }): CancelablePromise<any>
```

<ParamField path="chatGuid" type="string" required>
  The GUID of the chat to check contact share status for.
</ParamField>

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