Google Contacts

list_contacts

List "My Contacts" — explicitly saved contacts only.

Request body:

{
  "user_id": "...",
  "action": "list_contacts",
  "payload": {},
  "target_app": "contacts"
}

provider_response.result shape:

{ "connections": [{"names":[{"displayName":"..."}],"phoneNumbers":[...]}] }

search_contacts

Search "Other contacts" — people auto-remembered from email history but never manually saved. Use this if list_contacts doesn't find a match.

Request body:

{
  "user_id": "...",
  "action": "search_contacts",
  "payload": { "query": "mom" },
  "target_app": "contacts"
}

provider_response.result shape:

{ "results": [{"person":{"names":[...],"phoneNumbers":[...]}}] }

create_contact

Save a new contact.

Request body:

{
  "user_id": "...",
  "action": "create_contact",
  "payload": { "givenName": "Ada", "familyName": "Lovelace", "email": "ada@example.com", "phone": "+1234567890" },
  "target_app": "contacts"
}

provider_response.result shape:

{ "resourceName": "people/...", "names": [...] }

list_contacts returns empty but the person clearly has contacts

Cause: The contact likely lives in "Other contacts" (never manually saved) — list_contacts only sees "My Contacts."

Fix: Try search_contacts with their name as the query.

Both list_contacts and search_contacts come back empty

Cause: Usually a canonical user_id mismatch (the OAuth connection happened under a different session/device ID than the one making this call) — not a real 'no contacts' situation.

Fix: Verify the user_id used to connect matches the one used in this call exactly.