Google Workspace connector tools

50 min

The Google Workspace connector tools in Optimizely Opal let you read and interact with your Google Docs, Sheets, Slides, and Calendar data directly from Opal Chat, agents, and workflows. This article explains how administrators install and configure the tools in Optimizely Connect Platform (OCP), and how users authenticate to start using them.

Add the Google Workspace Tool for Opal in OCP

Install the Google Workspace Tool for Opal in OCP

In the OCP App Directory, complete the following:

Click Google Workspace Tool for Opal.

Click Install App.

Configure the Google Workspace settings

After installing the Google Workspace app, you must configure it in OCP.

Google Workspace settings

This section is to manage your own OAuth provider and is not common. See Configure instance level Opal OAuth for instructions.

Tool configuration

Expand the Tool Configuration section.

Toggle individual Google Workspace services on or off.

Click Save.

Expand the corresponding permissions sections and toggle individual tools on or off for the services you toggled on. See the Google Workspace connector tools section for a list of tools that each permission enables.

Click Save for each section.

Add to Opal

Expand the Add to Opal section.

Click Add to Opal to register the Google Workspace tools in the corresponding Opal instance.

Authenticate with Google Workspace

After an administrator adds the Google Workspace Tool for Opal in OCP, log in from Opal to access your information. The Google Workspace connector tools use user-level authorization. Each user can only access data they are permitted to view in Google.

To authenticate, complete the following steps in Opal:

Go to Connectors.

(Optional) Select Google from the Provider drop-down list to only display Google apps.

Click Connect for the Google Workspace tools you want to connect to.

After you connect to Google, the Google Workspace connector tools become available in Opal Chat, agents, and workflows.

Google Workspace connector tools

After an administrator adds the Google Workspace Tool in OCP and you log in to Google, the following tools are available in Opal.

Expand a tool to see when to use it, required and optional parameters, and example prompts. If you do not provide a required parameter, Opal prompts you for it.

Gmail

The Gmail tools let you compose, send, and manage emails, organize your inbox with labels, manage contacts, and monitor inbox activity directly from Opal. Use them to draft and send messages, search and thread conversations, keep your contact list up to date, and keep your inbox organized without leaving your current workflow.

Read

Write

Delete

Google Calendar

The Google Calendar tools let you create, retrieve, update, and delete calendar events directly from Opal. Use them to schedule meetings, manage your calendar, and coordinate availability without leaving your current workflow.

Read

Write

When to use

Schedule new meetings, appointments, or events.

Create all-day or multi-day out-of-office entries.

Create an event and immediately add attendees to send invitations.

Create recurring events with specific recurrence rules.

Parameters

startDateTime – Event start date and time. For timed events: RFC3339 format like "2023-12-15T14:00:00-05:00" or "2023-12-15T19:00:00Z". For all-day events: Date-only format like "2026-02-26" (YYYY-MM-DD, no time component).

endDateTime – Event end date and time. For all-day events: Date-only format. End date is exclusive. For a three-day event from the 26th through the 28th, use start="2026-02-26", end="2026-03-01".

summary – Event title or name. Displays as the main event heading in calendar views. Can contain HTML.

(Optional) attendees – Valid email addresses of invitees as a comma-separated string, JSON array string, or single email. Examples: "[email protected]" or "[email protected],[email protected]" or ["[email protected]","[email protected]"]

(Optional) calendarId – Calendar identifier.

(Optional) colorId – Color ID for the event (1-11). Sets the color of the event in calendar views.

(Optional) conferenceData – Conference data for video meetings (for example, Google Meet). Example:

{
  "createRequest": {
    "requestId": "unique-id-123",
    "conferenceSolutionKey": {
      "type": "hangoutsMeet"
    }
  }
}

(Optional) description – Event description or details. Can contain HTML formatting for rich text, links, and styling.

(Optional) eventType – Specifies special event categories. Event type: default, outOfOffice, focusTime, or workingLocation.

