Skip to main content

Google Calendar Integration with SmythOS

This page shows you how to connect Google Calendar to SmythOS and pick the right component for every calendar task.

Want your calendar to work smarter? Connect Google Calendar to SmythOS and let your agents create, read, and manage events in real time.

TL;DR
Link your Google Account to SmythOS by setting up OAuth 2.0 credentials in Google Cloud Console. Then, use our Google Calendar components to enable your agents to automate various calendar tasks, reducing manual scheduling and event management.

Quick Links:

Why Integrate Google Calendar with Your Agent?​

Google Calendar is a powerful tool for time management and scheduling. By integrating it with SmythOS, you empower your agents to interact with your calendar programmatically, unlocking significant automation potential.

  • Automate Event Creation: Agents can schedule meetings, block out time, or create reminders in Google Calendar based on triggers from other systems or agent logic (e.g., creating a follow-up event after a customer interaction).
  • Dynamic Scheduling: Agents can read calendar availability to make intelligent scheduling decisions, preventing conflicts and finding optimal times for events or resource allocation.
  • Centralized Event Logging: Use Google Calendar as a log for important time-stamped events generated by your automated processes, providing a clear, chronological view.
  • Real-time Updates: Enable agents to update event details (like status, attendees, or location) as circumstances change within your workflows.

Essentially, this integration transforms your Google Calendar from a static scheduling tool into an intelligent, interactive part of your SmythOS ecosystem. The result? Less manual effort, fewer scheduling errors, timely information, and more capacity for your team to focus on strategic tasks.

INFO
Why Integrate Google Calendar with Your Agent?

Google Calendar is a cornerstone for managing time and events. Integrating it with SmythOS allows your agents to become active participants in your scheduling and time management processes. Each component is designed for a specific calendar operation:

  • Automate Event Creation: Let agents automatically schedule project kick-offs, client follow-ups, or internal reminders directly in team members' calendars when certain conditions are met in your workflows.
  • Intelligent Availability Checks: Before committing to a new task or scheduling a resource, agents can query Google Calendar via the "List Events" component to check for existing commitments, preventing double-bookings.
  • Synchronized Task Management: If your agent manages tasks with deadlines, it can create corresponding events in Google Calendar to ensure visibility and timely reminders.
  • Automated Meeting Updates: Agents can modify existing events—for instance, adding a meeting link generated by another service, updating the attendee list, or changing the event status—based on real-time information.

By connecting Google Calendar, you reduce manual data entry, minimize scheduling conflicts, and ensure that your calendar accurately reflects the activities and commitments managed by your automated SmythOS agents.

Prerequisites: What You'll Need to Get Started​

