Contacts¶
The contacts connectors turn a name into an email address for a message or an invitation. They are strictly read-only, never creating, modifying, or deleting a contact, and three backends answer the same search.
| Backend | Searches | Runs on |
|---|---|---|
| Apple Contacts | Every account in the Contacts app on your Mac (iCloud, Google, Exchange, On My Mac) | The desktop app on macOS |
| Google Contacts | Your own contacts in Google, on the Google sign-in Google Calendar uses ('Other contacts' are not searched) | Every platform and the headless server |
| Microsoft 365 Contacts | Your Outlook contacts, on the Microsoft 365 sign-in (not the organization directory) | Every platform and the headless server |
Each search is recorded under AI actions like any other connector call, without keeping the name you searched for or what it found (see Privacy).
Connecting¶
Google and Microsoft 365 contacts both ride a sign-in you already have, and neither sign-in asks for contacts by itself. Adding contacts is a separate step with its own consent screen, so a Google Calendar or Outlook account you connected earlier never gains access to your contacts without your explicit approval.
In Settings > Connectors, the Contacts card holds all three sources, each with where it stands (Connected, Not connected, No permission yet, Not ready while the sign-in it rides is missing, Error while its status cannot be read, or Needs attention). The card's status says Needs attention or Error when a source does, and otherwise names the sources that are connected. Microsoft 365 appears in it once you are signed in to Microsoft 365.
Apple Contacts¶
Apple Contacts connects the same way as Apple Calendar and Reminders, with the kind contacts. First allow access: macOS shows its permission prompt the first time AI:GO asks, and only when you click Allow yourself. After you answer, the choice lives in System Settings > Privacy & Security > Contacts. Then connect it. A Mac has one account for it, local.
Without access, connecting is refused, and so is a search, each with a message naming the place to allow it; neither ever brings up the prompt. Connecting is also refused when AI:GO cannot read the list of accounts in the Contacts app, since that list is how it tells this Mac's contacts apart; an earlier connection stays as it was, and you can try again. Disconnecting changes nothing in the Contacts app.
In the Contacts card, Allow asks macOS. Once access is turned off or restricted, Open System Settings opens Privacy & Security > Contacts, where you turn it back on. The desktop app on this Mac offers both buttons. Disconnect asks before it disconnects.
Google Contacts¶
Google Contacts uses the Google sign-in of the Google Calendar connector in Settings > Connectors, stored under the same account label, so sign in to Google Calendar first and then complete the four steps to add contacts.
- Start the step that adds contacts, with the OAuth client ID and redirect URI the Google Calendar sign-in uses. It returns a consent address that asks for calendar and contacts together, and keeps what you allowed before.
- Open the address, check what Google lists, and allow it.
- Paste the
codefrom the address Google sends you to, to finish. - Connect Google Contacts.
The new sign-in replaces the stored one only when Google granted both calendar and contacts and you signed in with the same Google account that is already connected. If you leave contacts unticked on Google's screen, or untick calendar, nothing is stored and Google Calendar keeps the sign-in it had. If a different Google account signs in, the step is refused and nothing changes.
In the Contacts card, Add permission runs these steps with the OAuth client ID and redirect URI of the Google Calendar card: it opens the consent screen, shows a field for the code, and connects Google Contacts when Google granted contacts. The card offers it once Google Calendar is signed in, and links to the Google Calendar card until then. Deleting the Google Calendar sign-in disconnects Google Contacts too, since it rides that sign-in.
Your OAuth client in the Google Cloud console needs the People API turned on and the contacts.readonly scope on its consent screen.
A search on an account that has not added contacts answers CONTACTS_PERMISSION_REQUIRED.
Microsoft 365 Contacts¶
Microsoft 365 Contacts connects together with mail and calendar when you sign in to Microsoft 365, though that initial sign-in omits the Contacts.Read permission so searches answer CONTACTS_PERMISSION_REQUIRED until you grant it.
Adding contacts is a second device-code sign-in for the same account. It asks for the permissions the account already has plus Contacts.Read, uses the same application (client) ID and tenant, and is checked and cancelled like the first sign-in. When it finishes, mail, calendar, and contacts are connected again with the hold windows they had. If a different Microsoft account signs in, the step ends with the error different_account and nothing is stored. A Microsoft 365 sign-in saved without its account identity cannot add contacts; sign in to Microsoft 365 again first.
In Settings, Add contacts access starts this step, in the Microsoft 365 card or the Contacts card, once mail and calendar are connected. Microsoft 365 Contacts connects and disconnects with the account.
Your Microsoft Entra app registration needs the delegated Contacts.Read permission added under API permissions for this step.
After a restart¶
A connected source stays connected when the app starts again, on the desktop and on the headless server, and starting never brings up a permission prompt or a sign-in. Apple Contacts reconnects only while macOS still allows access, Google Contacts reads the Google sign-in and the account identity kept in the keychain, and Microsoft 365 Contacts comes back with mail and calendar on the account's sign-in. A source that cannot come back (access turned off, the sign-in gone from the keychain, a server without the Contacts app) shows Needs attention in the Contacts card with the step that fixes it, until you connect it again or disconnect it. When Microsoft 365 mail and calendar came back while contacts did not, the step is Add contacts access again, in the Microsoft 365 section here or in the Microsoft 365 card.
What a search returns¶
A search takes a name, or part of one, of 2 to 100 characters. A search that contains @ finds the contact with that exact address instead. Apple Contacts and Microsoft 365 match the start of a first or last name; Google uses its own contact search.
Each match carries a display name, its email addresses with their labels (home, work, or one you typed), and the organization when there is one. Phone numbers, postal addresses, birthdays, notes, and photos are never read. People with no email address are left out, since a search is for addresses.
A search returns 10 matches unless you ask for fewer or more, and never more than 25. When more people matched, the result says truncated.
Searching needs no approval. Governance tags each search domain:contacts and pii, so a policy can match every contacts backend at once.
Privacy¶
Because search results concern other people, the audit log records less metadata than it does for other connectors.
- The name you searched for is kept only as a short hash, so repeated searches still line up without storing the name itself.
- Matches are never stored; only a fingerprint of the result and a match count (
'2 matches') are recorded. - A failed search keeps no error text, and error messages omit the searched name.
Contacts rows follow the audit retention policy like every other row, and nothing in the logs names a contact, an address, or a search.
On a server or another platform¶
Every route exists on every host. Where there is no Contacts app to reach (a headless server, Linux, Windows, or a macOS build without the connectors), a search that names Apple, and connecting Apple Contacts, answer HTTP 412 with the code CONNECTOR_HOST_UNSUPPORTED. Google and Microsoft 365 work there as they do on the desktop. In air-gapped mode both refuse before anything is sent.
REST API¶
The Management API serves the same calls under /api/v1. A search and the Google status take the agent_read scope, and everything else agent_write.
| Method | Path | Does |
|---|---|---|
| POST | /connectors/contacts/search | Search (accountId, provider, query, limit) |
| POST | /connectors/contacts/google/consent | Start the Google step that adds contacts |
| POST | /connectors/contacts/google/consent/complete | Finish it with the code |
| POST | /connectors/contacts/google/activate | Connect Google Contacts |
| POST | /connectors/contacts/google/deactivate | Disconnect Google Contacts; the Google sign-in stays |
| GET | /connectors/contacts/google/accounts/{accountId} | Whether the account is signed in, has added contacts, and is connected |
| POST | /connectors/contacts/microsoft/consent | Start the Microsoft step that adds contacts |
Name the backend with "provider": "apple" (account local), "google", or "microsoft". Apple Contacts connects through /connectors/apple/activate with {"kind": "contacts"}, and its permission is the contacts field of /connectors/apple/permissions. The Microsoft step is checked and cancelled with /connectors/microsoft/sign-in/poll and /connectors/microsoft/sign-in/cancel, and /connectors/microsoft/accounts/{accountId} reports contactsGranted.