Google Calendar

Connect Google Calendar to Squid to read and manage calendar events

The Google Calendar connector's functionality

The Google Calendar connector enables Squid AI agents to read and manage calendar events using natural language. By providing AI agents with these capabilities, users can ask the AI agent to check their schedule, create events, or update meetings on their behalf.

The connector supports:

• Reading calendar events within a specified time range
• Creating and updating events with rich metadata (attendees, reminders, recurrence, Google Meet links)
• Multi-user support with secure OAuth2 authentication and automatic token refresh
• AI-powered natural language queries for calendar data

Configuring the Google Calendar connector

Squid connects to Google Calendar using OAuth2 authentication. You'll need to create a Google Cloud project and configure OAuth2 credentials.

Creating a Google Cloud project

1. Navigate to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
   • Navigate to APIs & Services > Library
   • Search for "Google Calendar API"
   • Click Enable
4. Create OAuth2 credentials:
   • Go to APIs & Services > Credentials
   • Click Create Credentials > OAuth Client ID
   • Configure the OAuth consent screen as prompted
   • Select Application type: Web application
   • Add authorized redirect URIs (e.g., https://your-app.com/oauth/callback)
   • Note the Client ID and Client Secret

Adding the Google Calendar connector to your Squid application

1. Navigate to the Connectors tab in the Squid Console.

2. Click Available Connectors.

3. Find the Google Calendar connector, and select Add Connector.

4. Provide the following configuration details:

Connector ID: A string that uniquely identifies the connector in your code.

Client ID: Your OAuth2 client ID from Google Cloud Console.

Client Secret: Your OAuth2 client secret from Google Cloud Console.

Redirect URI: Your OAuth2 redirect URI (must match what you configured in Google Cloud).

Understanding OAuth2 authentication

The Google Calendar connector uses OAuth2 for secure user authorization. Here's how the authentication flow works:

1. Authorization: Direct your users to Google's OAuth consent screen where they authorize your application. This returns an authorization code after user consent.
2. Token Exchange: Save the authorization code to Squid, which exchanges it for access and refresh tokens. Tokens are stored per-user using a unique identifier (e.g., User ID).
3. Automatic Token Management: Squid stores the tokens securely and automatically refreshes the access token when it expires.

The connector requires the following OAuth2 scopes:

[
  'openid',
  'email',
  'https://www.googleapis.com/auth/calendar.events'
]

Use these scopes when generating the OAuth authorization URL for users. For detailed instructions on implementing the OAuth flow, see the Google OAuth2 Web Server documentation.

Using the Google Calendar connector in your application

Once you have created your Google Calendar connector, you can use it either in the studio or SDK

No-code Studio

No-code solutions can be created via the Squid Agent Studio.

1. Navigate to the Studio tab in the Squid Console.

2. Click Create AI Agent.

3. Provide an Agent ID and description, such as "calendar-agent" and "This agent helps the user manage their Google Calendar".

4. Click Add Abilities, scroll to the SaaS section, and select the Google Calendar connector you created earlier.

5. Give a description for how the agent should use this connection, such as "Call this when a user wants to check their calendar or create events."

6. Click on Test and try asking the agent "What meetings do I have next week?".

Basic building blocks in code

To use the Google Calendar connector in a Squid application, install the @squidcloud/google-calendar-client npm package

npm install @squidcloud/google-calendar-client

Client setup

import { SquidGoogleCalendarClient } from '@squidcloud/google-calendar-client';
import { Squid } from '@squidcloud/client';

const squid = new Squid({
  appId: 'your-app-id',
  region: 'us-east-1.aws',
  environmentId: 'dev',
});

const calendarClient = new SquidGoogleCalendarClient(
  squid,
  'google_calendar' // your connector ID
);

Implementing the OAuth flow

After a user completes the OAuth authorization and you receive the authorization code, save it to Squid:

await calendarClient.saveAuthCode(authCode, userId);

This exchanges the code for tokens and stores them securely. You only need to do this once per user - Squid handles all token management after that.

Reading calendar events

// Get events from primary calendar for the next 7 days
const events = await calendarClient.getCalendarEvents({
  identifier: userId,
});

// Get events with custom date range
const events = await calendarClient.getCalendarEvents({
  identifier: userId,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  maxResults: 100,
});

Creating calendar events

// Create a simple timed event
const event = await calendarClient.upsertCalendarEvent({
  identifier: userId,
  summary: 'Team Meeting',
  description: 'Weekly team sync',
  start: new Date('2024-01-15T10:00:00'),
  end: new Date('2024-01-15T11:00:00'),
  location: 'Conference Room A',
});

// Create event with attendees and Google Meet
const eventWithMeet = await calendarClient.upsertCalendarEvent({
  identifier: userId,
  summary: 'Product Review',
  start: new Date('2024-01-20T14:00:00'),
  end: new Date('2024-01-20T15:00:00'),
  attendees: [
    { email: 'colleague@company.com', displayName: 'John Doe' },
    { email: 'manager@company.com' },
  ],
  addMeetLink: true,
  reminders: [
    { method: 'email', minutes: 60 },
    { method: 'popup', minutes: 10 },
  ],
});

Using AI functions

The Google Calendar connector provides AI functions that can be connected to your AI agents. The user identifier can be configured on the agent or passed in the agent context:

// Configure on the agent (persists across all calls)
const agent = this.squid.ai().agent('calendar_agent');
await agent.upsert({
  options: {
    connectedIntegrations: [
      {
        integrationId: 'google_calendar',
        integrationType: 'google_calendar',
        options: {
          identifier: userId,
        },
      },
    ],
  },
});

const result = await agent.ask('What meetings do I have next week?');

// Or pass in the agent context (per-call override)
const result = await agent.ask('What meetings do I have next week?', {
  functions: ['listCalendarEvents'],
  agentContext: { identifier: userId },
});

Congratulations! You can now manage Google Calendar events through your AI agent!