(Optional) guestsCanInviteOthers – Whether attendees other than the organizer can invite others to the event. Default: true.

(Optional) guestsCanModify – Whether attendees other than the organizer can modify the event. Default: false.

(Optional) guestsCanSeeOtherGuests – Whether attendees other than the organizer can see who the event's attendees are. Default: true.

(Optional) location – Geographic location as free-form text. Can be address, room name, or virtual meeting link.

(Optional) recurrence – RRULE, EXRULE, RDATE, and EXDATE lines for recurring events as a comma-separated string or JSON array string. Examples: "RRULE:FREQ=WEEKLY;COUNT=10" or ["RRULE:FREQ=WEEKLY;COUNT=10","EXDATE:20240101T120000Z"]

(Optional) reminders – Reminder settings with useDefault (boolean) and optional overrides array. If useDefault is true, calendar default reminders apply. If useDefault is false, specify custom reminders in overrides array. Example:

 {
  "useDefault": false,
  "overrides": [
    {
      "method": "email",
      "minutes": 60
    },
    {
      "method": "popup",
      "minutes": 10
    }
  ]
}

Valid methods – email, popup, and sms.

Minutes range – 0–40320 (four weeks).

(Optional) status – Indicates the event state. Event status: confirmed, tentative, or cancelled.

(Optional) timeZone – Internet Assigned Numbers Authority (IANA) Time Zone Database name (for example, "America/New_York" or "Europe/London"). Applied to both start and end times.

(Optional) visibility – Controls who can see event details. Event visibility: default, public, private, or confidential.

Example prompts

Create a project kickoff meeting tomorrow from 10 AM to 11 AM called "Q3 Planning".

Schedule an all-day out-of-office event for next Friday.

Create a sync with [email protected] on Monday at 3 PM for 30 minutes.

Draft a weekly recurring meeting starting next Tuesday at 9 AM called "Team Sync".

When to use

Reschedule an event to a new date or time.

Add or remove attendees from an existing meeting.

Update the description, location, or title of an existing calendar event.

Convert an all-day event to a timed event (or vice versa).

Parameters

eventId – Unique event identifier. Opaque string between 5-1024 characters, generated by Google Calendar API.

(Optional) attendees – Valid email addresses of invitees as a comma-separated string, JSON array string, or single email. Examples: "[email protected]" or "[email protected],[email protected]" or ["[email protected]","[email protected]"]

(Optional) calendarId – Calendar identifier.

(Optional) description – Event description or details. Can contain HTML formatting for rich text, links, and basic styling.

(Optional) endDateTime – Event end time. Must be after startDateTime. For timed events: RFC3339 format. For all-day events: Date-only format (end date is EXCLUSIVE). Must match startDateTime format (both all-day or both timed).

(Optional) location – Geographic location as free-form text. Can be address, room name, or virtual meeting link.

(Optional) sendUpdates – Notification policy: all (notify all attendees), externalOnly (external attendees only), or none (no notifications).

(Optional) startDateTime – Event start time. For timed events: RFC3339 format like "2023-12-15T14:00:00-05:00" or "2023-12-15T19:00:00Z". For all-day events: Date-only format like "2026-03-04" (YYYY-MM-DD). Can convert between formats (all-day to timed or vice versa).

(Optional) status – Event status: confirmed (default and final), tentative (provisional), cancelled (deleted but visible in incremental sync).

(Optional) summary – Event title and name. Can contain HTML formatting. This is the main event heading shown in calendar views.

(Optional) timeZone – IANA Time Zone Database name (for example, "America/New_York", "Europe/London", "Asia/Tokyo"). Applied to start and end times.

(Optional) visibility – Event visibility: default (calendar default), public (visible to all), private (attendees only), or confidential (legacy private).

Example prompts

Move my 3 PM meeting today to 4 PM instead.

Add [email protected] to the "Q3 Review" event tomorrow.

