Skip to main content
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
​
limit
number
default:1000
Maximum number of handles to return. Useful for paging through large result sets.
​
offset
number
default:0
Number of handles to skip before returning results. Combine with limit to paginate through the database.
​
with
string[]
Related data to include with each handle. Accepted values: participants, lastmessage, sms, archived.
​
sort
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
​
handleAddress
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
ValueMeaning
unknownFocus status could not be determined
silencedThe handle has an active focus mode (e.g., DND)
noneNo 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.