Before you begin the integration, please ensure you have the following:

  • An active SmythOS account. (If you're new to SmythOS, you can sign up here.)
  • A Google Account that has access to the Google Calendar(s) you plan to use.
  • You will need to generate OAuth 2.0 credentials (Client ID and Client Secret) from the Google Cloud Console. This process also involves configuring an OAuth consent screen and enabling the Google Calendar API. Detailed steps are provided below.
  • The Authorized redirect URI for SmythOS, which is: https://app.smythos.com/oauth/google/callback (You'll need this when creating credentials in Google Cloud Console).

Step-by-Step: Connecting Your Google Calendar Account​

Let's establish the connection between SmythOS and your Google Calendar. This involves obtaining OAuth 2.0 credentials from Google and then using them to authenticate within SmythOS. This is typically a one-time setup per Google account you wish to integrate.

Part A: Obtaining Your Client ID and Client Secret from Google Cloud Console​

  1. Navigate to Google Cloud Console:

    • Go to https://console.cloud.google.com/.
    • Sign in with the Google account that owns or has administrative access to the Google Calendar(s) you intend to use.
    • If you don't have a project, create a new one. Otherwise, select an existing project.

  2. Enable the Google Calendar API:

    • In the search bar at the top, type "Google Calendar API" and select it from the results under "Marketplace."
    • On the Google Calendar API page, click the Enable button. If it's already enabled, you can proceed to the next step.

  3. Configure the OAuth Consent Screen:

    • In the left-hand navigation menu (or by searching), go to "APIs & Services" > "OAuth consent screen."
    • User Type:
      • Choose "Internal" if your app is only for users within your Google Workspace organization.
      • Choose "External" if you want any Google user (including yourself with a personal Gmail account) to be able to authorize the app. If you select "External" and your app is not yet published, it will be in "testing" mode, and you'll need to add test users.
    • Click Create.
    • App Information:
      • App name: Enter a descriptive name, e.g., "SmythOS Calendar Integration."
      • User support email: Select your email address.
      • App logo (Optional): Upload a logo if desired.
      • Developer contact information: Enter your email address.
    • Click Save and Continue.
    • Scopes: Click Add or Remove Scopes.
      • In the filter, search for "Google Calendar API."
      • Select the necessary scopes. For full functionality (create, read, update, delete events), you'll typically need:
        • .../auth/calendar (Manage primary calendar and other calendars you have access to)
        • .../auth/calendar.events (View and edit events on all your calendars)
      • Best Practice: Only request scopes that are essential for the actions your agents will perform. For example, if agents only need to read events, .../auth/calendar.events.readonly might be sufficient.
      • Click Update after selecting scopes.
    • Click Save and Continue.
    • Test Users (if "External" and in testing mode):
      • Click + Add Users.
      • Enter the email addresses of the Google accounts that will be used to test this integration (including your own if it's a personal account).
    • Click Save and Continue.
    • Review the summary page and click Back to Dashboard. (Your app might remain in "testing" mode unless you go through Google's verification process, which is usually not necessary for internal tools or limited user bases).

  4. Create OAuth 2.0 Credentials:

    • Navigate to "APIs & Services" > "Credentials."
    • Click + Create Credentials at the top and select OAuth client ID.
    • Application type: Select Web application from the dropdown.
    • Name: Give your OAuth client ID a descriptive name, e.g., "SmythOS Calendar Web Client."
    • Authorized redirect URIs:
      • Click + Add URI.
      • Enter the SmythOS callback URL: https://app.smythos.com/oauth/google/callback
      • This URI must be an exact match.
    • Click Create.

  5. Copy Your Credentials:

    • A dialog box will appear showing Your Client ID and Your Client Secret.
    • Copy both of these values immediately and store them securely. You will need them in the next part to configure the integration in SmythOS.
      Secure Your Credentials!
      Your Client ID and especially your Client Secret are sensitive. Treat them like passwords. Do not embed them directly in agent code if avoidable, share them in public forums, or commit them to version control. SmythOS offers a Vault for secure credential storage. Learn more about SmythOS Vault here.

Part B: Authenticating in SmythOS​

  1. Navigate to SmythOS Integrations: In your SmythOS dashboard, find and click on the "Integrations" section.
  2. Add or Configure Google Calendar Integration:
    • Look for "Google Calendar" in the list of available integrations and click to add or configure it.
  3. Enter Your OAuth Credentials:
    • You will see fields to input the Client ID and Client Secret that you obtained from the Google Cloud Console in Part A.
    • Carefully paste these values into the respective fields.
  4. Initiate Authentication:
    • Click the Authenticate button within the SmythOS Google Calendar integration settings.
  5. Google Authorization Flow:
    • You will be redirected to a Google Sign-In page. Log in using the Google account you want to connect with SmythOS (this should be an account you added as a "test user" if your OAuth app is in testing mode and "External").
    • Google will then display a consent screen, showing the name of your app (e.g., "SmythOS Calendar Integration") and the permissions it's requesting (based on the scopes you configured). Review these permissions.
    • Click Allow or Grant to authorize SmythOS to access your Google Calendar data.
  6. Redirection to SmythOS:
    • After successful authorization, you'll be redirected back to SmythOS.
    • The Google Calendar integration should now indicate that it's connected and authenticated. Connection Confirmed!
Switching Google Accounts or Reconnecting?
If you ever need to connect a different Google Account or refresh an existing connection, you can typically find a Sign Out, Disconnect, or Deauthenticate button within the Google Calendar integration settings in SmythOS. After deauthenticating, simply repeat the authentication steps (Part B, and potentially Part A if credentials change or scopes need updating) with the new account.

Google Calendar Components: An Overview​

With your Google Account successfully linked, you gain access to a range of Google Calendar components within SmythOS. These components are specialized tools your agents can use to perform specific operations on your calendars.

Click any component name to jump directly to its detailed guide. Here’s what's available:

ComponentAction TypeSummary
Create EventWriteAdds a new event to a calendar.
required calendarId, summary, start, end
Get EventReadRetrieves details for a specific event.
required calendarId, eventId
List EventsReadFetches a list of events from a calendar, optionally filtered by time or query.
required calendarId
Patch Update EventWriteModifies specific fields of an existing event.
required calendarId, eventId, Body
Delete EventWriteRemoves an event from a calendar.
required calendarId, eventId
Good to Know!
That initial authentication you performed (OAuth 2.0 setup) covers all these components. You won't need to re-authenticate or re-enter your Client ID/Secret for each individual component you use with the connected Google account.

Understanding Common Calendar Component I/O Fields​

Many Google Calendar components share common input and output field names or structures. This section defines these common elements to avoid repetition in the detailed component guides.

FieldTypeDescription
calendarIdstringIdentifier of the calendar. Use primary for the authenticated user's primary calendar, or the calendar's specific ID (often an email address for user/group calendars, or a long string for resource calendars).
eventIdstringUnique identifier of a specific event within a calendar. Typically obtained from the output of "Create Event" or "List Events" components.
sendNotificationsboolean(Optional) Whether to send notifications to attendees about the event change (creation, update, deletion). Defaults vary by component/API, typically false if not specified.
conferenceDataSolutionKeystring(Optional, for Create/Patch) A type of conference solution, e.g., hangoutsMeet, to be added to the event. Used with conferenceData.createRequest.
maxAttendeesinteger(Optional, for Create/Patch) The maximum number of attendees to include in the event.
Footnotes
  1. calendarId — Using primary is the most common for interacting with the authenticated user's main calendar. For shared or other calendars, you'll need their specific ID.
  2. Event fields within the event object (like summary, start.dateTime, attendees) have specific formatting requirements by Google Calendar API.

Deep Dive into Calendar I/O Fields​

Switch between Inputs and Outputs below to see more detailed explanations and examples for parameters frequently used across multiple Google Calendar components.

calendarId (string)

Identifies the calendar to interact with. This is a required field for almost all components.

  • primary: Special keyword representing the primary calendar of the authenticated user. This is the most common value.
  • Calendar Email Address: For other user calendars or Google Group calendars you have access to (e.g., user@example.com, group_email@group.calendar.google.com).
  • Calendar ID: A long, unique string ID for specific calendars (often resource calendars or secondary calendars). You can find this in the calendar settings in Google Calendar.
Permissions
Ensure the authenticated Google account has the necessary permissions (view, edit, etc.) for the specified calendarId.
INFO
Component guides will list only extra or unique fields. Refer back here whenever you need a refresher on these standard parameters.

Quick Reference: Google Calendar Components​

Use this table to quickly compare inputs, outputs, and typical use cases for each Google Calendar component. For detailed parameter explanations, refer to the Deep Dive for I/O section.

ComponentKey Input Fields (Type, Required, Description)Key Output Fields (Type, Description)Use Case & Details
Create EventcalendarId (string, Yes): Target calendar.
summary (string, Yes): Event title.
start (object, Yes): Start time/date.
end (object, Yes): End time/date.
attendees (array, No): List of invitees.
description (string, No): Event details.
location (string, No): Event location.
sendNotifications (boolean, No): Notify attendees.		event (object): The created event object.
Response (object): Raw API response.
Headers (object): HTTP headers.		Adds a new entry to a Google Calendar. Ideal for automating meeting creation, scheduling reminders, or logging important milestones.
Get EventcalendarId (string, Yes): Calendar ID.
eventId (string, Yes): Specific event ID.		event (object): The retrieved event object.
Response (object): Raw API response.
Headers (object): HTTP headers.		Fetches detailed information about a single, known event. Useful for checking event status or details before further action.
List EventscalendarId (string, Yes): Calendar to query.
timeMin (string, No): Start of date/time range (RFC3339).
timeMax (string, No): End of date/time range (RFC3339).
q (string, No): Free-text search query.
singleEvents (boolean, No): Expand recurring events.		items (array): List of event objects.
nextPageToken (string): Token for more results (in Response.nextPageToken).
Response (object): Raw API response.
Headers (object): HTTP headers.		Retrieves multiple events based on criteria. Perfect for checking availability, generating daily/weekly agendas, or finding specific types of events.
Patch Update EventcalendarId (string, Yes): Target calendar.
eventId (string, Yes): Event to modify.
Body (object, Yes): JSON object with fields to update (e.g., summary, start, attendees).
sendNotifications (boolean, No): Notify attendees.		event (object): The updated event object.
Response (object): Raw API response.
Headers (object): HTTP headers.		Modifies specific details of an existing event without overwriting the entire event. Use for changing times, descriptions, locations, or attendee lists.
Delete EventcalendarId (string, Yes): Calendar ID.
eventId (string, Yes): Event to remove.
sendNotifications (boolean, No): Notify attendees of cancellation.		Response (object): Raw API response (often empty on success).
Headers (object): HTTP headers.		Permanently removes an event from the specified calendar. Use with caution.

Which Google Calendar Component Should I Use With My Agent?​

If you need to…Typical Target / Key InputsUse this ComponentWhy this one?
Create a new meeting or remindercalendarId, summary, start, end objectsCreate EventDirectly adds a new, fully defined event to the calendar.
Log a past activity as an all-day eventcalendarId, summary, start.date, end.dateCreate EventUse date fields in start/end for all-day entries.
Check details of a specific known eventcalendarId, eventIdGet EventRetrieves all information for a single event if you have its ID.
Find out what is scheduled for today or this weekcalendarId, timeMin, timeMax, singleEvents=trueList EventsFetches all events within a specified time window; singleEvents expands recurring ones.
Search for events containing specific keywordscalendarId, q (query string)List EventsFilters events based on a text search across event fields.
Change an event's title or timecalendarId, eventId, Body (with summary or start/end)Patch Update EventModifies only the specified parts of an existing event, preserving other details.
Add or remove attendees from an eventcalendarId, eventId, Body (with attendees array)Patch Update EventUpdates the attendee list for an existing event.
Cancel a scheduled meetingcalendarId, eventIdDelete EventRemoves an event. Use sendNotifications to inform attendees if needed.
INFO
Still unsure? For creating new entries, start with Create Event. For finding existing ones, List Events is your primary tool. For modifying, use Patch Update Event.

Detailed Component Guides​

This section provides detailed information for each Google Calendar component. Remember to refer to the Understanding Common Sheet Component Fields and Deep Dive Into Calendar Fields for explanations of common inputs (like calendarId, eventId, start/end objects, attendees) and outputs (like the event object structure, Response, Headers). Each component guide below will highlight any unique fields or provide specific context.

Create Event — Add New Calendar Entry​

Adds a new event to a specified calendar. Supports timed events, all-day events, attendee invitations, location, description, and conference data (e.g., Google Meet links).

INFO
This component is fundamental for automating scheduling. It uses the standard calendarId, start, and end inputs, along with event-specific details like summary. The primary output is the created event object.

Inputs​

FieldRequiredNotes
calendarIdrequiredCalendar ID. Defaults to primary. See Standard Parameters.
summaryrequiredThe title of the event.
startrequiredEvent start time/date object. See Standard Parameters for dateTime/date and timeZone structure.
endrequiredEvent end time/date object. See Standard Parameters.
descriptionoptionalA detailed description of the event.
locationoptionalThe geographical location of the event as a free-form string.
attendeesoptionalArray of attendee objects. See Standard Parameters.
sendNotificationsoptionalBoolean. Whether to send notifications to attendees about the event creation. Default: false.
conferenceDataoptionalObject to specify conference data. To create a new Google Meet link: {"createRequest": {"requestId": "UNIQUE_STRING", "conferenceSolutionKey": {"type": "hangoutsMeet"}}}. requestId should be a unique string for each request.
guestsCanInviteOthersoptionalBoolean. Whether attendees can invite others. Default: true.
guestsCanModifyoptionalBoolean. Whether attendees can modify the event. Default: false.
guestsCanSeeOtherGuestsoptionalBoolean. Whether attendees can see other attendees. Default: true.
visibilityoptionalEvent visibility. Values: default, public, private, confidential.
remindersoptionalObject to specify reminders. E.g., {"useDefault": false, "overrides": [{"method": "popup", "minutes": 30}]}.

Outputs​

FieldDescription
eventThe full Google Calendar Event resource object that was created. See Common Output Fields (Event Object Structure).
ResponseRaw API payload from Google.
HeadersHTTP headers from the API response.
Use Case
An agent processes a "New Project Kick-off" form. Upon submission, it uses "Create Event" to schedule a 1-hour kick-off meeting in the project manager's primary calendar for the next business day at 10 AM, invites the project team members listed in the form, adds a Google Meet link, and includes the project brief in the event description. 
{
  "component": "googleCalendar.createEvent",
  "calendarId": "primary",
  "summary": "Project Alpha - Kick-off Meeting",
  "description": "Initial kick-off meeting to discuss project goals, timeline, and roles. Agenda attached.",
  "start": {
    "dateTime": "2025-09-15T10:00:00-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "end": {
    "dateTime": "2025-09-15T11:00:00-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "attendees": [
    {"email": "project.manager@example.com"},
    {"email": "lead.developer@example.com"},
    {"email": "client.contact@example.com"}
  ],
  "location": "Virtual / Google Meet",
  "conferenceData": {
    "createRequest": {
      "requestId": "projAlphaKickoff123",
      "conferenceSolutionKey": {"type": "hangoutsMeet"}
    }
  },
  "sendNotifications": true,
  "reminders": {
    "useDefault": false,
    "overrides": [
      {"method": "email", "minutes": 1440},
      {"method": "popup", "minutes": 60}
    ]
  }
}

Get Event — Fetch Details for a Specific Event​

Retrieves detailed information about a single event, identified by its eventId, from a specified calendarId.

INFO
This component uses the standard calendarId and eventId inputs. Its primary output is the event object containing all details of the fetched event.

Inputs​

FieldRequiredNotes
calendarIdrequiredCalendar ID. Defaults to primary. See Standard Parameters.
eventIdrequiredThe unique ID of the event to retrieve. See Standard Parameters.

Outputs​

FieldDescription
eventThe full Google Calendar Event resource object that was fetched. See Common Output Fields (Event Object Structure).
ResponseRaw API payload from Google.
HeadersHTTP headers from the API response.
Use Case
An agent needs to confirm the current start time and attendee list for a scheduled maintenance window before sending out a final reminder. It uses "Get Event" with the known eventId to fetch these details. 
{
  "component": "googleCalendar.getEvent",
  "calendarId": "shared.calendar@example.com",
  "eventId": "eventabcdef12345"
}

List Events — Retrieve Multiple Events​

Fetches a list of events from a specified calendar. Events can be filtered by time range, search query, and other criteria.

INFO
Key inputs include calendarId and optional filters like timeMin, timeMax, and q. The primary output is items, an array of event objects.

Inputs​

FieldRequiredNotes
calendarIdrequiredCalendar ID. Defaults to primary. See Standard Parameters.
timeMinoptionalRFC3339 timestamp (e.g., YYYY-MM-DDTHH:mm:ssZ). Filters for events starting no earlier than this time.
timeMaxoptionalRFC3339 timestamp. Filters for events starting no later than this time.
qoptionalFree-text search query. Searches across event fields like summary, description, location, attendees.
singleEventsoptionalBoolean. Whether to expand recurring events into their individual instances. Default: false. Set to true for most date-range queries.
orderByoptionalOrder of the returned events. Values: startTime (default) or updated.
maxResultsoptionalInteger. Maximum number of events to return (e.g., 10, 100). Default: 250. Max: 2500.
pageTokenoptionalString. Token specifying the next page of results to return. Obtained from a previous "List Events" Response.nextPageToken.
showDeletedoptionalBoolean. Whether to include deleted events. Default: false.
iCalUIDoptionalString. Filters for events with a specific iCalendar UID.

Outputs​

FieldDescription
itemsAn array of Google Calendar Event resource objects matching the criteria. See Common Output Fields (Event Object Structure).
summaryString. The summary (title) of the calendar queried.
timeZoneString. The timeZone of the calendar queried.
nextPageTokenString. Token to retrieve the next page of results. Present if more results exist. Found in Response.nextPageToken.
ResponseRaw API payload from Google.
HeadersHTTP headers from the API response.
Use Case
An agent needs to find all "Team Meeting" events scheduled for the current week in the "Team Shared Calendar" to compile an agenda. It uses timeMin and timeMax for the week's range and q="Team Meeting". 
{
  "component": "googleCalendar.listEvents",
  "calendarId": "team.shared.calendar@example.com",
  "timeMin": "2025-09-15T00:00:00Z",
  "timeMax": "2025-09-19T23:59:59Z",
  "q": "Weekly Sync",
  "singleEvents": true,
  "orderBy": "startTime",
  "maxResults": 20
}
Troubleshooting
  • Time Zone for timeMin/timeMax: Ensure these RFC3339 timestamps correctly specify UTC (Z) or an offset if not UTC, to avoid incorrect date ranges.
  • singleEvents=false (default): If you're querying a date range and not seeing individual instances of recurring events, set singleEvents to true.
  • Pagination: For more than maxResults events, you'll need to implement logic to use the nextPageToken from the Response to fetch subsequent pages.

Patch Update Event — Modify an Existing Event​

Modifies specific fields of an existing event without overwriting the entire event resource. Only the fields provided in the Body will be updated.

INFO
Requires calendarId, eventId, and a Body object containing the fields to change. Uses standard parameter structures for fields like start, end, attendees if they are being updated.

Inputs​

FieldRequiredNotes
calendarIdrequiredCalendar ID. See Standard Parameters.
eventIdrequiredThe unique ID of the event to update. See Standard Parameters.
BodyrequiredA JSON object containing the fields to update. For example: {"summary": "New Title", "location": "New Location"}. Refer to Google Calendar Event resource for modifiable fields.
sendNotificationsoptionalBoolean. Whether to send notifications to attendees about the event update. Default: false.
conferenceDataVersionoptionalInteger. Set to 1 to indicate that conferenceData fields should be updated. Required if modifying conferenceData.

Outputs​

FieldDescription
eventThe full, updated Google Calendar Event resource object. See Common Output Fields (Event Object Structure).
ResponseRaw API payload from Google.
HeadersHTTP headers from the API response.
Use Case
A meeting's location changes from a physical room to a virtual meeting. An agent uses "Patch Update Event" to change the location field and update the description with the new meeting link, without altering the original summary, time, or attendee list. 
{
  "component": "googleCalendar.patchUpdateEvent",
  "calendarId": "primary",
  "eventId": "eventtoupdate123",
  "Body": {
    "summary": "Updated: Project Review",
    "location": "Online - Google Meet (Link in description)",
    "description": "Project review meeting. New Google Meet link: https://meet.google.com/xyz-abc-pqr",
    "start": {
      "dateTime": "2025-09-20T14:30:00-07:00",
      "timeZone": "America/Los_Angeles"
    },
    "end": {
      "dateTime": "2025-09-20T15:30:00-07:00",
      "timeZone": "America/Los_Angeles"
    }
  },
  "sendNotifications": true
}
Troubleshooting
  • Modifying Attendees: To add, remove, or change attendee status, provide the complete new attendees array in the Body. Patching individual attendees within the array is not directly supported; you replace the entire array.
  • Permissions: Ensure write access to the calendarId.
  • conferenceDataVersion: If updating conference data (e.g., changing a Meet link), you might need to set conferenceDataVersion: 1 in the input to signal the API to process these changes.

Delete Event — Remove an Event​

Permanently removes an event from the specified calendar.

INFO
This is a straightforward action requiring calendarId and eventId. Use with caution as deletion is permanent.

Inputs​

FieldRequiredNotes
calendarIdrequiredCalendar ID. See Standard Parameters.
eventIdrequiredThe unique ID of the event to delete. See Standard Parameters.
sendNotificationsoptionalBoolean. Whether to send notifications (cancellations) to attendees. Default: false.

Outputs​

FieldDescription
ResponseRaw API payload from Google. Usually empty for a successful delete operation (HTTP 204 No Content).
HeadersHTTP headers from the API response.
Use Case
If a project is cancelled, an agent can automatically find all associated future meetings using "List Events" (e.g., by searching for the project name in the summary) and then use "Delete Event" in a loop to remove them from the calendar, optionally notifying attendees. 
{
  "component": "googleCalendar.deleteEvent",
  "calendarId": "primary",
  "eventId": "eventtodelete789",
  "sendNotifications": true
}
Troubleshooting
  • Irreversible Action: Event deletion is permanent. Ensure you have the correct eventId.
  • Permissions: The authenticated user must have write access to the calendarId to delete events.
  • Recurring Events: Deleting an instance of a recurring event might have different behavior (e.g., deleting just that instance, or the instance and all following) depending on Google Calendar's API handling for that specific event type. Test thoroughly.

Best Practices & Advanced Tips​

To make the most of your Google Calendar integration with SmythOS, consider these tips:

  • Minimal Scopes: During OAuth setup in Google Cloud Console, only request the API scopes that your agents absolutely need (e.g., .../auth/calendar.events.readonly if only reading events, or .../auth/calendar.events for full read/write). This enhances security by limiting potential access.
  • Idempotency: For operations like "Create Event," especially in workflows that might be retried, design your agent logic to prevent duplicate event creations. This could involve:
    • Storing the eventId of created events in SmythOS Vault or a database.
    • Using the iCalUID field: You can either provide your own iCalUID during event creation or use the one Google generates to check for existing events.
  • Time Zones are Critical:
    • When specifying start.dateTime and end.dateTime, always include the start.timeZone and end.timeZone fields with valid IANA time zone names (e.g., America/New_York, Europe/London, Asia/Tokyo).
    • For timeMin and timeMax in "List Events," use UTC (Z suffix) or include the correct timezone offset in your RFC3339 timestamps to ensure accurate filtering across different time zones.
  • singleEvents=true for "List Events": When querying for events within a date range, setting singleEvents: true is highly recommended. This expands instances of recurring events, ensuring your agent sees all actual occurrences within the period.
  • Error Handling & Response Object: Always check component outputs for errors. The Response object (raw API payload from Google) often contains detailed error messages that are invaluable for debugging.
  • Use "Patch Update Event" for Modifications: When changing an existing event, "Patch Update Event" is generally preferred over a full update (if one were available) because it only modifies the fields you specify, reducing the risk of unintentionally overwriting other details.
  • Notifications (sendNotifications): Be mindful of the sendNotifications parameter in components like "Create Event," "Patch Update Event," and "Delete Event." Use it to control whether attendees receive email notifications, which can be crucial for user experience.
  • Pagination for "List Events": If you expect "List Events" to return more events than your maxResults limit (or the default of 250), you must implement logic to handle pagination using the nextPageToken found in the Response object of the previous call.
  • Conference Data (conferenceData): Utilize the conferenceData input in "Create Event" or "Patch Update Event" to automatically create or manage video conferencing links (like Google Meet) for your events. Ensure you provide a unique requestId for createRequest.
  • Rate Limiting: Be aware of Google Calendar API usage quotas. If your agents perform many calendar operations in a short period, you might encounter rate limits. Design workflows to be efficient, and implement retry logic with backoff if necessary.
  • Testing with Non-Primary Calendars: If interacting with shared or resource calendars, thoroughly test permissions and calendarId usage. primary only works for the authenticated user's main calendar.

Troubleshooting Common Issues​

Encountering an issue with your Google Calendar integration? Here are solutions to some common problems:

  • Authentication Errors (e.g., invalid_client, redirect_uri_mismatch, access_denied):

    • Possible Cause(s): Incorrect Client ID or Client Secret entered in SmythOS; "Authorized redirect URIs" in Google Cloud Console not matching https://app.smythos.com/oauth/google/callback exactly; user denied permissions during the Google consent screen.
    • Solution(s):
      1. Verify Client ID and Client Secret in SmythOS match Google Cloud Console.
      2. Ensure the redirect URI in Google Cloud Console is https://app.smythos.com/oauth/google/callback.
      3. If access_denied, the user must re-authenticate and grant the requested permissions.
      4. Ensure the Google User account used for authentication is added as a "Test User" in GCP OAuth Consent Screen settings if the app is in "testing" mode and "External".

  • 403 Forbidden / Permission Denied Errors when using components:

    • Possible Cause(s): The authenticated Google account lacks necessary permissions for the target calendarId, or the required API scopes were not requested/granted during OAuth setup.
    • Solution(s):
      1. In Google Calendar, check the sharing settings for the calendarId in question. Ensure the authenticated Google account has appropriate access rights (e.g., "Make changes to events" for creating/updating, or "See all event details" for reading).
      2. In Google Cloud Console, go to "APIs & Services" > "OAuth consent screen." Edit your app registration, go to "Scopes," and ensure all necessary scopes (e.g., .../auth/calendar.events, .../auth/calendar) are listed and saved.
      3. After updating scopes in Google Cloud Console, you may need to de-authenticate and re-authenticate the Google Calendar integration within SmythOS.

  • 404 Not Found Errors (for "Get Event," "Patch Update Event," "Delete Event"):

    • Possible Cause(s): The provided eventId is incorrect, does not exist in the specified calendarId, or the authenticated user lacks permission to see that specific event (even if they have access to the calendar).
    • Solution(s): Double-check the eventId for typos. Confirm the event exists in the correct calendarId. Ensure the authenticated user has at least view access to that particular event.

  • Incorrect calendarId Usage:

    • Possible Cause(s): Using an invalid calendar ID format or an ID for a calendar the authenticated user cannot access.
    • Solution(s): Remember primary is a special keyword for the authenticated user's main calendar. For other calendars, use their full ID (often an email address for user/group calendars, or a long string for resource calendars). Verify access permissions.

  • Invalid Date/Time Formats or Time Zone Issues:

    • Possible Cause(s): start or end date/time objects are not in RFC3339 format; timeZone is missing when dateTime is used; timeMin/timeMax for "List Events" have incorrect timezone handling.
    • Solution(s):
      1. For dateTime fields: Use YYYY-MM-DDTHH:mm:ssZ (for UTC) or YYYY-MM-DDTHH:mm:ss±HH:mm (with offset). Example: 2025-10-23T10:00:00-07:00.
      2. Always include the timeZone field (e.g., "America/Los_Angeles") within the start and end objects if using dateTime to represent local time.
      3. For all-day events: Use date with YYYY-MM-DD format. E.g., "start": {"date": "2025-10-23"}.
      4. For timeMin/timeMax in "List Events," it's safest to use UTC (Z) to avoid ambiguity unless you are certain about local time handling.

  • Events Not Appearing in "List Events" as Expected:

    • Possible Cause(s): singleEvents is false (default) for recurring events; timeMin/timeMax range is incorrect or affected by time zones; search query q is too restrictive; pagination not handled.
    • Solution(s): Set singleEvents: true for date range queries. Verify timeMin/timeMax RFC3339 timestamps and their time zones. Test with a broader query or no query. Check Response.nextPageToken for more results.
INFO
If you're still facing issues, the detailed Response output from the Google Calendar components often contains specific error messages directly from Google that can provide excellent clues. The SmythOS support team is always ready to help. Get help from the SmythOS team

What's Next?​

Congratulations! You've successfully set up the SmythOS Google Calendar integration and explored its powerful components. You're now equipped to build agents that can intelligently interact with your calendar data, automating scheduling, reminders, and event management.

Consider these next steps on your journey:

  • Build an Agent That...
    • Monitors a CRM for new "Closed-Won" deals and automatically schedules a "Client Onboarding" meeting in the account manager's calendar using "Create Event," inviting the client and attaching relevant documents in the description.
    • Allows team members to request vacation time via a SmythOS form. The agent checks the team calendar for conflicts ("List Events"), then, if approved, creates an all-day event for the vacation period.
    • Sends a personalized daily agenda to users via Slack or email, by fetching today's events ("List Events") and formatting the information.
    • Listens for webhook events from a project management tool. When a task deadline is updated, the agent uses "List Events" to find the corresponding calendar event (perhaps by searching a unique ID in the description) and then "Patch Update Event" to adjust its due date.
  • Combine with Other SmythOS Integrations:
    • Use Google Gmail Integration to send customized email notifications or follow-ups related to calendar events created or managed by your agents.
    • Trigger calendar events based on data received from SmythOS database connectors or other third-party API integrations.
    • Update a central dashboard or log file (e.g., using Google Sheets Integration) with details of calendar events managed by your agents for reporting or auditing.

Explore the possibilities, and happy automating!