Rename the "Sync" meeting to "Weekly Project Sync".

Update the location of my 10 AM meeting to "Conference Room B".

Google Docs

The Google Docs tools let you create, read, edit, and format documents directly from Opal. Use them to insert and style content, manage tables, find and replace text, and work with images without leaving your current workflow.

Read

Write

When to use

Remove a specific paragraph or section of text from a document.

Delete content between known start and end coordinates.

Erase unwanted data programmatically from an existing template.

Parameters

documentId – The ID of the document to update

range – The range of content to delete. Deleting text that crosses a paragraph boundary may result in changes to paragraph styles, lists, positioned objects and bookmarks as the two paragraphs are merged. Attempting to delete certain ranges can result in an invalid document structure in which case a 400 bad request error is returned. The range of content to affect (object with segmentId, startIndex, endIndex, tabId properties). Object structure: {"segmentId": string, "startIndex": number, "endIndex": number, "tabId": string} *segmentId* - The ID of the header, footer or footnote the range is in. An empty segment ID signifies the document's body. *startIndex* - REQUIRED. The zero-based start index of this range, in UTF-16 code units. In all current uses, a start index must be provided. This field is an Int32Value in order to accommodate future use cases with open-ended ranges. *endIndex* - REQUIRED. The zero-based end index of this range, exclusive, in UTF-16 code units. In all current uses, an end index must be provided. This field is an Int32Value in order to accommodate future use cases with open-ended ranges. *tabId* - The tab that contains this range. When omitted, the request applies to the first tab. In a document containing a single tab: - If provided, must match the singular tab's ID. - If omitted, the request applies to the singular tab. In a document containing multiple tabs: - If provided, the request applies to the specified tab. - If omitted, the request applies to the first tab in the document. IMPORTANT: This parameter must be provided as a JSON string. Example: '{"segmentId": "", "startIndex": 1, "endIndex": 10, "tabId": "tab1"}'

Example prompts

Delete the text from index 15 to 35 in my document.

Remove the content range from document xyz123 between indices 100 and 150.

Clear the text spanning from character 0 to 50 in document abc456.

Advanced

When to use

Mass update the formatting of a specific word or phrase throughout a document.

Turn all instances of a brand name to bold text.

Highlight or color-code specific key terms within notes.

Parameters

documentId – The ID of the document to update

fields – Comma-separated list of fields to update (for example, bold,foregroundColor). This must match the properties you set in textStyle. Examples:

For bold only – bold.

For bold and red – bold,foregroundColor.

For italic and underline – italic,underline.

For font size – fontSize.

findText – The exact text to search for and update

textStyle – The text style to apply to all found occurrences (JSON string). This parameter must be provided as a JSON string. Example for bold red text:

{
  "bold": true,
  "foregroundColor": {
    "color": {
      "rgbColor": {
        "red": 1.0,
        "green": 0.0,
        "blue": 0.0
      }
    }
  }
}

Common styles:

Bold – {"bold": true}

Italic – {"italic": true}

Underline – {"underline": true}

Red text –

{
"foregroundColor": {
  "color": {
    "rgbColor": {
      "red": 1.0, 
      "green": 0.0, 
      "blue": 0.0
      }
    }
  }
}

Font size 14pt – {"fontSize": {"magnitude": 14, "unit": "PT"}}

(Optional) matchCase – Whether the search should be case-sensitive (default: false)

Example prompts

Find all instances of the word "TODO" and make them bold and red in document abc123.

Make the phrase "Important Note" italicized everywhere it appears in the text.

Change the font size of "Google Docs" to 14pt throughout my proposal document.

When to use

Add a logo or graphic into the flow of text in a document.

Attach an image directly to the end of a section automatically.

Insert a diagram into a report using a known image URI.

Parameters

documentId – The ID of the document to update

uri – The URI of the image to insert

