Skip to main content
The contacts service gives you access to the Contacts app data on the macOS machine running BlueBubbles Server. You can retrieve all contacts at once or query for specific contacts by passing one or more phone numbers or email addresses. This is useful for resolving display names, profile photos, and other contact metadata alongside your iMessage data. Access the service through client.contacts.
Contacts are read directly from the macOS device. The server must have permission to access the system Contacts app. If the permission has not been granted, these calls will return empty results or an error.

​
Fetch all contacts

​
getContacts()

Returns all contacts stored on the macOS device running BlueBubbles Server. Signature 
client.contacts.getContacts(): CancelablePromise<any>
Example 
const contacts = await client.contacts.getContacts();

for (const contact of contacts.data) {
  console.log(contact.displayName, contact.phoneNumbers);
}
For large contact lists, consider using queryContacts() with specific addresses instead of loading every contact on each request.

​
Query contacts by address

​
queryContacts()

Queries for contacts matching a list of addresses (phone numbers or email addresses). Use this when you already have addresses from a message or handle and want to resolve their contact information. Signature 
client.contacts.queryContacts({
  requestBody,
}: {
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
Request body parameters
​
addresses
string[]
A list of one or more phone numbers or email addresses to look up. Each entry should match the format stored in the Contacts app (e.g. +12125551234 or user@icloud.com).
Example 
// Look up contacts for a set of known addresses
const result = await client.contacts.queryContacts({
  requestBody: {
    addresses: ["+12125551234", "alice@icloud.com", "+14155550199"],
  },
});

for (const contact of result.data) {
  console.log(contact.displayName, contact.addresses);
}

// Resolve a single address after receiving a message
const senderAddress = message.handle.address;

const result = await client.contacts.queryContacts({
  requestBody: {
    addresses: [senderAddress],
  },
});

const contact = result.data[0];
console.log(`Message from: ${contact?.displayName ?? senderAddress}`);