Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Google Contacts

Scalekit connector
Open markdown

The Google Contacts connector lets your AI agent act in each user's Google Contacts account. Each user signs in to Google Contacts once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 24 tools.

Tools
24
What they doRead · write · destructive
11 · 9 · 411 read9 write4 destructive
Users sign in with
OAuth app
Your own Google app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Google Contacts connection

    In AgentKit > Connections, create a Google Contacts connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register a Google OAuth app

    Google Contacts connections use your own OAuth app. Register one with Google and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Google Contacts connection.

    Console steps with screenshots

    Register your Scalekit environment with the Google Contacts connector so Scalekit handles the OAuth flow and token lifecycle for you. The connection name you create will be used to identify and invoke the connection programmatically. Then complete the configuration in your application as follows:

    1. Set up auth redirects

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Google Contacts and click Create. Click Use your own credentials and copy the redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

      • Navigate to Google Cloud Console → APIs & Services → Credentials.

        Google Cloud Console Credentials page listing API keys, OAuth 2.0 client IDs, and service accounts

      • Click + Create Credentials, then OAuth client ID.

        Create credentials menu showing API key, OAuth client ID, and Service account options

      • Choose Web application from the Application type menu and give the client a name, for example Agent Auth.

        Application type dropdown with Web application, Android, Chrome Extension, iOS, TVs, and Desktop app options

      • Under Authorized redirect URIs, click + Add URI, paste the redirect URI you copied from Scalekit, and click Create.

        Create OAuth client ID form with Web application type and Authorized redirect URIs section

    2. Enable the Google People API

      Google Contacts is powered by the People API — Google’s underlying API for profile and contact data.

      • In Google Cloud Console, go to APIs & Services → Library. Search for “Google People API” and click Enable.

        Google People API product page showing the Enable button and API Enabled status

    3. Get client credentials

      • Open the OAuth client you created in step 1. Google shows the Client ID under Additional information, and lets you generate a Client secret from the same page.

        OAuth client detail page showing Client ID and Authorized redirect URIs

    4. Add credentials in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections and open the connection you created.
      • Copy the Connection name shown on that connection and use that exact value in your code as connection_name or connectionName.
      • Enter your credentials:
      • Click Save.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'googlecontacts'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Google Contacts:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'googlecontacts_groups_list',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • googlecontacts_contact_getReturns a single contact by resource name from Google Contacts.Read-only

    Get Contact

    Returns a single contact by resource name from Google Contacts.

    Inputs

    person_fieldsstringrequired
    Comma-separated fields to return for the contact.
    person_idstringrequired
    The person ID of the contact to retrieve (the part after 'people/'). 'me' is not supported by this connector: it requires Google's userinfo.profile scope, which is not part of this connection's granted scopes and will return a 403.
  • googlecontacts_contacts_listReturns all contacts (connections) for the authenticated user from Google Contacts, with cursor-based pagination and optional sync token support.Read-only

    List Contacts

    Returns all contacts (connections) for the authenticated user from Google Contacts, with cursor-based pagination and optional sync token support.

    Inputs

    person_fieldsstringrequired
    Comma-separated FieldMask of person fields to return. Valid values: addresses, ageRanges, biographies, birthdays, calendarUrls, clientData, coverPhotos, emailAddresses, events, externalIds, genders, imClients, interests, locales, locations, memberships, metadata, miscKeywords, names, nicknames, occupations, organizations, phoneNumbers, photos, relations, sipAddresses, skills, urls, userDefined.
    page_sizeinteger
    Number of contacts to return per page (max 1000).
    page_tokenstring
    Page token from a previous response for pagination.
    request_sync_tokenboolean
    If true, returns a sync token on the last page for incremental sync.
    sort_orderstring
    Sort order for contacts. One of: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING.
    sync_tokenstring
    Sync token from a previous response to fetch only changed contacts.
  • googlecontacts_directory_listLists people in the Google Workspace domain directory.Read-only

    List Directory People

    Lists people in the Google Workspace domain directory. Requires the directory.readonly OAuth scope.

    Inputs

    read_maskstringrequired
    Comma-separated FieldMask of person fields to return. Valid values: addresses, ageRanges, biographies, birthdays, calendarUrls, clientData, coverPhotos, emailAddresses, events, externalIds, genders, imClients, interests, locales, locations, memberships, metadata, miscKeywords, names, nicknames, occupations, organizations, phoneNumbers, photos, relations, sipAddresses, skills, urls, userDefined.
    sourcesstringrequired
    Directory source type to return. Use DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT for domain contacts or DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE for domain profiles.
    page_sizeinteger
    Number of people to return per page (1–1000, default 100).
    page_tokenstring
    Page token from a previous response for pagination.
    request_sync_tokenboolean
    If true, returns a sync token on the last page for incremental sync.
    sync_tokenstring
    Sync token from a previous response to fetch only changed people.
  • googlecontacts_group_getReturns a single contact group by resource name, including its members if requested.Read-only

    Get Contact Group

    Returns a single contact group by resource name, including its members if requested.

    Inputs

    group_idstringrequired
    The group ID of the contact group (the part after 'contactGroups/').
    group_fieldsstring
    Comma-separated fields to return: clientData, groupType, memberCount, metadata, name.
    max_membersinteger
    Maximum number of group members to return (default 0 = none).
  • googlecontacts_groups_batch_getRetrieves up to 200 contact groups in a single request from Google Contacts.Read-only

    Batch Get Contact Groups

    Retrieves up to 200 contact groups in a single request from Google Contacts.

    Inputs

    resource_namesarrayrequired
    One or more contact group resource names to retrieve, in the format 'contactGroups/<id>' (e.g. 'contactGroups/myContacts' or 'contactGroups/starred'), up to 200. Get IDs from googlecontacts_groups_list. Sent as repeated resourceNames query parameters.
    group_fieldsstring
    Comma-separated fields to return for each group: clientData, groupType, memberCount, metadata, name.
    max_membersinteger
    Maximum number of group members to return per group (default 0 = none).
  • googlecontacts_groups_listReturns all contact groups owned by the authenticated user, including system groups like 'My Contacts' and 'Starred'.Read-only

    List Contact Groups

    Returns all contact groups owned by the authenticated user, including system groups like 'My Contacts' and 'Starred'.

    Inputs

    group_fieldsstring
    Comma-separated fields to return: clientData, groupType, memberCount, metadata, name.
    page_sizeinteger
    Number of contact groups to return per page (max 1000).
    page_tokenstring
    Page token from a previous response for pagination.
    sync_tokenstring
    Sync token to fetch only changed contact groups. Unlike googlecontacts_contacts_list, this endpoint always returns nextSyncToken on the last page — no request flag is needed.
All 103 in Productivity