Google Calendar integration

Back to list of integrations

Use the Google Calendar integration to let agents create, find, update, and delete events and check availability through Action Tools, and to start workflows when calendar events change. Artemis authenticates with OAuth 2.0.

Authentication	Actions	Workflow triggers
OAuth 2.0	9	7

​

Supported actions

Actions are Google Calendar operations that an agent runs as Action Tools during a conversation. You can also run them from an Integration node in a workflow.

Action	Use it to
Add Attendees to Event	Add guests to an existing event.
Create Quick Event	Create an event from a text description.
Create Event	Create an event with full details.
Get all Events	Get the events in a calendar.
Update Event	Change an event’s details.
Delete Event	Delete an event.
Find Busy/Free Periods in Calendar	Find busy periods across calendars.
Get Event by ID	Get an event’s details by its ID.
Custom API Call	Call a Google Calendar API endpoint that the other actions don’t cover.

​

Supported triggers

Triggers start a workflow when an event occurs in Google Calendar.

Trigger	Starts a workflow when
New or Updated Event	An event is created or updated.
New Event	An event is created in a calendar.
Event Ends	An event ends.
Event Start (Time Before)	A set amount of time remains before an event starts, for example as a reminder.
New Event Matching Search	An event that matches a search term is created.
Event Cancelled	An event is canceled or deleted.
New Calendar	A calendar is created or becomes accessible.

​

Prerequisites

• A Google account with access to the calendars that agents use.
• A Google Cloud project with the Google Calendar API enabled, an OAuth consent screen, and an OAuth client ID of type Web application. See Configure the OAuth consent screen and choose scopes.

​

Set up the integration

1. Create a Google OAuth client

   In the Google Cloud console, enable the Google Calendar API, and configure the OAuth consent screen with the calendar.events and calendar.readonly scopes. Create an OAuth client ID of type Web application, add the Callback URL from the Artemis profile form to Authorized redirect URIs, and copy the Client ID and Client Secret.

2. Create the auth profile

   In Integrations, select Google Calendar > Connect. On Project Auth Profiles, select New Profile > Integration Profile > Google Calendar > Continue.

   Field	Value
   Profile Name	A name for the profile, for example Google Calendar - Production
   Usage Mode	Preconfigured (default), JIT (Just-in-Time), or Preflight. With Preconfigured, an admin provides credentials at setup, and users don’t authorize. See Auth profiles.
   Authorization URL, Token URL, Refresh URL	Pre-filled with the Google endpoints. Keep the defaults.
   Scopes	Pre-filled with https://www.googleapis.com/auth/calendar.events and https://www.googleapis.com/auth/calendar.readonly.
   Additional Authorization Parameters	Pre-filled with access_type=offline and prompt=consent, which let Artemis refresh the access token. Keep the defaults.
   Callback URL	Read only. Add it to the OAuth client’s authorized redirect URIs.
   Client ID, Client Secret	From your Google OAuth client.

   Select Create Profile, and complete the Google sign-in and consent when prompted.

3. Create the action tool

   In Tools, open the Actions tab and select Create Tool. Enter a Tool Name and Description, and select Select Integration > Google Calendar > Continue. Select the Action and Auth Profile, set parameter defaults (leave a value empty for the agent to supply at runtime), choose an output mode, and select Create Tool. Then assign the tool to an agent.

​

Action reference

Add Attendees to Event

Adds one or more guests to an existing event.

Parameter	Type	Description
calendar_id	enum	Calendar.
eventId	string	Event ID.
attendees	array	Guest email addresses.

Create Quick Event

Creates an event from a text description, for example Lunch with Priya tomorrow at 1 PM.

Parameter	Type	Description
calendar_id	enum	Calendar.
text	string	Text that describes the event.
send_updates	enum	Guests who receive a notification about the new event.

Create Event

Creates an event with full details.