(Optional) endOfSegmentLocation – Insert at the end of a segment (object with segmentId, tabId properties). Object structure: {"segmentId": string, "tabId": string} *segmentId* - The ID of the header, footer or footnote. An empty segment ID signifies the document's body. *tabId* - The tab that the location is in. When omitted, the request is applied to the first tab. In a document containing a single tab: - If provided, must match the singular tab's ID. - If omitted, the request applies to the singular tab. In a document containing multiple tabs: - If provided, the request applies to the specified tab. - If omitted, the request applies to the first tab in the document. (Union field: provide either location OR endOfSegmentLocation, not both) IMPORTANT: This parameter must be provided as a JSON string. Example: '{"segmentId": "", "tabId": "tab1"}'

(Optional) location – The specific location in the document (object with segmentId, index, tabId properties) IMPORTANT: Text must be inserted inside the bounds of an existing Paragraph. For instance, text cannot be inserted at a table's start index (i.e. between the table and its preceding paragraph). The text must be inserted in the preceding paragraph. CRITICAL: If you want to insert at the beginning of the document, DO NOT use index 0. Instead: 1. First call the 'google_docs_get_document' tool to retrieve the document structure 2. Find the first paragraph element in the document body 3. Use that paragraph's startIndex as your insertion point. Object structure: {"segmentId": string, "index": number, "tabId": string} *segmentId* - The ID of the header, footer or footnote the location is in. An empty segment ID signifies the document's body. *index* - REQUIRED. The zero-based index, in UTF-16 code units. The index is relative to the beginning of the segment specified by segmentId. WARNING: Index 0 is typically invalid for insertion - use document retrieval to find valid positions. *tabId* - The tab that the location is in. When omitted, the request is applied to the first tab. In a document containing a single tab: - If provided, must match the singular tab's ID. - If omitted, the request applies to the singular tab. In a document containing multiple tabs: - If provided, the request applies to the specified tab. - If omitted, the request applies to the first tab in the document. (Union field: provide either location OR endOfSegmentLocation, not both) IMPORTANT: This parameter must be provided as a JSON string. Example: '{"segmentId": "", "index": 1, "tabId": "tab1"}'

(Optional) objectSize – The size of an object in the document (object with width/height dimensions). Object structure: { "height": object (Dimension), "width": object (Dimension) } *height* - The height of the object *width* - The width of the object Each Dimension object has the structure: { "magnitude": number, "unit": enum (Unit) } Where Unit can be: UNIT_UNSPECIFIED, PT (points), INCH, MM (millimeters) IMPORTANT: This parameter must be provided as a JSON string. Example: '{"height": {"magnitude": 100, "unit": "PT"}, "width": {"magnitude": 100, "unit": "PT"}}'

Example prompts

Insert the image from url "https://example.com/logo.png" at the end of document abc123.

Place an inline image at index 50 in document xyz789.

Add an image sized 100pt by 100pt to the current document at the specified index.

Google Sheets

The Google Sheets tools let you create, read, update, and format spreadsheet data directly from Opal. Use them to log data, analyze ranges, manage sheets, and automate spreadsheet tasks without leaving your current workflow.

Read

Write

When to use

Add new records to a table or list.

Log new entries such as events and transactions.

Append form responses or survey data.

Parameters

range – The A1 notation range to append to. Use column range for best results. Common patterns:

All columns – Sheet1!A:D (appends to columns A through D).

Full sheet – Sheet1!A:Z (appends across many columns).

Specific columns – Sheet1!B:E (appends to columns B through E).

Named range – DataTable (appends to named range). Use column ranges (A:D) instead of cell ranges (A1:D100).

spreadsheetId – The ID of the spreadsheet to append to.

values – Pipe-delimited values where rows are separated by newlines (\n) and columns by pipes (|). Each row should have the same number of columns as your table. Use empty value between pipes for empty cells.

Single row – John [Doe|[email protected]](mailto:Doe|[email protected])|Active.

