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

# Handles API reference — BlueBubbles SDK

> Query, count, and look up iMessage handles by address. Check iMessage and FaceTime availability, and read focus status for any handle.

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**

```typescript theme={null}
client.handles.getHandleCount(): CancelablePromise<any>
```

**Example**

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

```typescript theme={null}
client.handles.queryHandles({
  requestBody,
}: {
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
```

**Request body parameters**

<ParamField body="limit" type="number" default={1000}>
  Maximum number of handles to return. Useful for paging through large result
  sets.
</ParamField>

<ParamField body="offset" type="number" default={0}>
  Number of handles to skip before returning results. Combine with `limit` to
  paginate through the database.
</ParamField>

<ParamField body="with" type="string[]">
  Related data to include with each handle. Accepted values: `participants`,
  `lastmessage`, `sms`, `archived`.
</ParamField>

<ParamField body="sort" type="string">
  Sort order for results. Pass `lastmessage` to sort by the most recent message.
  Requires `lastmessage` to also be present in the `with` array.
</ParamField>

**Example**

```typescript theme={null}
// 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,
  },
});
```

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

***

## Get a handle by address

### `get()`

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

**Signature**

```typescript theme={null}
client.handles.get({
  handleAddress,
}: {
  handleAddress: string;
}): CancelablePromise<any>
```

**Parameters**

<ParamField path="handleAddress" type="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`).
</ParamField>

**Example**

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

```typescript theme={null}
client.handles.getImessageAvailability(): CancelablePromise<any>
```

**Example**

```typescript theme={null}
const result = await client.handles.getImessageAvailability();
console.log(result);
```

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

***

### `getFacetimeavailability()`

Checks whether a given address has FaceTime enabled.

**Signature**

```typescript theme={null}
client.handles.getFacetimeavailability(): CancelablePromise<any>
```

**Example**

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

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

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

<Warning>
  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`.
</Warning>