Handles API reference — BlueBubbles SDK

A handle is a contact address — a phone number or email — that iMessage uses to identify a conversation participant. The handles service on the BlueBubbles SDK client lets you count handles stored on the macOS device, query them in bulk, retrieve a single handle by address, and check whether an address supports iMessage, FaceTime, or is currently in a focus mode such as Do Not Disturb. Access the service through client.handles.

Count handles

`getHandleCount()`

Returns the total number of handles stored in the iMessage database on the device. Signature

client.handles.getHandleCount(): CancelablePromise<any>

Example

const result = await client.handles.getHandleCount();
console.log(result); // { status: 200, data: { total: 412 } }

Query handles

`queryHandles()`

Queries handles from the iMessage database with optional pagination, relation loading, and sorting. Signature

client.handles.queryHandles({
  requestBody,
}: {
  requestBody?: Record<string, any>;
}): CancelablePromise<any>

Request body parameters

number

default:1000

Maximum number of handles to return. Useful for paging through large result sets.

number

default:0

Number of handles to skip before returning results. Combine with limit to paginate through the database.

string[]

Related data to include with each handle. Accepted values: participants, lastmessage, sms, archived.

string

Sort order for results. Pass lastmessage to sort by the most recent message. Requires lastmessage to also be present in the with array.

Example

// Fetch the first page of 100 handles, including last message data
const result = await client.handles.queryHandles({
  requestBody: {
    limit: 100,
    offset: 0,
    with: ["lastMessage"],
    sort: "lastmessage",
  },
});

// Fetch the next page
const page2 = await client.handles.queryHandles({
  requestBody: {
    limit: 100,
    offset: 100,
  },
});

Use limit and offset together to paginate through large handle lists without loading the entire database in a single request.

Get a handle by address

`get()`

Fetches a single handle’s database record by its address (phone number or email). Signature

client.handles.get({
  handleAddress,
}: {
  handleAddress: string;
}): CancelablePromise<any>

Parameters

string

required

The iMessage address to look up. Can be a phone number (e.g. +12125551234) or an email address (e.g. user@icloud.com).

Example

const handle = await client.handles.get({
  handleAddress: "+12125551234",
});

const emailHandle = await client.handles.get({
  handleAddress: "user@icloud.com",
});

Check availability

`getImessageAvailability()`

Checks whether a given address has iMessage enabled. Signature

client.handles.getImessageAvailability(): CancelablePromise<any>

Example

const result = await client.handles.getImessageAvailability();
console.log(result);

The target address is resolved from the server context. Use this to verify that an address can receive iMessages before attempting to send.

`getFacetimeavailability()`

Checks whether a given address has FaceTime enabled. Signature

client.handles.getFacetimeavailability(): CancelablePromise<any>

Example

const result = await client.handles.getFacetimeavailability();
console.log(result);

Check focus status

`getHandleSFocusStatus()`

Returns the current focus mode status for a handle. This tells you whether the recipient has Do Not Disturb or another focus mode active. Signature

client.handles.getHandleSFocusStatus(): CancelablePromise<any>

Possible return values

Value	Meaning
`unknown`	Focus status could not be determined
`silenced`	The handle has an active focus mode (e.g., DND)
`none`	No focus mode is active

Example

const focus = await client.handles.getHandleSFocusStatus();
console.log(focus); // { status: 200, data: { focusStatus: "silenced" } }

Focus status is only available on macOS versions that expose this data through the BlueBubbles Private API. If the Private API is not enabled on your server, this call may return unknown.

Messaging

Contacts & Handles

Server

Handles API reference — BlueBubbles SDK

Count handles

`getHandleCount()`

Query handles

`queryHandles()`

Get a handle by address

`get()`

Check availability

`getImessageAvailability()`

`getFacetimeavailability()`

Check focus status

`getHandleSFocusStatus()`

​Count handles

​getHandleCount()

​Query handles

​queryHandles()

​Get a handle by address

​get()

​Check availability

​getImessageAvailability()

​getFacetimeavailability()

​Check focus status

​getHandleSFocusStatus()

Count handles

`getHandleCount()`

Query handles

`queryHandles()`

Get a handle by address

`get()`

Check availability

`getImessageAvailability()`

`getFacetimeavailability()`

Check focus status

`getHandleSFocusStatus()`