Two rows – John [Doe|[email protected]](mailto:Doe|[email protected])|Active\nJane [Smith|[email protected]](mailto:Smith|[email protected])|Pending.

With date and status (three rows) – [John|[email protected]](mailto:John|[email protected])|[2024-11-12|Active\nJane|[email protected]](mailto:2024-11-12|Active\nJane|[email protected])|[2024-11-12|Pending\nBob|[email protected]](mailto:2024-11-12|Pending\nBob|[email protected])|2024-11-13|Active.

With empty cells – [Alice||[email protected]](mailto:Alice||[email protected])\[nBob|Smith|[email protected]](mailto:nBob|Smith|[email protected]) (Alice has no last name).

(Optional) insertDataOption – How data should be inserted. Options:

INSERT_ROWS (default) – Adds new rows after existing data.

OVERWRITE – Overwrites cells starting at append position.

(Optional) valueInputOption – How input data should be interpreted. Options:

USER_ENTERED (default) – Parses input, such as formulas, numbers, and dates.

"2024-11-12" becomes a date, "100" becomes number 100.

RAW – Stores as-is. Everything becomes text.

"2024-11-12" stays as text, "100" becomes text "100".

Example prompts

Append the row "John [Doe|[email protected]](mailto:Doe|[email protected])" to Sheet1!A:B.

Log a new transaction at the end of the ledger table.

Add these three new customer records to the end of my sheet.

Advanced

Delete

Google Slides

The following tools let you create, read, and modify Google Slides presentations programmatically. Use them to automate presentation tasks such as building slide decks from data, updating content across slides, or managing presentation structure. You need a Google account with access to Google Drive to use these tools.

Read

Write

Advanced

Configure instance level Opal OAuth

Configure this only if your organization manages its own OAuth provider. Most administrators can skip this section.

In the OCP App Directory, complete the following steps:

Click the Settings tab of the Google Workspace Tool.

Expand the Google Workspace Settings section.

Toggle Instance level Opal OAuth on if you want to use a custom Google Workspace authentication provider connection.

Enter your Google Workspace Auth Provider ID.

Click Save.

Note

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applicationsTurn generative AI off across Optimizely applications.

Google Workspace connector tools

Add the Google Workspace Tool for Opal in OCP

Install the Google Workspace Tool for Opal in OCP

Configure the Google Workspace settings

Authenticate with Google Workspace

Google Workspace connector tools

Gmail

gmail_get_attachment – Downloads an attachment from a Gmail message.

gmail_get_contact – Retrieves detailed information about a specific contact.

gmail_get_inbox_changes – Monitors recent inbox changes since a specific history ID.

gmail_get_profile – Retrieves the authenticated user's Gmail profile information.

gmail_get_thread – Retrieves all messages in a specific Gmail email thread (conversation).

gmail_list_contacts – Lists all contacts for the authenticated user.

gmail_list_labels – Lists all labels available in the authenticated user's Gmail account.

gmail_create_contact – Creates a new contact in Google Contacts.

gmail_create_draft – Creates a new email draft in Gmail for review before sending.

gmail_create_label – Creates a new label in Gmail for organizing emails.

gmail_organize_emails – Organizes emails by applying or removing labels based on search criteria.

gmail_send_draft – Sends a saved draft email in Gmail.

gmail_send_email – Sends an email message directly from the user's Gmail account.

gmail_update_contact – Updates an existing contact's information in Google Contacts.

gmail_update_draft – Updates an existing email draft in Gmail.

gmail_delete_contact – Deletes a specific contact from the user's Gmail contact list.

gmail_trash_emails – Moves emails matching a search query to the trash in Gmail.

Google Calendar

google_calendar_get_event – Retrieves a specific event from a Google Calendar.

google_calendar_list_calendars – Lists all calendars on the user's calendar list.

google_calendar_list_events – Lists events from a specified Google Calendar.

google_calendar_create_event – Creates a new event in a Google Calendar.

google_calendar_delete_event – Deletes an event from a Google Calendar.