Parameter	Type	Description
calendar_id	enum	Calendar.
title	string	Event title.
start_date_time	string	Start date and time.
end_date_time	string	End date and time. If empty, the event ends 30 minutes after it starts.
location	string	Event location.
description	string	Event description. Supports HTML tags.
colorId	enum	Event color.
attendees	array	Guest email addresses.
guests_can_modify	boolean	Lets guests modify the event. Default: False.
guests_can_invite_others	boolean	Lets guests invite others. Default: False.
guests_can_see_other_guests	boolean	Lets guests see the guest list. Default: False.
send_notifications	enum	Guests who receive a notification. Default: Yes, to everyone.
create_meet_link	boolean	Adds a Google Meet link to the event. Default: False.

Get all Events

Gets the events in a calendar.

Parameter	Type	Description
calendar_id	enum	Calendar.
event_types	array	Event types to return: Default, Out Of Office, Focus Time, or Working Location.
search	string	Search term.
start_date	string	Start of the date range.
end_date	string	End of the date range.
singleEvents	boolean	Expands recurring events into individual instances and returns only single events and instances. Default: False.

Update Event

Changes an event’s details.

Parameter	Type	Description
calendar_id	enum	Calendar.
eventId	string	Event ID.
title	string	Event title.
start_date_time	string	Start date and time.
end_date_time	string	End date and time.
location	string	Event location.
description	string	Event description. Supports HTML tags.
colorId	enum	Event color.
attendees	array	Guest email addresses.
guests_can_modify	boolean	Lets guests modify the event. Default: False.
guests_can_invite_others	boolean	Lets guests invite others. Default: False.
guests_can_see_other_guests	boolean	Lets guests see the guest list. Default: False.

Delete Event

Deletes an event.

Parameter	Type	Description
calendar_id	enum	Calendar.
eventId	string	Event ID.

Find Busy/Free Periods in Calendar

Finds the busy periods in one or more calendars for a time range.

Parameter	Type	Description
calendar_ids	array	Calendars to check.
start_date	string	Start of the time range.
end_date	string	End of the time range.

Get Event by ID

Gets an event’s details by its ID.

Parameter	Type	Description
calendar_id	enum	Calendar.
event_id	string	Event ID, for example abc123def456. Find it in the event URL or in the output of other calendar actions.
max_attendees	number	Maximum number of attendees to return. If the event has more, the response includes only the participant.
time_zone	string	Time zone for the response, for example America/New_York. Defaults to the calendar’s time zone.

Custom API Call

Sends a request to a Google Calendar API endpoint. Artemis adds the authorization headers from the auth profile.

Parameter	Type	Description
url	object	Endpoint URL.
method	enum	HTTP method.
headers	object	Request headers. Authorization headers are added automatically.
queryParams	object	Query parameters.
body_type	enum	Body type. Default: None.
body	object	Request body.
response_is_binary	boolean	Returns the response as a file. Use for PDFs, images, and other files. Default: False.
failsafe	boolean	Returns a result instead of an error when the request fails.
timeout	number	Timeout, in seconds.
followRedirects	boolean	Follows HTTP redirects. Default: False.

​

Troubleshoot common issues

Issue	Resolution
redirect_uri_mismatch	Add the exact Callback URL from the profile form to the OAuth client’s authorized redirect URIs.
The profile status stays Awaiting authorization	Complete the Google sign-in and consent in the same browser session.
access_denied or Access blocked during sign-in	Add the user as a test user on the OAuth consent screen, or publish the app.
Requests fail after the access token expires	Keep access_type=offline and prompt=consent in Additional Authorization Parameters, and reauthorize the profile.
403 insufficient permissions	Confirm the consent screen includes both Calendar scopes, and reauthorize the profile.
The calendar list is empty	Confirm the authorizing user owns the calendar or has access to it.
Recurring events return as one event	Set singleEvents to True in Get all Events.

Related articles:

• Auth profiles
• Action Tools
• Workflows
• Google Calendar API reference