queryHandles()
Queries handles with optional filtering, pagination, and relationship loading.
Parameters
Query options for filtering and pagination.
Filter by specific phone number or email address.
Related data to include. Options: ["messages", "chats"].
Number of results to skip for pagination.
Maximum number of results to return.
Returns
Query results with data and pagination metadata.
Array of handle objects matching the query.
Pagination information.
Total number of handles matching the query.
Number of handles returned in this response.
Example
// Query all handles
const allHandles = await client.handle.queryHandles();
console.log(`Total handles: ${allHandles.metadata.total}`);
console.log(`Returned: ${allHandles.data.length}`);
Filter by address
const result = await client.handle.queryHandles({
address: '+1234567890'
});
if (result.data.length > 0) {
console.log('Found handle:', result.data[0]);
}
const handlesWithChats = await client.handle.queryHandles({
with: ['chats', 'messages'],
limit: 50
});
handlesWithChats.data.forEach(handle => {
console.log(`${handle.address} has ${handle.chats?.length || 0} chats`);
});
const pageSize = 25;
let offset = 0;
let allHandles = [];
while (true) {
const result = await client.handle.queryHandles({
offset,
limit: pageSize
});
allHandles.push(...result.data);
if (result.data.length < pageSize) {
break; // No more results
}
offset += pageSize;
}
console.log(`Loaded ${allHandles.length} total handles`);
Use the with parameter to eagerly load related data and reduce the number of API calls needed.
getHandle()
Retrieves a specific handle by its GUID.
Parameters
The unique GUID identifier of the handle to retrieve.
Returns
The handle object containing address, service, and metadata.
Original database row ID.
Phone number or email address.
Service type (e.g., “iMessage”, “SMS”).
Country code if applicable.
Original unformatted identifier.
Example
const handleGuid = 'handle-guid-123';
const handle = await client.handle.getHandle(handleGuid);
console.log('Address:', handle.address);
console.log('Service:', handle.service);
console.log('Country:', handle.country);
Handle GUIDs are typically obtained from chat participants or message sender information.
getHandleCount()
Retrieves the total number of handles stored in the system.
Returns
Example
const totalHandles = await client.handle.getHandleCount();
console.log(`Total handles in system: ${totalHandles}`);
Use cases
- Display statistics in dashboards
- Determine if pagination is needed before querying
- Monitor handle growth over time
Quick stats example
const total = await client.handle.getHandleCount();
const { data } = await client.handle.queryHandles({
with: ['chats'],
limit: total
});
const withChats = data.filter(h => h.chats && h.chats.length > 0);
console.log(`Total handles: ${total}`);
console.log(`Handles with chats: ${withChats.length}`);
console.log(`Handles without chats: ${total - withChats.length}`);