google_calendar_update_event – Updates an existing event in a Google Calendar.

Google Docs

google_docs_find_document_by_name – Search for Google Docs documents by name. Supports both exact and fuzzy matching.

google_docs_get_document – Get a Google Docs document by its ID. Returns the full document structure.

google_docs_list_documents – Get a list of Google Docs documents from your Google Drive. Supports pagination and sorting options.

google_docs_create_document – Create a new Google Docs document with the specified title.

google_docs_delete_content_range – Delete content from the specified range in the document.

google_docs_insert_text – Insert text at the specified location in the document.

google_docs_replace_all_text – Replace all instances of specified text in the document.

google_docs_create_paragraph_bullets – Create bullets for paragraphs in the specified range.

google_docs_delete_paragraph_bullets – Delete bullets from paragraphs in the specified range.

google_docs_delete_positioned_object – Delete a positioned object from the document.

google_docs_delete_table_column – Delete a column from a table.

google_docs_delete_table_row – Delete a row from a table.

google_docs_find_and_update_text_style – Find all occurrences of specific text and update their style.

google_docs_insert_inline_image – Insert an inline image at the specified location.

google_docs_insert_table – Insert a table at the specified location.

google_docs_insert_table_column – Insert a column into a table.

google_docs_insert_table_row – Insert a row into a table.

google_docs_merge_table_cells – Merge cells in a table.

google_docs_replace_image – Replace an existing image with a new image.

google_docs_unmerge_table_cells – Unmerge previously merged cells in a table.

google_docs_update_paragraph_style – Update paragraph style in the specified range.

google_docs_update_table_column_properties – Update properties of columns in a table such as width.

google_docs_update_text_style – Update the text style in the specified range.

Google Sheets

google_sheets_get_spreadsheet – Retrieves detailed information about a specific Google Sheets spreadsheet.

google_sheets_list_spreadsheets – Lists the Google Sheets spreadsheets in your Google Drive.

google_sheets_read_values – Reads values from a specified range in a Google Sheets spreadsheet.

google_sheets_append_values – Appends new rows of data to the end of a table in a Google Sheets spreadsheet.

google_sheets_clear_values – Clears all values from a specified range in a Google Sheets spreadsheet.

google_sheets_create_spreadsheet – Creates a new Google Sheets spreadsheet with optional initial data.

google_sheets_batch_update_values – Updates multiple ranges in a Google Sheets spreadsheet in a single batch request.

google_sheets_add_sheet – Adds a new sheet (tab) to an existing Google Sheets spreadsheet.

google_sheets_append_columns – Appends blank columns to the end of a Google Sheets sheet.

google_sheets_append_rows – Appends blank rows to the end of a Google Sheets sheet.

google_sheets_format_cells – Format cells in a Google Sheets spreadsheet by applying background colors, text colors, or both.

google_sheets_insert_columns – Inserts blank columns at a specific position in a Google Sheets sheet.

google_sheets_insert_rows – Inserts blank rows at a specific position in a Google Sheets sheet.

google_sheets_update_values – Updates values in a specified range of a Google Sheets spreadsheet.

google_sheets_delete_columns – Deletes columns from a Google Sheets sheet.

google_sheets_delete_rows – Deletes rows from a Google Sheets sheet.

google_sheets_delete_spreadsheet – Deletes a Google Sheets spreadsheet permanently.

Google Slides

google_slides_find_presentation_by_name – Search for Google Slides presentations by name in the user's Google Drive.

google_slides_get_presentation – Gets the latest version and complete details of the specified Google Slides presentation.

google_slides_list_presentations – Get a list of Google Slides presentations from your Google Drive with pagination and sorting options.

google_slides_add_text_box – Creates a text box with specified text on a slide in a Google Slides presentation.

google_slides_create_image – Creates an image on a slide from a provided URL.

google_slides_create_presentation – Creates a blank Google Slides presentation with the specified title.