ioLoop Docs

Appearance

$io.google ​

Server API reference.

Functions ​

$io.google.addAttendeesToEvent ​

Add new attendees to an existing event without duplicating existing attendees.

Usage ​

js
$io.google.addAttendeesToEvent(connectionName, calendarId, eventId, newAttendees, notifyAttendees)

Description ​

This function adds new attendees to an existing event in Google Calendar without duplicating any existing attendees.

The system:

  • Fetches the current attendee list
  • Merges in the new attendees, ignoring duplicates based on email address
  • Updates the event with the final attendee list

The 'notifyAttendees' flag controls whether Google Calendar automatically sends email invitations to the newly added participants.

Each attendee can be provided either as:

Usage Scenarios ​

  • Invite additional participants to an already scheduled event
  • Add guests programmatically based on user actions or workflows
  • Expand group meetings without affecting existing invitees

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

calendarId ​

Type: String

Required: Yes

The ID of the calendar containing the event.

eventId ​

Type: String

Required: Yes

The ID of the event to which attendees should be added.

newAttendees ​

Type: Array

Required: Yes

Array of new attendees to add. Each item can be an email string or a structured attendee object.

Example: [ '[email protected]', { email: '[email protected]', displayName: 'Another User', optional: true } ]

notifyAttendees ​

Type: Boolean

Required: No

Optional. If true (default), Google Calendar will send invitations to the added attendees.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the attendees were successfully added
  • 'data': Updated event metadata
  • 'err': If status is false, contains error details

$io.google.addGmailLabelByName ​

Add a Gmail label to a message by label display name.

Usage ​

js
$io.google.addGmailLabelByName(connectionName, messageId, labelName)

Description ​

This function adds a Gmail label to a message using the label's display name.

  • Internally, it uses $io.google.findGmailLabelByName to resolve the label's ID.
  • Then it applies that label to the message via $io.google.updateGmailMessage.

The label name match is case-insensitive.

If the label is not found, the function returns an error.

Usage Scenarios ​

  • Tag a message with a user-facing label such as 'Follow Up' or 'Leads'
  • Support UI workflows where users choose labels by name
  • Avoid needing to know the internal Gmail label ID

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

messageId ​

Type: String

Required: Yes

The Gmail message ID to apply the label to.

labelName ​

Type: String

Required: Yes

The display name of the Gmail label to apply (e.g., 'INBOX', 'Important', 'Leads').

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the label was successfully applied
  • 'data': Gmail's updated message metadata
  • 'err': If status is false, contains error info (e.g., label not found)

$io.google.addGmailThreadLabelByName ​

Add a Gmail label to a thread by its name.

Usage ​

js
$io.google.addGmailThreadLabelByName(connectionName, threadId, labelName)

Description ​

This function adds a Gmail label to a thread by its name.

The label name is case-insensitive. If the label does not exist, the function returns an error.

Internally, this resolves the label ID using $io.google.findGmailLabelByName and then calls $io.google.updateGmailThread.

Usage Scenarios ​

  • Tagging a conversation with a custom label
  • Organizing threads by project or priority
  • Adding workflow-specific labels like 'Follow Up' or 'Escalated'

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

threadId ​

Type: String

Required: Yes

The Gmail thread ID to update.

labelName ​

Type: String

Required: Yes

The name of the Gmail label to add to the thread.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if successful
  • data: Gmail thread object with updated labelIds
  • err: Error details if failed

$io.google.addSheetColumn ​

Insert a new column into a Google Sheets tab and set its header name.

Usage ​

js
$io.google.addSheetColumn(connectionName, fileId, sheetName, columnName, index)

Description ​

This function inserts a new column into the specified sheet tab within a Google Sheets file. The new column will be added at the specified zero-based index, or appended at the end if index is not provided. The first row of the new column will be set to the specified columnName, effectively naming the column in the header.

If a column already exists at the target index, this operation will shift existing columns to the right.

Usage Scenarios ​

  • Add a new data field to an existing sheet for user input or automation
  • Dynamically modify sheet structure to support new workflows
  • Programmatically manage headers in structured spreadsheet templates

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authenticated Sheets API access.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file containing the target sheet.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab to modify.

columnName ​

Type: String

Required: Yes

The name to set in the header row for the new column (placed in row 1).

index ​

Type: Number

Required: No

Optional. Zero-based index where the column should be inserted. If omitted, the column will be added at the end.

Output ​

Type: Promise

Returns a Promise resolving to an object containing the result of the operation:

  • status: true if the column was successfully inserted and labeled
  • data: An object with:
    • columnIndex (Number): The index at which the column was inserted
    • headerCell (String): A1 notation of the cell where the header was set (e.g., 'Sheet1!C1')
  • err: If status is false, this contains error details as a string

$io.google.addSheetRows ​

Insert one or more rows into a Google Sheets tab at a specified position or at the bottom.

Usage ​

js
$io.google.addSheetRows(connectionName, fileId, sheetName, rows, insertAtIndex)

Description ​

This function inserts one or more rows into a sheet tab within a Google Sheets file. By default, rows are appended to the end of the existing data. To insert at a specific position (e.g., below the header), pass a 1-based insertAtIndex.

Each row must be an array of values matching the expected columns in the sheet. If a row is shorter than the existing column count, the remaining cells will be left blank.

Usage Scenarios ​

  • Append new data entries to the bottom of a sheet
  • Insert records programmatically at the top or a specific position
  • Build automations that log events or submissions into structured rows

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate with the Sheets API.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file that contains the target sheet tab.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab where the rows will be inserted.

rows ​

Type: Array

Required: Yes

An array of row arrays to insert. Each row is an array of cell values.

Example:

js
[
  ['Sundar', 'Pichai', 'Mountain View', 'CA', 'USA'],
  ['Satya', 'Nadella', 'Redmond', 'WA', 'USA']
]

insertAtIndex ​

Type: Number

Required: No

Optional. The 1-based row index where new rows should be inserted. Defaults to appending at the bottom.

Output ​

Type: Promise

Returns a Promise resolving to an object describing the result of the insertion:

  • If appending:
    • data contains Google's standard append response including:
      • spreadsheetId (String)
      • tableRange (String)
      • updates.updatedRange (String) — A1 range of inserted values
  • If inserting at a specific index:
    • data contains:
      • insertedAt (Number): The index where rows were inserted
      • numRows (Number): Number of rows inserted
  • status: true if the rows were inserted successfully
  • err: If status is false, contains error details

$io.google.apiRawRequest ​

Make an authenticated raw HTTP request to a Google API using the saved OAuth2 access token.

Usage ​

js
$io.google.apiRawRequest(connectionName, url, httpMethod, queryParams, body, expectedResponseType)

Description ​

This function issues a raw HTTP request to a specified Google API endpoint using the saved access token obtained via OAuth2.

It supports common HTTP methods (GET, POST, PUT, PATCH) and handles response decoding for JSON, text, and binary responses.

  • The Authorization header is automatically included
  • JSON body content is automatically stringified and sent with Content-Type: application/json
  • Binary responses are returned as Node.js Buffers

The function is useful when you need to access a Google API that is not yet wrapped by a higher-level function.

Examples:

  • GET a file metadata from Drive API
  • POST a query to BigQuery API
  • Fetch raw binary content from a Google endpoint

Usage Scenarios ​

  • Call less commonly used or unsupported Google APIs directly
  • Download or upload binary content using OAuth2 credentials
  • Test custom Google API endpoints with GET, POST, PUT, or PATCH methods

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the request.

url ​

Type: String

Required: Yes

The full URL to call (must be a Google API endpoint).

httpMethod ​

Type: String

Required: Yes

HTTP method to use (e.g., 'GET', 'POST', 'PUT', 'PATCH').

queryParams ​

Type: Object

Required: No

Optional. Key-value pairs to be sent as URL query parameters.

body ​

Type: Object | null

Required: No

Optional. Request body (usually for POST/PUT/PATCH). Automatically stringified as JSON.

expectedResponseType ​

Type: 'json' | 'text' | 'binary'

Required: No

Optional. Expected response type. Defaults to 'json'. If set to 'binary', returns a Buffer.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the request was successful
  • 'data': The decoded response data (object, string, or Buffer depending on response type)
  • 'err': If status is false, contains error details

$io.google.appendTextToDoc ​

Append text to the end of a Google Docs document, optionally inserting a new line before the text.

Usage ​

js
$io.google.appendTextToDoc(connectionName, documentId, text, newLine)

Description ​

This function appends text to the end of a Google Docs document.

It fetches the document structure to find the last available insertion point, and inserts the given text. If newLine is true (default), a newline character (\n) is inserted before the appended text for better formatting.

This allows programmatically extending documents without overwriting existing content.

Usage Scenarios ​

  • Log events or messages to a shared document
  • Programmatically extend a document with user notes or system outputs
  • Add summary sections or footnotes to generated reports

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Docs API call.

documentId ​

Type: String

Required: Yes

The ID of the Google Docs document to append text to.

text ​

Type: String

Required: Yes

The text content to append to the document.

newLine ​

Type: Boolean

Required: No

Optional. If true, inserts a new line (\n) before the appended text. Defaults to true.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the text was successfully appended
  • err: If status is false, contains error details

$io.google.archiveGmailMessage ​

Archive a Gmail message by removing it from the inbox.

Usage ​

js
$io.google.archiveGmailMessage(connectionName, messageId)

Description ​

This function archives a Gmail message by removing the 'INBOX' label.

It uses $io.google.updateGmailMessage internally with the { archive: true } flag.

The message is still retrievable in Gmail (e.g., via All Mail or search), but no longer appears in the inbox.

Usage Scenarios ​

  • Programmatically archive incoming or processed emails
  • Support user-triggered archive actions in a custom Gmail interface
  • Clean up inbox while preserving message in Gmail storage

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

messageId ​

Type: String

Required: Yes

The ID of the Gmail message to archive.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the message was successfully archived
  • 'data': Gmail's updated message metadata
  • 'err': If status is false, contains error details

$io.google.archiveGmailThread ​

Archive a Gmail thread by removing it from the inbox.

Usage ​

js
$io.google.archiveGmailThread(connectionName, threadId)

Description ​

This function archives a Gmail thread by removing the 'INBOX' label.

The thread is still accessible in Gmail (e.g., via All Mail or search) but no longer appears in the inbox.

It uses $io.google.updateGmailThread internally with the { archive: true } flag.

Usage Scenarios ​

  • Clean up inbox without deleting the thread
  • Programmatically archive processed conversations
  • Support user-triggered archive actions in a custom Gmail interface

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

threadId ​

Type: String

Required: Yes

The Gmail thread ID to archive.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the thread was archived successfully
  • data: Gmail thread object with updated labelIds
  • err: Error details if failed

$io.google.clearSheetRows ​

Clear the contents of specific rows in a Google Sheets tab, leaving the row structure intact.

Usage ​

js
$io.google.clearSheetRows(connectionName, fileId, sheetName, rowIndexes)

Description ​

This function clears the contents of specific rows in a Google Sheets sheet tab. It does not delete the rows — it simply removes the values from the specified rows across all columns (based on header width).

Internally, the function determines the number of columns by inspecting the first row of the sheet. Rows are cleared using the Sheets API's values.clear method.

Usage Scenarios ​

  • Reset rows while keeping sheet formatting and formulas intact
  • Clear data from form submissions or temporary rows
  • Erase outdated or invalid content without shifting other data

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Sheets API call.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file containing the sheet to modify.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab where rows will be cleared.

rowIndexes ​

Type: Array

Required: Yes

An array of zero-based row indexes to clear. Duplicates will be ignored and rows will be processed in ascending order.

Example:

js
[1, 3, 5]  // Clears rows 2, 4, and 6

Output ​

Type: Promise

Returns a Promise that resolves to an object summarizing the result:

  • status: true if all specified rows were successfully cleared
  • data: { cleared: Number } — number of unique rows cleared
  • err: If status is false, contains error details

$io.google.copyDriveFile ​

Copy a file in Google Drive with optional renaming, relocation, and format conversion.

Usage ​

js
$io.google.copyDriveFile(connectionName, fileId, newFileName, destFolderId, convertToDoc)

Description ​

This function creates a copy of a file in Google Drive.

  • If newFileName is provided, the copy will be renamed.
  • If destFolderId is specified, the file will be placed in that folder.
  • If convertToDoc is true, the file will be converted into a Google Docs-compatible format (e.g., Word → Google Docs).

This is useful for template-based workflows, content generation, or processing user uploads.

Usage Scenarios ​

  • Create a duplicate of a spreadsheet or document template
  • Move a file into a specific folder during onboarding or workflow
  • Convert an uploaded file (e.g., .docx or .pdf) into Google Docs format

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication via the Drive API.

fileId ​

Type: String

Required: Yes

The ID of the existing Drive file to copy.

newFileName ​

Type: String

Required: No

Optional. A new name for the copied file. If omitted, the original file name is retained.

destFolderId ​

Type: String

Required: No

Optional. The ID of the Drive folder where the copied file will be placed. If omitted, the file remains in the current location.

convertToDoc ​

Type: Boolean

Required: No

Optional. If true, attempts to convert the copied file into Google Docs format (e.g., Word → Docs, PDF → Docs). Defaults to false.

Output ​

Type: Promise

Returns a Promise that resolves to an object with the result:

  • status: true if the file was copied successfully
  • data: Metadata about the new file (e.g., ID, name, mimeType)
  • err: If status is false, contains error information

$io.google.copyWorksheet ​

Copy a sheet tab from one Google Sheets file to another, optionally renaming it.

Usage ​

js
$io.google.copyWorksheet(connectionName, fileId, sheetName, destinationFileId, newSheetName)

Description ​

This function copies an existing worksheet (sheet tab) from one Google Sheets file to another. You must specify the source file ID, the sheet name to copy, and the destination file ID.

If destinationFileId is the same as fileId, the worksheet is duplicated within the same file.

If newSheetName is provided, the copied sheet will be renamed in the destination file.

Usage Scenarios ​

  • Duplicate a worksheet into a template or report workbook
  • Copy a tab from one user's file into another's for consolidation
  • Back up a specific sheet tab into another file (even the same file)

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Sheets API call.

fileId ​

Type: String

Required: Yes

The ID of the source Google Sheets file containing the sheet to be copied.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab to copy from the source file.

destinationFileId ​

Type: String

Required: Yes

The ID of the destination Google Sheets file where the sheet will be copied. May be the same as fileId.

newSheetName ​

Type: String

Required: No

Optional. If provided, renames the copied sheet tab in the destination file.

Output ​

Type: Promise

Returns a Promise resolving to an object indicating the result of the copy operation:

  • status: true if the copy succeeded, false otherwise
  • data: If successful, contains metadata returned by the Sheets API for the new sheet (e.g., sheetId, title)
  • err: If status is false, contains error information

$io.google.createCalendarEvent ​

Create a new event in a specified Google Calendar, with support for attendees and notifications.

Usage ​

js
$io.google.createCalendarEvent(connectionName, calendarId, startDateTime, endDateTime, title, description, attendees, notifyAttendees, other)

Description ​

This function creates a new event in a specified Google Calendar.

It allows specifying the event's start and end times, title, description, optional attendees, and whether or not to notify attendees via email.

You can also pass an other object to provide additional fields as per the Google Calendar API Events resource — such as location, recurrence, colorId, etc.

Attendees must be an array of email addresses or full attendee objects.

To automatically generate a Google Meet link, pass { addMeet: true } in the other object.

Usage Scenarios ​

  • Add scheduled meetings, appointments, or reminders to a user's calendar
  • Create shared events with participant invitations
  • Automate event creation for bookings, classes, or tasks

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Calendar API call.

calendarId ​

Type: String

Required: Yes

The ID of the calendar where the event will be created.

startDateTime ​

Type: String | Date | moment

Required: Yes

The event start time. Accepts an ISO 8601 string, a JavaScript Date object, or a moment instance. Internally converted to ISO format.

endDateTime ​

Type: String | Date | moment

Required: Yes

The event end time. Accepts an ISO 8601 string, a JavaScript Date object, or a moment instance. Internally converted to ISO format.

title ​

Type: String

Required: Yes

Title of the event.

description ​

Type: String

Required: Yes

Optional. Detailed description of the event.

attendees ​

Type: Array

Required: No

Optional. Array of email addresses or attendee objects to invite.

Each attendee object can include fields like: [ '[email protected]', { email: '[email protected]', displayName: 'John Doe', optional: true } ]

notifyAttendees ​

Type: Boolean

Required: No

Optional. If true (default), sends email invitations to attendees.

other ​

Type: Object

Required: No

Optional. Additional fields as per the Google Calendar API Events resource. To add a Google Meet link, set addMeet: true.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the event was created successfully
  • data: Full event metadata (including ID, summary, start/end, etc.)
  • err: If status is false, contains error information

$io.google.createDocFromTemplate ​

Create a Google Doc from a template by replacing text, image, and table placeholders.

Usage ​

js
$io.google.createDocFromTemplate(connectionName, templateFileId, placeholders, newFileName, destFolderId)

Description ​

This function creates a new Google Docs file by copying an existing template and replacing placeholders.

Supported placeholder types:

  • Text placeholders: replaced with string values.
  • Image placeholders: replaced with inline images (by URL), with optional width and height.
  • Table placeholders: replaced by inserting a structured table of text data.

Placeholders must be wrapped in double curly braces (e.g., ) in the template document.

The new file can optionally be renamed and placed into a specific Drive folder.

Usage Scenarios ​

  • Generate dynamic documents such as invoices, certificates, or contracts
  • Fill a template with user-specific or transaction-specific data
  • Automate complex document generation with text, images, and tables

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication via Drive and Docs APIs.

templateFileId ​

Type: String

Required: Yes

The ID of the template Google Docs file to copy and populate.

placeholders ​

Type: Object

Required: Yes

An object defining placeholder replacements. Example:

js
{
  Name: 'Alice Smith',
  ProfilePic: { type: 'image', url: 'https://example.com/photo.jpg', width: 100, height: 100 },
  InvoiceTable: { type: 'table', rows: [['Item', 'Qty', 'Price'], ['Widget', '2', '$20']] }
}

newFileName ​

Type: String

Required: No

Optional. New name for the created document. If omitted, uses the same name as the template.

destFolderId ​

Type: String

Required: No

Optional. Destination folder ID to place the created document into. Defaults to user's root folder if omitted.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the document was successfully created and populated
  • data: { fileId: String } — ID of the newly created document
  • err: If status is false, contains error details

$io.google.createDriveFolder ​

Create a new folder in Google Drive, optionally under a parent and with uniqueness control.

Usage ​

js
$io.google.createDriveFolder(connectionName, folderName, parentFolderId, ensureUnique)

Description ​

This function creates a new folder in Google Drive.

  • If parentFolderId is provided, the new folder is created inside that parent.
  • If ensureUnique = false, the function first searches for a folder with the same name in the target location and returns it if found.
  • If ensureUnique = true, the folder is always created fresh (even if a duplicate already exists).

The folder is created using Drive API with mimeType = 'application/vnd.google-apps.folder'.

Usage Scenarios ​

  • Generate a folder structure for projects, users, or workflows
  • Prevent duplicate folders with the same name under a parent
  • Create nested folder trees in a team or shared drive

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Drive API call.

folderName ​

Type: String

Required: Yes

The name of the folder to create.

parentFolderId ​

Type: String

Required: No

Optional. The ID of the parent folder under which to create the new folder. If omitted, the folder is created at the root.

ensureUnique ​

Type: Boolean

Required: No

Optional. If false, checks for an existing folder with the same name and returns it if found. Defaults to true (always create new).

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if a folder was created or found
  • data: Folder metadata including id, name, and parents
  • err: If status is false, contains error information

$io.google.createGmailLabel ​

Create a new user-defined Gmail label with optional display and color options.

Usage ​

js
$io.google.createGmailLabel(connectionName, name, options)

Description ​

This function creates a new user-defined Gmail label.

Optional settings include:

  • labelListVisibility: Controls visibility in the Gmail sidebar. Default is 'labelShow'. Other values: 'labelHide'
  • messageListVisibility: Controls whether messages with this label appear in the inbox list. Default is 'show'. Other values: 'hide'
  • color: Optional object with label colors. If provided, must include:
    • backgroundColor: Hex color string (e.g., '#3366CC')
    • textColor: Hex color string (e.g., '#FFFFFF')

Note: Gmail does not allow duplicate label names. If the label already exists, this function will return an error.

Usage Scenarios ​

  • Create custom categories for automated email processing
  • Allow users to define folders/tags in your app
  • Pre-create expected labels for workflows

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

name ​

Type: String

Required: Yes

The display name of the Gmail label to create (must be unique).

options ​

Type: Object

Required: No

Optional. Display and color settings for the label.

Example: { labelListVisibility: 'labelShow', messageListVisibility: 'show', color: { backgroundColor: '#4285F4', textColor: '#FFFFFF' } }

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the label was successfully created
  • data: The full label metadata returned by Gmail
  • err: If status is false, contains error details (e.g., label name conflict)

$io.google.createSpreadsheet ​

Create a new Google Sheets file, optionally copying from another file and customizing its sheet, headers, and folder.

Usage ​

js
$io.google.createSpreadsheet(connectionName, title, copyFromFileId, headers, sheetName, parentFolder)

Description ​

This function creates a new Google Sheets file.

  • If copyFromFileId is provided, the spreadsheet is created by copying that file. In this mode, headers and sheetName are ignored.
  • Otherwise, an empty spreadsheet is created with an optional sheet name and optional header row.
  • If parentFolder is specified, the created spreadsheet is placed into that Google Drive folder.

Note: When copying from another file, setting headers is not allowed.

Usage Scenarios ​

  • Create a blank or pre-filled spreadsheet for reporting, logs, or templates
  • Copy an existing spreadsheet and place it in a specific Drive folder
  • Initialize a new sheet with a specific tab name and header row

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate API requests.

title ​

Type: String

Required: Yes

The title to assign to the new spreadsheet file.

copyFromFileId ​

Type: String

Required: No

Optional. If provided, creates the new spreadsheet by copying this file. Cannot be used with headers or sheetName.

headers ​

Type: Array

Required: No

Optional. A list of strings to use as headers in row 1 of the sheet. Example:

js
['Name', 'Email', 'Location']

sheetName ​

Type: String

Required: No

Optional. Name of the first sheet tab to create. Defaults to 'Sheet1' if not specified.

parentFolder ​

Type: String

Required: No

Optional. The ID of a Google Drive folder to place the new spreadsheet into.

Output ​

Type: Promise

Returns a Promise resolving to an object indicating the outcome:

  • status: true if the spreadsheet was created successfully
  • data: { fileId: String } — the ID of the new spreadsheet
  • err: If status is false, contains error details

$io.google.createTextFile ​

Create a new plain text file in Google Drive, optionally converting it to Google Docs.

Usage ​

js
$io.google.createTextFile(connectionName, text, fileName, destFolderId, convertToDoc)

Description ​

This function creates a new text file in Google Drive using a string input.

The text is converted into a readable stream and uploaded as a plain text file (text/plain MIME type). If convertToDoc is true, the file is converted to Google Docs format during upload.

The new file can optionally be placed into a specified Drive folder.

Usage Scenarios ​

  • Generate logs, summaries, or exports as text documents
  • Store structured or unstructured text content in Drive programmatically
  • Create and convert notes or markdown into editable Google Docs

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

text ​

Type: String

Required: Yes

The full text content to be uploaded as a file.

fileName ​

Type: String

Required: Yes

The name of the file to create in Google Drive (e.g., 'log.txt').

destFolderId ​

Type: String

Required: No

Optional. The ID of a folder where the file should be placed. Defaults to Drive root if omitted.

convertToDoc ​

Type: Boolean

Required: No

Optional. If true, the uploaded text will be converted to Google Docs format.

Output ​

Type: Promise

Returns a Promise that resolves to an object describing the outcome:

  • status: true if the file was successfully created
  • data: Metadata about the new file (e.g., id, name, mimeType)
  • err: If status is false, contains error information

$io.google.createWorksheet ​

Create a new sheet tab within a Google Sheets file, optionally setting headers and overwriting if it exists.

Usage ​

js
$io.google.createWorksheet(connectionName, fileId, sheetName, headers, overwrite)

Description ​

This function creates a new sheet tab (worksheet) within an existing Google Sheets file. If a sheet with the specified name already exists:

  • If overwrite is true, the existing sheet is deleted before creating a new one.
  • If overwrite is false, the operation fails with an error.

If a headers array is provided, it is written to the first row of the new sheet as column headers.

Usage Scenarios ​

  • Create a new tab for storing fresh data or generating a report
  • Initialize a new worksheet with specific column headers
  • Reset a sheet by deleting and recreating it if it already exists

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file in which to create the new sheet tab.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab to create. Must be unique unless overwriting.

headers ​

Type: Array

Required: No

Optional. An array of strings to set as headers in the first row of the sheet. Example:

js
['First Name', 'Last Name', 'City', 'State', 'Country']

overwrite ​

Type: Boolean

Required: No

Optional. If true, deletes the existing sheet with the same name before creating the new one. Defaults to false.

Output ​

Type: Promise

Returns a Promise resolving to an object describing the result:

  • status: true if the sheet was successfully created (or recreated), false otherwise
  • data: If successful, contains:
    • sheetId (Number): Internal ID of the new sheet tab
    • sheetName (String): The name of the sheet created
  • err: If status is false, contains error information as a string

$io.google.deleteCalendarEvent ​

Delete an event from a Google Calendar, optionally notifying attendees.

Usage ​

js
$io.google.deleteCalendarEvent(connectionName, calendarId, eventId, notifyAttendees)

Description ​

This function deletes a specific event from a Google Calendar by ID.

You can optionally control whether attendees are notified of the cancellation using the 'notifyAttendees' flag.

A successful deletion usually returns a 204 No Content response from the API.

Usage Scenarios ​

  • Cancel meetings or appointments programmatically
  • Allow users to delete events they created or own
  • Clean up temporary or outdated scheduled events

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

calendarId ​

Type: String

Required: Yes

The ID of the calendar containing the event to delete.

eventId ​

Type: String

Required: Yes

The ID of the event to delete.

notifyAttendees ​

Type: Boolean

Required: No

Optional. If true (default), Google Calendar will notify attendees that the event was canceled. If false, no notifications are sent.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the event was successfully deleted
  • 'data': Always null on successful deletion
  • 'err': If status is false, contains error information

$io.google.deleteDriveFile ​

Move a file or folder in Google Drive to the trash (soft delete).

Usage ​

js
$io.google.deleteDriveFile(connectionName, fileId)

Description ​

This function moves a file or folder to the trash in Google Drive.

It performs a soft delete by setting the trashed property of the file to true. Files moved to the trash can be recovered manually from Drive or permanently deleted later.

Usage Scenarios ​

  • Soft-delete outdated files while retaining the ability to recover them
  • Clean up temporary or generated files after processing
  • Manage lifecycle of Drive files by trashing instead of immediate permanent deletion

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Drive API request.

fileId ​

Type: String

Required: Yes

The ID of the file or folder to move to trash.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the file was successfully moved to trash
  • data: File metadata including:
    • id: File ID
    • name: File name
    • trashed: true
  • err: If status is false, contains error information

$io.google.deleteGmailMessage ​

Move a Gmail message to Trash (soft delete).

Usage ​

js
$io.google.deleteGmailMessage(connectionName, messageId)

Description ​

This function moves a Gmail message to Trash by applying the 'TRASH' label.

It is a wrapper around $io.google.updateGmailMessage, using the { trash: true } flag.

Note: This is a soft-delete — the message remains in the Trash label until purged by Gmail or the user.

Usage Scenarios ​

  • Soft-delete a message from inbox or other folders
  • Support user-facing delete actions from custom Gmail clients
  • Build cleanup workflows or bulk message removers

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

messageId ​

Type: String

Required: Yes

The ID of the Gmail message to move to Trash.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the message was successfully marked as trashed
  • 'data': Gmail's updated message metadata
  • 'err': If status is false, contains error information

$io.google.deleteGmailThread ​

Move a Gmail thread to Trash.

Usage ​

js
$io.google.deleteGmailThread(connectionName, threadId)

Description ​

This function deletes a Gmail thread by adding the built-in Gmail label 'TRASH'.

The thread will be moved to the Trash folder in Gmail and will be permanently deleted after 30 days unless recovered.

Internally, this uses $io.google.updateGmailThread with the addLabelIds: ['TRASH'] operation.

Usage Scenarios ​

  • Programmatically delete unwanted or processed conversations
  • Support user actions like 'Delete Thread' in a custom email client
  • Clear out old threads during periodic cleanup

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

threadId ​

Type: String

Required: Yes

The ID of the Gmail thread to delete.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the thread was moved to Trash successfully
  • data: Gmail thread object with updated labelIds
  • err: Error details if failed

$io.google.deleteSheetRows ​

Delete one or more row blocks from a Google Sheets tab using index-based ranges.

Usage ​

js
$io.google.deleteSheetRows(connectionName, fileId, sheetName, ranges)

Description ​

This function deletes one or more groups of rows from a sheet tab in a Google Sheets file. Each range must specify a zero-based startRowIndex and the number of rows to delete via numRows.

Multiple ranges can be provided in a single call. All deletions are performed using a Sheets API batchUpdate.

Usage Scenarios ​

  • Remove stale or incorrect data from structured sheets
  • Delete rows added by mistake or automation cleanups
  • Programmatically prune sections of data after processing

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file containing the target sheet.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab where rows should be deleted.

ranges ​

Type: Array

Required: Yes

An array of range objects specifying rows to delete. Each object must have:

js
[
  { startRowIndex: 2, numRows: 3 },  // deletes rows 3–5 (zero-based index)
  { startRowIndex: 10, numRows: 1 }  // deletes row 11
]

Output ​

Type: Promise

Returns a Promise resolving to an object summarizing the operation:

  • status: true if all row deletions were successfully applied
  • data: { deleted: Number } — the number of ranges processed
  • err: If status is false, contains error details

$io.google.downloadDriveFile ​

Download the raw content of a non-Google-Docs file stored in Google Drive as a readable stream.

Usage ​

js
$io.google.downloadDriveFile(connectionName, fileId)

Description ​

This function downloads the raw binary content of a non-Google-Docs-native file stored in Google Drive.

Files such as uploaded PDFs, images, ZIP files, spreadsheets (not Sheets), and videos can be retrieved directly using this method.

Files created as Google Docs (e.g., Google Docs, Sheets, Slides) must be downloaded using $io.google.exportGoogleFile.

The downloaded content is returned as a Node.js readable stream, allowing efficient processing without loading the full file into memory.

Usage Scenarios ​

  • Fetch binary file contents (e.g., PDFs, images, uploads) for saving, processing, or serving to a client
  • Backup or replicate non-Google-native files from Drive
  • Stream file downloads without loading full files into memory

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the download request.

fileId ​

Type: String

Required: Yes

The ID of the Google Drive file to download.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the file was successfully retrieved
  • data: A readable stream representing the file content
  • err: If status is false, contains error details

$io.google.exportGoogleFile ​

Export a Google Docs-native file (Doc, Sheet, Slide) into a downloadable format such as PDF or DOCX.

Usage ​

js
$io.google.exportGoogleFile(connectionName, fileId, mimeType)

Description ​

This function exports a Google-native file (e.g., Google Docs, Google Sheets, Google Slides) into a different MIME type.

Use this function to download Google Drive files that cannot be directly downloaded using $io.google.downloadDriveFile.

By default, the export is done in PDF format, but you can specify other formats such as application/vnd.openxmlformats-officedocument.wordprocessingml.document (DOCX) or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (XLSX).

The exported content is returned as a Node.js readable stream.

Usage Scenarios ​

  • Download a Google Doc as a PDF for offline storage
  • Export a Google Sheet into Excel format (XLSX)
  • Generate downloadable reports from Google Slides or Docs

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

fileId ​

Type: String

Required: Yes

The ID of the Google Docs-native file to export.

mimeType ​

Type: String

Required: No

Optional. The MIME type to export the file into. Defaults to application/pdf.

Examples:

  • For Docs to PDF: application/pdf
  • For Docs to Word: application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • For Sheets to Excel: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the export succeeded
  • data: A readable stream of the exported content
  • err: If status is false, contains error information

$io.google.exportGoogleFileToDrive ​

Export a Google-native file to a downloadable format and save it back into Drive as a static file.

Usage ​

js
$io.google.exportGoogleFileToDrive(connectionName, fileId, newFileName, destFolderId, mimeType)

Description ​

This function exports a Google-native file (e.g., Google Doc, Sheet, Slide) into a specified format (default: PDF), and immediately saves the exported result as a new static file back into Drive.

The resulting file is independent of Google Docs and can be shared, downloaded, or archived as a regular file.

Internally, it combines:

  • $io.google.exportGoogleFile to export the file
  • $io.google.saveDriveFile to upload it back to Drive

Usage Scenarios ​

  • Convert Google Docs into PDFs and save them automatically
  • Export Sheets into Excel files for external sharing
  • Create immutable snapshots of Google Docs at a point in time

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

fileId ​

Type: String

Required: Yes

The ID of the Google Docs-native file to export.

newFileName ​

Type: String

Required: Yes

The name for the new saved file in Drive (e.g., 'Invoice.pdf').

destFolderId ​

Type: String

Required: No

Optional. The ID of the Drive folder where the exported file should be saved. Defaults to the user's root folder if omitted.

mimeType ​

Type: String

Required: No

Optional. The MIME type to export into. Defaults to application/pdf.

Examples:

  • application/pdf
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document (for Word format)

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the file was successfully exported and saved
  • data: Metadata of the newly saved static file (e.g., id, name, mimeType)
  • err: If status is false, contains error details

$io.google.findCalendarByName ​

Find a calendar by its display name (summary) in the user's list of accessible calendars.

Usage ​

js
$io.google.findCalendarByName(connectionName, name)

Description ​

This function searches the user's accessible calendars for a calendar with a matching name.

The comparison is case-insensitive and matches the calendar's summary property.

If a match is found, the full calendar metadata object is returned. Otherwise, an error is returned.

Usage Scenarios ​

  • Look up a calendar by name to retrieve its ID before creating or searching for events
  • Validate that a specific calendar exists before proceeding with an operation
  • Support user-friendly calendar selection by matching display names

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Calendar API request.

name ​

Type: String

Required: Yes

The name (summary) of the calendar to find. Comparison is case-insensitive.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if a calendar with the given name was found
  • data: Metadata object of the found calendar (e.g., id, summary, timeZone, etc.)
  • err: If status is false, contains an error message (e.g., calendar not found)

$io.google.findGmailLabelByName ​

Find a Gmail label by its display name (case-insensitive).

Usage ​

js
$io.google.findGmailLabelByName(connectionName, labelName)

Description ​

This function searches the user's Gmail labels and returns the metadata for the one with a matching display name.

The comparison is case-insensitive and uses the 'name' property of each label.

This is often used to obtain the 'id' of a label for use in Gmail watchers or search filters.

Usage Scenarios ​

  • Resolve a label's ID by its user-visible name before setting up filters or watchers
  • Validate that a specific Gmail label exists
  • Support label name entry in user-facing settings or forms

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

labelName ​

Type: String

Required: Yes

The display name of the label to find (e.g., 'INBOX', 'Work', 'Leads').

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the label was found
  • 'data': The label object with fields such as 'id', 'name', and 'type'
  • 'err': If status is false, contains an error message (e.g., label not found)

$io.google.findRowInData ​

Search tabular sheet data using a header-aware match on column values.

Usage ​

js
$io.google.findRowInData(connectionName, data, criteria, matchMultiple)

Description ​

This function searches tabular sheet data using column names from the first row (header) to match row values.

It performs exact (===) matches for each key-value pair provided in the criteria object. If matchMultiple is true, all matching rows are returned. Otherwise, only the first match is returned.

Header values must match exactly (case-sensitive), and all required columns must be present in the data.

Usage Scenarios ​

  • Find a specific row based on column values (e.g., Email = '[email protected]')
  • Retrieve all rows that match a given criteria for reporting or processing
  • Use after readSheetData to filter results before taking action

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection. (Not used in logic, but included for consistency and logging.)

data ​

Type: Array

Required: Yes

A 2D array of rows, where the first row is the header. Typically returned by readSheetData.

criteria ​

Type: Object

Required: Yes

An object mapping header column names to the values to match. Example:

js
{
  Email: '[email protected]',
  Status: 'Active'
}

matchMultiple ​

Type: Boolean

Required: No

Optional. If true, returns all matching rows; otherwise, returns only the first match.

Output ​

Type: Promise

Returns a Promise that resolves to an object:

  • status: true if a match was found, false otherwise
  • data:
    • If matchMultiple = false: a single result object with:
      • rowIndex: index of the matching row (1-based within the data array)
      • row: the matched row array
      • header: the original header array
    • If matchMultiple = true: an array of such result objects described above.
  • err: If status is false, contains error details (e.g., no match or missing column)

$io.google.formatSheetRows ​

Apply formatting (background color, text color, bold) to specific rows in a Google Sheets tab.

Usage ​

js
$io.google.formatSheetRows(connectionName, fileId, sheetName, rowIndexes, options)

Description ​

This function applies cell formatting to specific rows in a sheet tab. It supports background color, text color, and bold styling, and applies these to all cells in each target row.

The number of columns is auto-detected from the header row. Formatting is applied using batchUpdate. If no options are provided, the call will fail with an error.

Usage Scenarios ​

  • Highlight rows based on status (e.g., errors, flagged records)
  • Visually differentiate sections of a spreadsheet
  • Format header rows or recent entries for emphasis

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file that contains the sheet to format.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab where formatting will be applied.

rowIndexes ​

Type: Array

Required: Yes

An array of zero-based row indexes to format. Example:

js
[1, 3, 5]

options ​

Type: Object

Required: No

Optional. An object specifying the formatting to apply. At least one must be provided. Supported keys:

js
{
  backgroundColor: { red: 1, green: 0.9, blue: 0.9 },
  textColor: { red: 0, green: 0, blue: 0 },
  bold: true
}

Output ​

Type: Promise

Returns a Promise resolving to an object summarizing the result:

  • status: true if formatting was applied successfully
  • data: { formatted: Number } — number of rows formatted
  • err: If status is false, contains error information

$io.google.getCalendarEvent ​

Retrieve full metadata for a specific event in a Google Calendar.

Usage ​

js
$io.google.getCalendarEvent(connectionName, calendarId, eventId)

Description ​

This function retrieves full details of a specific event from a Google Calendar by its ID.

The returned metadata includes fields such as summary (title), description, start/end times, location, attendees, status (confirmed/cancelled), visibility, recurrence, and more.

This is useful for viewing, editing, or synchronizing event information.

Usage Scenarios ​

  • Fetch complete event details to display or process
  • Check event properties before updating or deleting
  • Sync or audit a specific event by ID

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Calendar API call.

calendarId ​

Type: String

Required: Yes

The ID of the calendar that contains the event.

eventId ​

Type: String

Required: Yes

The ID of the event to retrieve.

Output ​

Type: Promise

Returns a Promise resolving to an object:

$io.google.getGmailMessage ​

Fetch and decode a Gmail message's headers and body (text and HTML formats).

Usage ​

js
$io.google.getGmailMessage(connectionName, messageId, options)

Description ​

This function retrieves the full metadata and content of a Gmail message by its ID.

By default, it decodes and returns the following fields:

  • 'subject', 'from', 'to', 'cc', 'bcc', 'date' — extracted from message headers
  • 'labelIds' — labels assigned to the message
  • 'snippet' — Gmail's snippet summary
  • 'text', 'html' — decoded plain-text and HTML body parts

If 'options.raw === true', the function skips parsing and returns the full raw Gmail message object instead.

Usage Scenarios ​

  • Extract message details like subject, from, body, and labels
  • Parse incoming messages for automation or routing
  • Access full email content after a watch trigger

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

messageId ​

Type: String

Required: Yes

The ID of the Gmail message to retrieve.

options ​

Type: Object

Required: No

Optional. If 'raw === true', returns the unprocessed Gmail message object.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the message was successfully retrieved
  • 'data': Object containing parsed message fields, or raw message if 'options.raw' is true
  • 'err': If status is false, contains error information

$io.google.getGmailThread ​

Fetch a Gmail thread and return its messages in the desired format.

Usage ​

js
$io.google.getGmailThread(connectionName, threadId, format)

Description ​

Fetches a Gmail thread (i.e., a conversation consisting of multiple related messages) by its thread ID and returns its messages.

The format can be one of:

  • 'minimal' (default): Only includes 'id' and 'threadId' for each message.
  • 'metadata': Includes headers like Subject, From, To, Date, etc.
  • 'full': Includes headers and decoded body content (plain text and HTML).

Returned object includes:

  • id: Thread ID
  • historyId: Gmail history ID
  • messages[]: List of simplified message objects depending on format:

When 'metadata' or 'full' is used, each message in messages[] contains:

  • id, threadId, labelIds, snippet
  • subject, from, to, cc, bcc, date — from headers
  • text, html — decoded body parts (only in 'full')

If 'minimal' is used, only message IDs and thread IDs are returned. You may use $io.google.getGmailMessage to fetch full details per message.

Usage Scenarios ​

  • Retrieve all messages in a specific email thread
  • Access headers and/or body of messages within a conversation
  • Use after selecting a thread from $io.google.listGmailThreads

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

threadId ​

Type: String

Required: Yes

The Gmail thread ID to retrieve.

format ​

Type: String

Required: No

Optional. Format of messages: 'minimal' (default), 'metadata', or 'full'.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if successful
  • data:
  • err: If status is false, contains error details

$io.google.getWorksheetIdByName ​

Look up the internal sheetId of a tab in a Google Sheets file by its name.

Usage ​

js
$io.google.getWorksheetIdByName(connectionName, fileId, sheetName)

Description ​

This function retrieves the internal sheetId of a specific sheet tab in a Google Sheets file. The sheetId is required for structural operations like inserting or deleting rows/columns.

If the sheet with the specified sheetName is found, its numeric ID is returned. If not, the function returns status: false and a descriptive error.

Usage Scenarios ​

  • Access low-level sheet operations that require the internal sheet ID
  • Use in batchUpdate requests to modify sheet structure
  • Validate that a given tab exists before performing operations

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the request.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file containing the target sheet.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab whose internal ID should be retrieved.

Output ​

Type: Promise

Returns a Promise resolving to an object with the following:

  • status: true if the sheet was found, false otherwise
  • data: If status is true, contains the numeric sheetId of the tab
  • err: If status is false, contains an error message string

$io.google.listCalendarEvents ​

List events in a Google Calendar within a specified time range, supporting filters and pagination.

Usage ​

js
$io.google.listCalendarEvents(connectionName, calendarId, timeMin, timeMax, maxResults, pageToken, other)

Description ​

This function lists events from a specific Google Calendar, filtered by a date/time range.

It supports:

  • Pagination with 'pageToken'
  • Adjustable 'maxResults' per page
  • Merging of additional filter options via the 'other' parameter (e.g., keyword search, visibility filters)

Time parameters accept ISO 8601 strings, JavaScript Date objects, or moment instances. If 'timeMin' or 'timeMax' is not provided, defaults to the current day window (24 hours).

Usage Scenarios ​

  • Fetch upcoming or past events for a user
  • Search calendar events within a date window
  • Paginate through large event datasets for reporting or dashboards

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Calendar API call.

calendarId ​

Type: String

Required: Yes

The ID of the calendar to query for events.

timeMin ​

Type: String | Date | moment

Required: No

Optional. Lower bound for event start time (inclusive). Defaults to now if omitted. Accepts ISO 8601 string, Date object, or moment instance.

timeMax ​

Type: String | Date | moment

Required: No

Optional. Upper bound for event start time (exclusive). Defaults to 1 day after 'timeMin' if omitted.

maxResults ​

Type: Number

Required: No

Optional. Maximum number of events to return per page. Default is 100.

pageToken ​

Type: String

Required: No

Optional. Token to retrieve a specific page of results for pagination.

other ​

Type: Object

Required: No

Optional. Additional Google Calendar API query options (e.g., q for keyword search, showHiddenInvitations, iCalUID, etc.).

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the query succeeded
  • 'data': Full API response object (includes 'items' array, 'nextPageToken', etc.)
  • 'err': If status is false, contains error details

$io.google.listCalendars ​

List all calendars accessible by the authenticated Google account.

Usage ​

js
$io.google.listCalendars(connectionName)

Description ​

This function retrieves all calendars visible to the authenticated user.

It returns both primary and secondary calendars, including shared calendars and calendars created by the user.

The returned information includes each calendar's ID, name (summary), description, timezone, color, access role, and more.

Usage Scenarios ​

  • Display a calendar picker in your app
  • Allow users to select which calendar to watch or add events to
  • Sync a user's available calendars for automation setups

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Calendar API request.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if calendars were successfully listed
  • data: An array of calendar metadata objects. Each object may include:
    • id: Calendar ID
    • summary: Calendar display name
    • description, timeZone, colorId, accessRole, etc.
  • err: If status is false, contains error details

$io.google.listDriveFolderContents ​

List files and/or folders inside a Google Drive folder, with filtering support.

Usage ​

js
$io.google.listDriveFolderContents(connectionName, folderId, options)

Description ​

This function lists the contents of a Google Drive folder.

By default, it includes both files and folders. You can filter results using the options parameter to include only files or only folders. If folderId is empty or omitted, the user's root folder is used.

Usage Scenarios ​

  • Fetch the contents of a folder for display or navigation
  • Scan user-uploaded files in a shared or team folder
  • List only folders or only files depending on use case

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the API request.

folderId ​

Type: String

Required: Yes

The ID of the Google Drive folder to list contents from. If empty or omitted, defaults to the user's root folder.

options ​

Type: Object

Required: No

Optional filtering options:

js
{
  includeFiles: true,     // default: true
  includeFolders: true    // default: true
}
Set one of these to false to filter the results.

### Output

Type: `Promise`

Returns a Promise resolving to an object:
- `status`: true if the contents were listed successfully
- `data`: An array of file/folder metadata, each object includes:
  - `id`, `name`, `mimeType`, `parents`, `createdTime`, `modifiedTime`, `size`
- `err`: If status is false, contains error information


### Related Functions

- [`$io.google.createDriveFolder`](./io-google.md#api-io-google-createdrivefolder)
- [`$io.google.copyDriveFile`](./io-google.md#api-io-google-copydrivefile)
- [`$io.google.moveDriveFile`](./io-google.md#api-io-google-movedrivefile)


## $io.google.listDrivePermissions {#api-io-google-listdrivepermissions}

List all sharing permissions applied to a file in Google Drive.

### Usage

```js
$io.google.listDrivePermissions(connectionName, fileId)

Description ​

This function retrieves all sharing permissions for a specified file in Google Drive.

The returned permissions include user, domain, and public access levels, with details such as roles and email addresses. This is useful for audit logs, security reviews, or admin dashboards.

Usage Scenarios ​

  • Audit who has access to a Drive file
  • Display current sharing settings for a user interface
  • Review public and private permissions before modifying access

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Drive API request.

fileId ​

Type: String

Required: Yes

The ID of the Drive file whose sharing permissions should be listed.

Output ​

Type: Promise

Returns a Promise that resolves to an object:

  • status: true if the permissions were successfully retrieved
  • data: An array of permission objects. Each object may include:
    • id: Permission ID
    • type: 'user', 'domain', or 'anyone'
    • role: 'reader', 'writer', etc.
    • emailAddress (if type is 'user')
    • domain (if type is 'domain')
    • allowFileDiscovery: Boolean flag for link visibility
  • err: If status is false, contains error details

$io.google.listGmailLabels ​

List all Gmail labels available to the authenticated user.

Usage ​

js
$io.google.listGmailLabels(connectionName)

Description ​

This function retrieves all Gmail labels associated with the authenticated account.

Each label object contains fields such as:

  • 'id': Unique label ID (e.g., 'INBOX', 'UNREAD', or a user-defined ID)
  • 'name': Human-readable label name
  • 'type': Either 'system' or 'user'
  • 'labelListVisibility' and 'messageListVisibility': Optional UI config settings

This function is often used in conjunction with Gmail watch registrations or filtering logic.

Usage Scenarios ​

  • Let users select Gmail labels for filtering or automation
  • Display Gmail label names and IDs in a user interface
  • Support configuration of label-specific watchers (e.g., watch only INBOX)

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Gmail API request.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if labels were successfully retrieved
  • 'data': Array of label metadata objects
  • 'err': If status is false, contains error information

$io.google.listGmailMessages ​

List Gmail messages with support for filters, labels, pagination, and detail level control.

Usage ​

js
$io.google.listGmailMessages(connectionName, pageToken, maxResults, format, options)

Description ​

This function searches and retrieves Gmail messages using flexible filters and Gmail search syntax.

Supports three formats:

  • 'minimal' (default): Only 'id' and 'threadId' per message. Use $io.google.getGmailMessage to fetch full content as needed.
  • 'metadata': Includes headers like Subject, From, Date (max 10 results per page)
  • 'full': Includes parsed body and headers (max 10 results per page)

When 'format' is 'metadata' or 'full', each message object in data.messages[] contains:

  • 'id', 'threadId', 'labelIds', 'snippet'
  • 'subject', 'from', 'to', 'cc', 'bcc', 'date' — extracted from message headers
  • 'text', 'html' — decoded body parts (only present in 'full' mode)

Filter options include:

  • 'from', 'to', 'subject', 'body'
  • 'labelIds': Array of Gmail label IDs
  • 'after', 'before': Accepts Date, ISO string, or moment
  • 'isUnread', 'hasAttachment'
  • 'query': Gmail raw search query (overrides structured filters)

If 'metadata' or 'full' is used, each message is resolved individually.

Usage Scenarios ​

  • Search messages with filters like subject, sender, label, or date
  • Paginate through large Gmail inboxes
  • Fetch message metadata or full content previews in a custom inbox UI

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

pageToken ​

Type: String

Required: No

Optional. Gmail pagination token for fetching the next page.

maxResults ​

Type: Number

Required: No

Optional. Maximum number of messages to retrieve in one page (default is 10). For 'metadata' or 'full', the value must be <= 10.

format ​

Type: String

Required: No

Optional. One of: 'minimal' (default), 'metadata', or 'full'. Controls the depth of returned data.

options ​

Type: Object

Required: No

Optional. Additional filters. Keys include:

  • 'from', 'to', 'subject', 'body'
  • 'labelIds': Array of Gmail label IDs
  • 'after', 'before': Accepts Date, ISO string, or moment
  • 'isUnread', 'hasAttachment': Boolean
  • 'query': Gmail raw search string (overrides others)
  • 'debug': If true, logs fetch failures for individual messages

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if listing succeeded
  • 'data.messages': Array of message summaries or full metadata (depending on format)
  • 'data.nextPageToken': Token for fetching the next page
  • 'data.resultSizeEstimate': Approximate number of matching results
  • 'err': If status is false, contains error information

$io.google.listGmailThreads ​

Search and list Gmail threads using filters or query.

Usage ​

js
$io.google.listGmailThreads(connectionName, pageToken, maxResults, format, options)

Description ​

This function searches and retrieves Gmail threads (conversations of related messages) using flexible filters and Gmail search syntax.

Supports three formats:

  • 'minimal' (default): Only 'id' and 'snippet' for each thread. Message details are not included.
  • 'metadata': Each thread includes parsed message headers such as Subject, From, and Date (max 10 results per page).
  • 'full': Each thread includes parsed headers and decoded body (plain text and HTML) for each message (max 10 results per page).

When 'format' is 'metadata' or 'full', each thread in data.threads[] includes:

  • id: Thread ID
  • snippet: Summary text (from the first message)
  • messageCount: Number of messages in the thread
  • messages[]: List of simplified message objects, where each message contains:
    • id, threadId, labelIds, snippet
    • subject, from, to, cc, bcc, date — extracted from headers
    • text, html — decoded message body parts (present only in 'full' format)

If 'minimal' is used, you can use $io.google.getGmailMessage to retrieve full message data as needed.

Filter options include:

  • from, to, subject, body
  • labelIds: Array of Gmail label IDs
  • after, before: Accepts Date, ISO string, or moment
  • isUnread, hasAttachment
  • query: Gmail raw search query (overrides structured filters)

Threads are paginated using pageToken, and results include nextPageToken and resultSizeEstimate. Each thread is resolved using Gmail's threads.get API to fetch its messages and apply parsing logic.

Usage Scenarios ​

  • Search conversation threads using Gmail search syntax
  • Get paginated thread summaries or full message metadata
  • Trigger automation based on email threads

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

pageToken ​

Type: String

Required: No

Optional. If provided, fetches the next page of results starting from this token.

maxResults ​

Type: Number

Required: No

Optional. Maximum number of threads to retrieve in one page. Required to be ≤10 for 'metadata' or 'full' formats.

format ​

Type: String

Required: No

Optional. Format of each message: 'minimal' (default), 'metadata', or 'full'.

options ​

Type: Object

Required: No

Optional filters and flags for the search:

  • from, to, subject, body
  • labelIds (array of label IDs)
  • after, before (Date, ISO, or moment)
  • isUnread, hasAttachment
  • query (raw Gmail query string)
  • debug (true to log fetch errors)

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if retrieval was successful
  • data:
  • err: If status is false, contains error details

$io.google.moveDriveFile ​

Move a file in Google Drive to a new folder, replacing its current location.

Usage ​

js
$io.google.moveDriveFile(connectionName, fileId, newFolderId)

Description ​

This function moves a file to a different folder in Google Drive by replacing all of its existing parent folders with the new one.

It retrieves the file's current parents, removes them, and sets the specified newFolderId as the new parent.

This is useful for workflows that categorize, archive, or relocate files after upload or processing.

Usage Scenarios ​

  • Organize uploaded files by placing them into project or user-specific folders
  • Implement workflows that relocate files based on status or stage
  • Transfer a file from a temporary location to its final destination

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the API request.

fileId ​

Type: String

Required: Yes

The ID of the file to be moved.

newFolderId ​

Type: String

Required: Yes

The ID of the new destination folder in Drive.

Output ​

Type: Promise

Returns a Promise resolving to an object containing:

  • status: true if the file was moved successfully
  • data: Metadata of the moved file (including id, name, parents)
  • err: If status is false, contains error details

$io.google.readSheetData ​

Read cell data from an entire Google Sheets tab or a specified rectangular region.

Usage ​

js
$io.google.readSheetData(connectionName, fileId, sheetName, range)

Description ​

This function retrieves values from a Google Sheets tab. By default, it returns all visible cells from the sheet. If a rectangular range is provided, only that area will be fetched.

The range is specified using zero-based startRowIndex and startColIndex, with optional numRows and numCols. All values are returned as raw strings in a 2D array structure.

Usage Scenarios ​

  • Load sheet data for analysis, preview, or validation
  • Read a defined block of cells for batch processing
  • Import records from Sheets into your app's workflows

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the read request.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file from which to read data.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab to read from.

range ​

Type: Object

Required: No

Optional. A zero-based object defining the rectangular area to read. Example:

js
{
  startRowIndex: 1,  // Row 2
  startColIndex: 0,  // Column A
  numRows: 4,
  numCols: 3
}

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the data was read successfully, false otherwise
  • data: A 2D array of raw cell values (e.g., [[...], [...]])
  • err: If status is false, contains error details

$io.google.removeAttendeesFromEvent ​

Remove specified attendees from an existing Google Calendar event.

Usage ​

js
$io.google.removeAttendeesFromEvent(connectionName, calendarId, eventId, emailsToRemove, notifyAttendees)

Description ​

This function removes specified attendees from an existing event in Google Calendar.

The system:

  • Fetches the current attendee list
  • Removes all attendees whose email addresses match any in the 'emailsToRemove' list (case-insensitive)
  • Updates the event with the reduced list

The 'notifyAttendees' flag controls whether Google Calendar automatically sends cancellation notices to the removed participants.

Only the attendee emails are needed for removal — full attendee objects are not required.

Usage Scenarios ​

  • Uninvite specific participants from a scheduled meeting
  • Manage attendance dynamically when users cancel or opt out
  • Correct attendee lists after changes in booking or participation

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

calendarId ​

Type: String

Required: Yes

The ID of the calendar containing the event.

eventId ​

Type: String

Required: Yes

The ID of the event from which attendees should be removed.

emailsToRemove ​

Type: Array

Required: Yes

Array of email addresses to remove from the attendee list.

Example: [ '[email protected]', '[email protected]' ]

notifyAttendees ​

Type: Boolean

Required: No

Optional. If true (default), Google Calendar will notify removed attendees.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the attendees were successfully removed
  • 'data': Updated event metadata
  • 'err': If status is false, contains error information

$io.google.removeGmailLabelByName ​

Remove a Gmail label from a message using the label's display name.

Usage ​

js
$io.google.removeGmailLabelByName(connectionName, messageId, labelName)

Description ​

This function removes a Gmail label from a message using the label's display name.

  • Internally, it uses $io.google.findGmailLabelByName to look up the label ID.
  • Then it removes the label from the message via $io.google.updateGmailMessage.

Label name matching is case-insensitive.

If the label is not found, the function returns an error.

Usage Scenarios ​

  • Un-tag a message from a user-defined category like 'Processed' or 'Needs Reply'
  • Support automation that cleans up labels by name
  • Allow end users to remove labels without knowing internal Gmail label IDs

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

messageId ​

Type: String

Required: Yes

The Gmail message ID to remove the label from.

labelName ​

Type: String

Required: Yes

The display name of the Gmail label to remove (e.g., 'Inbox', 'Leads', 'Archived').

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the label was successfully removed
  • 'data': Gmail's updated message metadata
  • 'err': If status is false, contains error info (e.g., label not found)

$io.google.removeGmailThreadLabelByName ​

Remove a Gmail label from a thread by its name.

Usage ​

js
$io.google.removeGmailThreadLabelByName(connectionName, threadId, labelName)

Description ​

This function removes a Gmail label from a thread by its name.

The label name is case-insensitive. If the label does not exist, the function returns an error.

Internally, this resolves the label ID using $io.google.findGmailLabelByName and then calls $io.google.updateGmailThread.

Usage Scenarios ​

  • Clean up labels from threads no longer relevant
  • Unmark threads that have been resolved
  • Reorganize email threads by removing outdated categories

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

threadId ​

Type: String

Required: Yes

The Gmail thread ID to update.

labelName ​

Type: String

Required: Yes

The name of the Gmail label to remove from the thread.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if successful
  • data: Gmail thread object with updated labelIds
  • err: Error details if failed

$io.google.renameDriveItem ​

Rename a file or folder in Google Drive.

Usage ​

js
$io.google.renameDriveItem(connectionName, fileId, newName)

Description ​

This function renames a file or folder in Google Drive.

It updates the name property of the Drive item with the provided newName. This can be used for both files and folders, as long as the fileId is valid.

Usage Scenarios ​

  • Rename a newly created or uploaded file to match a naming convention
  • Update folder names dynamically based on project or workflow changes
  • Allow users or systems to rename Drive items programmatically

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the API request.

fileId ​

Type: String

Required: Yes

The ID of the Drive file or folder to rename.

newName ​

Type: String

Required: Yes

The new name to assign to the Drive item.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the item was renamed successfully
  • data: { id: String, name: String } — metadata of the renamed item
  • err: If status is false, contains error information

$io.google.saveDriveFile ​

Upload a new file or overwrite an existing file in Google Drive from a stream, buffer, or URL.

Usage ​

js
$io.google.saveDriveFile(connectionName, fileId, bufferOrStreamOrUrl, fileName, mimeType, destFolderId, convertToDoc)

Description ​

This function saves a file to Google Drive.

If fileId is provided, it overwrites the existing file. If fileId is null or empty, a new file is uploaded.

The input bufferOrStreamOrUrl can be:

  • A Buffer (binary content)
  • A readable stream
  • A URL string

The function also supports renaming, setting MIME types, placing the file in a Drive folder, and optionally converting to Google Docs format.

Usage Scenarios ​

  • Upload documents to Drive from a user form, backend process, or external URL
  • Update an existing file's contents and/or filename
  • Convert uploaded documents (e.g., PDFs, Word files) to Google Docs format

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for Drive API authentication.

fileId ​

Type: String

Required: No

If non-empty string, the file with this ID will be overwritten. Otherwise, a new file is created.

bufferOrStreamOrUrl ​

Type: Mixed

Required: Yes

A Buffer, Stream, or URL pointing to the file content.

fileName ​

Type: String

Required: Yes

The name to assign to the uploaded or updated file.

mimeType ​

Type: String

Required: No

Optional. The MIME type of the file (e.g., 'application/pdf'). If omitted and input is a URL, it is inferred from headers.

destFolderId ​

Type: String

Required: No

Optional. The ID of the destination folder in Drive (used only when creating a new file).

convertToDoc ​

Type: Boolean

Required: No

Optional. If true, the uploaded file is converted to Google Docs format (e.g., PDF or Word → Docs). Only applies when uploading new files.

Output ​

Type: Promise

Returns a Promise resolving to an object describing the operation:

  • status: true if upload or update succeeded
  • data: Metadata of the resulting file (e.g., id, name, mimeType)
  • err: If status is false, contains error information

$io.google.searchDriveFiles ​

Search for files in Google Drive using name, type, folder, and pagination filters.

Usage ​

js
$io.google.searchDriveFiles(connectionName, options)

Description ​

This function searches for files in Google Drive using flexible filter options including:

  • File name (exact or partial match)
  • Folder ID (to scope the search)
  • One or more MIME types (e.g., PDFs, Docs, Spreadsheets)
  • Result count and pagination control

The function returns an array of matching files and a nextPageToken if more results are available.

Usage Scenarios ​

  • Locate documents by partial or exact name match
  • Search within a specific folder for certain file types
  • Paginate through large file sets to index or audit Drive content

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Drive API call.

options ​

Type: Object

Required: No

Optional search filters:

js
{
  folderId: '...',                 // restrict search to a folder
  name: 'Report',                 // search by name (partial match by default)
  exactNameMatch: true,          // set to true to match full name exactly
  mimeTypes: ['application/pdf'],// filter by one or more MIME types
  maxResults: 100,               // limit number of results (default 100)
  pageToken: '...',              // use for pagination
}

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the query succeeded
  • data: Array of matching files. Each file includes:
    • id, name, mimeType, parents, createdTime, modifiedTime, size, webViewLink
  • nextPageToken: If more results exist, pass this value to fetch the next page
  • err: If status is false, contains error information

$io.google.sendGmailMessage ​

Send a new email message using Gmail with optional HTML and attachments.

Usage ​

js
$io.google.sendGmailMessage(connectionName, to, subject, bodyText, bodyHtml, attachments, options)

Description ​

This function composes and sends an email using the authenticated user's Gmail account.

At least to, subject, and one of bodyText or bodyHtml must be provided.

Attachments are optional and support multiple formats:

  • { buffer, fileName, mimeType }: raw Buffer content
  • { stream, fileName, mimeType }: readable stream
  • { url, fileName?, mimeType? }: external file via URL

Sender address is automatically resolved via Gmail profile unless explicitly set via options.from.

The message is sent using MIME-encoded raw format.

Note: This function does not use a draft or template; it sends directly.

Usage Scenarios ​

  • Send transactional emails to users
  • Notify internal teams of status changes or alerts
  • Send emails with one or more file attachments

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

to ​

Type: String

Required: Yes

Recipient email address (comma-separated if multiple).

subject ​

Type: String

Required: Yes

Subject line of the email.

bodyText ​

Type: String

Required: Yes

Plain text version of the email body.

bodyHtml ​

Type: String

Required: No

Optional. HTML version of the email body. If both bodyText and bodyHtml are present, multipart is used.

attachments ​

Type: Array

Required: No

Optional. Array of attachment objects. Each must specify one of: buffer, stream, or url. Example:

js
{
  buffer: <Buffer>,
  fileName: 'report.pdf',
  mimeType: 'application/pdf'
}

options ​

Type: Object

Required: No

Optional. Additional email metadata:

  • cc: String (comma-separated)
  • bcc: String (comma-separated)
  • from: Override sender email
  • displayName: Name shown in the 'From' field
  • replyTo: Custom reply-to address

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if sent successfully
  • data: Sent Gmail message metadata
  • err: If failed, contains error details

$io.google.shareDriveFile ​

Share a Google Drive file with public, domain, or user access and return shareable links.

Usage ​

js
$io.google.shareDriveFile(connectionName, fileId, options)

Description ​

This function shares a Drive file with specified permissions and returns updated metadata including the shareable link.

By default, it shares the file publicly as a reader. The options object allows configuration of the access type, role, and target (domain or email). After applying the permission, it fetches and returns the updated file metadata including webViewLink and webContentLink.

Usage Scenarios ​

  • Enable public viewing or downloading of a file
  • Share a document with a specific domain or email address
  • Generate a web link for viewing or downloading a Drive file

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Drive API call.

fileId ​

Type: String

Required: Yes

The ID of the file to be shared.

options ​

Type: Object

Required: No

Optional. Sharing configuration object with the following properties:

js
{
  type: 'anyone' | 'domain' | 'user',  // default: 'anyone'
  role: 'reader' | 'writer',           // default: 'reader'
  domain: 'example.com',               // required if type = 'domain'
  emailAddress: '[email protected]'     // required if type = 'user'
}

Output ​

Type: Promise

Returns a Promise resolving to an object containing:

  • status: true if the sharing action succeeded
  • data: File metadata including:
    • id: File ID
    • name: File name
    • webViewLink: URL to open the file in Drive
    • webContentLink: URL to download the file
  • err: If status is false, contains error details

$io.google.unshareDriveFile ​

Remove a specific sharing permission from a Google Drive file (user, domain, or public).

Usage ​

js
$io.google.unshareDriveFile(connectionName, fileId, options)

Description ​

This function removes a specific sharing permission from a file in Google Drive.

You can target the type of permission (e.g., public, domain, or user-specific), and provide identifiers (email or domain) as needed. The function first lists all current permissions, finds the matching entry, and removes it if found.

Usage Scenarios ​

  • Revoke access previously granted to a user or domain
  • Remove public visibility of a file (type: 'anyone')
  • Tighten access control on sensitive documents

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Drive API request.

fileId ​

Type: String

Required: Yes

The ID of the file from which to remove a sharing permission.

options ​

Type: Object

Required: No

Optional. An object describing which permission to remove. Must specify a type and optionally emailAddress or domain:

js
{
  type: 'anyone' | 'user' | 'domain',  // Required
  emailAddress: '[email protected]',     // Required if type = 'user'
  domain: 'example.com'                 // Required if type = 'domain'
}

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the matching permission was successfully removed
  • data: { removed: true, permissionId: String } on success
  • err: If status is false, contains error details (e.g., no matching permission found)

$io.google.unwatchCalendarEventChange ​

Remove a previously registered event change trigger from a specific Google Calendar.

Usage ​

js
$io.google.unwatchCalendarEventChange(connectionName, calendarId, id)

Description ​

This function removes a previously registered event change trigger on a specific Google Calendar.

The calendarId and id must match the values used during the watchCalendarEventChange registration.

If no clients remain for the calendar, the internal watcher is disabled automatically.

Usage Scenarios ​

  • Stop tracking event changes for a calendar
  • Clean up webhook registrations when a user disconnects
  • Disable synchronization for deleted calendars or accounts

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Calendar API call.

calendarId ​

Type: String

Required: Yes

The ID of the calendar whose watch should be removed.

id ​

Type: String

Required: Yes

The unique identifier of the registered watch to remove.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the watch was successfully removed
  • data: {removed: Boolean} — true if a client was removed
  • err: If status is false, contains error details

$io.google.unwatchCalendarListChange ​

Remove a previously registered trigger for monitoring Google Calendar list changes.

Usage ​

js
$io.google.unwatchCalendarListChange(connectionName, id)

Description ​

This function removes a previously registered watch on a user's Google Calendar list.

The id must match the identifier used during the corresponding watchCalendarListChange registration. If no clients remain after removal, the calendar watch channel is disabled automatically.

Usage Scenarios ​

  • Stop monitoring changes to a user's list of calendars
  • Disable synchronization or automation tied to calendar list updates
  • Clean up webhook registrations to reduce resource usage

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the API call.

id ​

Type: String

Required: Yes

The unique identifier of the watch registration to remove.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the watch was successfully removed
  • data: {removed: Boolean} — true if a client was found and removed
  • err: If status is false, contains error details

$io.google.unwatchDriveChange ​

Remove a previously registered trigger that was monitoring a Google Drive file or folder.

Usage ​

js
$io.google.unwatchDriveChange(connectionName, id, mimeType)

Description ​

This function removes a previously registered Drive change trigger. It disables tracking for the trigger identified by id on the specified connection.

If a MIME type was specified during registration via watchDriveChange, the same mimeType value must be provided here for the unwatch to succeed.

Usage Scenarios ​

  • Stop monitoring a specific Drive file or folder for changes
  • Disable Drive triggers when no longer needed
  • Clean up listeners tied to temporary files or user sessions

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection defined in your app. This must refer to a connection configured with Google OAuth2 credentials.

id ​

Type: String

Required: Yes

The unique identifier of the trigger that was registered earlier via watchDriveChange.

mimeType ​

Type: String

Required: No

Optional. The MIME type that was originally used during watchDriveChange registration. If a MIME type was specified when registering the trigger, the same value must be provided here to successfully remove it.

Output ​

Type: Promise

This function returns a Promise that resolves to an object indicating the status of the unwatch operation:

  • status: true if the trigger was removed successfully, false otherwise.
  • err: If status is false, contains error details as a string.

$io.google.unwatchFileChange ​

Remove a previously registered trigger monitoring changes to a specific Google Drive file.

Usage ​

js
$io.google.unwatchFileChange(connectionName, id, fileId)

Description ​

This function removes a file-level trigger that was previously registered using watchFileChange. It disables change tracking for the specific file identified by fileId, under the given connectionName and id.

Both id and fileId must match the values used during registration.

Usage Scenarios ​

  • Stop tracking a file after it is deleted or archived
  • Disable file-level change listeners when a user logs out
  • Remove temporary watchers for session-based workflows

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the file watch removal.

id ​

Type: String

Required: Yes

The unique identifier that was used when the file watch was created.

fileId ​

Type: String

Required: Yes

The Google Drive file ID that was being watched.

Output ​

Type: Promise

Returns a Promise that resolves to an object indicating whether the file trigger was successfully removed:

  • status: true if removal succeeded, false otherwise
  • err: If status is false, contains error information

$io.google.unwatchGmailChange ​

Remove a previously registered Gmail watch trigger for a given label group and ID.

Usage ​

js
$io.google.unwatchGmailChange(connectionName, id, labelIds)

Description ​

This function removes a previously registered Gmail watch based on the unique registration ID and associated label group.

If no 'labelIds' are provided, the function assumes the default label scope (i.e., all messages).

Watches are internally grouped by label combinations. This function ensures the correct watcher instance is accessed and the specified client is removed.

If no clients remain on the watch, the watcher is disabled and removed from memory.

Usage Scenarios ​

  • Disable Gmail change monitoring for a specific automation
  • Clean up watchers when a client disconnects or no longer needs email triggers
  • Stop tracking a label-specific subset of messages

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Gmail API call.

id ​

Type: String

Required: Yes

The unique identifier used during the original 'watchGmailChange' registration.

labelIds ​

Type: Array

Required: No

Optional. Array of Gmail label IDs associated with the original watch. If omitted or empty, assumes default label scope.

Output ​

Type: Promise

Returns a Promise resolving to a boolean:

  • 'true' if the client was successfully removed from the watch group
  • 'false' if no matching watcher or client was found

$io.google.unwatchNewDriveFiles ​

Remove a previously registered trigger for monitoring newly added files in Google Drive.

Usage ​

js
$io.google.unwatchNewDriveFiles(connectionName, id)

Description ​

This function removes a Drive watch that was created using watchNewDriveFiles.

It wraps unwatchDriveChange with an empty MIME type to match the watch registration. The id must match the one used during the corresponding watch registration.

Usage Scenarios ​

  • Stop watching a folder or global Drive space for new uploads
  • Clean up temporary file monitoring watchers
  • Disable triggers after a workflow or session ends

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the API request.

id ​

Type: String

Required: Yes

The unique identifier of the previously registered watch to remove.

Output ​

Type: Promise

Returns a Promise resolving to an object indicating the result:

  • status: true if the trigger was successfully removed
  • err: If status is false, contains error information

$io.google.unwatchNewFoldersInFolder ​

Remove a previously registered trigger monitoring new folders in a Drive folder.

Usage ​

js
$io.google.unwatchNewFoldersInFolder(connectionName, id)

Description ​

This function removes a Drive change watcher that was registered to detect new folders using watchNewFoldersInFolder.

It must use the same id that was provided during registration.

Usage Scenarios ​

  • Stop monitoring a parent folder for new subfolders
  • Clean up watchers set during session-based workflows
  • Disable folder creation alerts for archived structures

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the request.

id ​

Type: String

Required: Yes

The same unique identifier used when the watch was registered.

Output ​

Type: Promise

Returns a Promise resolving to:

  • status: true if the trigger was successfully removed
  • err: If status is false, contains error details

$io.google.unwatchSheetChange ​

Remove a previously registered trigger monitoring changes in a Google Sheets sheet.

Usage ​

js
$io.google.unwatchSheetChange(connectionName, id, fileId, sheetName)

Description ​

This function removes a row-level trigger that was previously registered using watchSheetChange. You must provide the same id, fileId, and (if used) sheetName that were used during registration.

If a sheetName was specified during watch registration, the same name must be provided here for the unwatch to succeed. If sheetName was omitted during registration, it must also be omitted here.

Usage Scenarios ​

  • Stop watching a sheet tab when a workflow ends
  • Remove spreadsheet watchers tied to a session or client
  • Clean up inactive or no longer needed triggers

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Sheets API call.

id ​

Type: String

Required: Yes

The unique identifier originally used to register the watch.

fileId ​

Type: String

Required: Yes

The Google Sheets file ID that was being monitored.

sheetName ​

Type: String

Required: No

Optional. The name of the sheet tab that was monitored. Required if one was used during registration.

Output ​

Type: Promise

Returns a Promise resolving to an object indicating whether the trigger was successfully removed:

  • status: true if removal succeeded, false otherwise
  • err: If status is false, contains error information

$io.google.updateCalendarEvent ​

Update properties of an existing Google Calendar event (excluding attendees).

Usage ​

js
$io.google.updateCalendarEvent(connectionName, calendarId, eventId, startDateTime, endDateTime, title, description, notifyAttendees, other)

Description ​

This function updates the properties of an existing event in Google Calendar.

Supported updates include:

  • Start and end date-times
  • Title (summary)
  • Description
  • Any additional fields provided in the 'other' object (location, colorId, recurrence, etc.)

To manage Google Meet links:

  • Set other.addMeet = true to generate a new Meet link if one does not already exist
  • Set other.removeMeet = true to remove an existing Meet link

Note:

  • To modify the list of attendees (add/remove), use $io.google.addAttendeesToEvent or $io.google.removeAttendeesFromEvent separately.
  • The 'notifyAttendees' flag controls whether invitees are notified of the update.

Date-time inputs are automatically normalized from ISO 8601 string, Date object, or moment instance.

Usage Scenarios ​

  • Reschedule meetings by changing start and end times
  • Update event titles, descriptions, or locations
  • Modify event visibility, color, reminders, or recurrence settings

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

calendarId ​

Type: String

Required: Yes

The ID of the calendar containing the event.

eventId ​

Type: String

Required: Yes

The ID of the event to update.

startDateTime ​

Type: String | Date | moment

Required: No

Optional. New start date-time for the event. If omitted, start time remains unchanged.

endDateTime ​

Type: String | Date | moment

Required: No

Optional. New end date-time for the event. If omitted, end time remains unchanged.

title ​

Type: String

Required: No

Optional. New title (summary) of the event.

description ​

Type: String

Required: No

Optional. New description for the event.

notifyAttendees ​

Type: Boolean

Required: No

Optional. If true (default), sends update notifications to attendees.

other ​

Type: Object

Required: No

Optional. Additional fields following the Google Calendar API Events resource. Example: location, colorId, recurrence.

To manage Google Meet:

  • Set addMeet: true to add a Google Meet link
  • Set removeMeet: true to remove an existing Meet link

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the event was updated successfully
  • 'data': Full updated event metadata
  • 'err': If status is false, contains error information

$io.google.updateGmailMessage ​

Add or remove Gmail labels on a message using standard flags or explicit label IDs.

Usage ​

js
$io.google.updateGmailMessage(connectionName, messageId, options)

Description ​

This function modifies the labels on a Gmail message using high-level flags or explicit label IDs.

High-level flags include:

  • 'markRead': Removes the UNREAD label
  • 'markUnread': Adds the UNREAD label
  • 'archive': Removes the INBOX label
  • 'spam': Adds the SPAM label
  • 'trash': Adds the TRASH label
  • 'star': Adds the STARRED label
  • 'unstar': Removes the STARRED label

You can also specify:

  • 'addLabels': Array of label IDs to apply
  • 'removeLabels': Array of label IDs to remove

If no label changes are specified, the function will return an error and skip the API call.

Usage Scenarios ​

  • Mark a message as read, unread, starred, archived, or spam
  • Move a message to trash or remove it from inbox
  • Apply or remove user-defined labels programmatically

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

messageId ​

Type: String

Required: Yes

The Gmail message ID to update.

options ​

Type: Object

Required: No

Object with label update options. Supported keys:

  • 'markRead', 'markUnread', 'archive', 'spam', 'trash', 'star', 'unstar' — Boolean flags
  • 'addLabels': Array of label IDs to apply
  • 'removeLabels': Array of label IDs to remove

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if labels were successfully updated
  • 'data': Updated message metadata from Gmail
  • 'err': If status is false, contains error details

$io.google.updateGmailThread ​

Add or remove labels to a Gmail thread (e.g., mark read/unread, archive).

Usage ​

js
$io.google.updateGmailThread(connectionName, threadId, options)

Description ​

This function applies label changes to a Gmail thread by its thread ID.

Supports standard label operations via flags:

  • markRead: true: Removes 'UNREAD'
  • markUnread: true: Adds 'UNREAD'
  • archive: true: Removes 'INBOX'
  • moveToInbox: true: Adds 'INBOX'

You can also explicitly add or remove labels using:

  • addLabelIds: []: Array of label IDs to add
  • removeLabelIds: []: Array of label IDs to remove

Use $io.google.listGmailLabels to retrieve valid label IDs.

Usage Scenarios ​

  • Programmatically archive or unarchive a Gmail thread
  • Mark an entire conversation as read or unread
  • Move a thread back to the inbox

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate.

threadId ​

Type: String

Required: Yes

The Gmail thread ID to update.

options ​

Type: Object

Required: No

Label update options. Supports keys: markRead, markUnread, archive, moveToInbox, addLabelIds, removeLabelIds

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the update succeeded
  • data: Gmail thread object with updated labelIds
  • err: Error info if failed

$io.google.updateSheetCells ​

Update individual cell values in a Google Sheets tab using zero-based row and column indices.

Usage ​

js
$io.google.updateSheetCells(connectionName, fileId, sheetName, updates)

Description ​

This function updates individual cell values in a specific sheet tab by specifying their locations using zero-based row and column indices.

Multiple cells can be updated in a single call. Internally, updates are grouped by row for efficient batch writing.

Each update specifies the target cell via startRowIndex and startColIndex, and a value to insert.

Usage Scenarios ​

  • Set values for scattered cells across the sheet
  • Efficiently update multiple non-contiguous cells
  • Build granular spreadsheet editing features from code

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate the Sheets API request.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file containing the target sheet.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab where cells will be updated.

updates ​

Type: Array

Required: Yes

An array of update instructions. Each entry is an object with:

  • range: An object specifying the target cell using:
    • startRowIndex (Number): Zero-based row index
    • startColIndex (Number): Zero-based column index
  • value: The value to set in the specified cell

Example:

js
[
  { range: { startRowIndex: 2, startColIndex: 3 }, value: 'Hello' },
  { range: { startRowIndex: 2, startColIndex: 4 }, value: 'World' }
]

Output ​

Type: Promise

Returns a Promise resolving to an object indicating the outcome:

  • status: true if all updates were applied successfully
  • data:
    • updated (Number): The number of cell updates requested
  • err: If status is false, contains error information

$io.google.updateSheetRange ​

Update a rectangular range of cells in a Google Sheets tab using a 2D array of values.

Usage ​

js
$io.google.updateSheetRange(connectionName, fileId, sheetName, range, valuesMatrix)

Description ​

This function updates a rectangular range of cells in a sheet tab with the provided matrix of values. The range is defined using zero-based row and column indices and will be translated into A1 notation internally.

range.numRows and range.numCols are optional — if omitted, they are inferred from the dimensions of valuesMatrix. All updates use USER_ENTERED mode, allowing formulas and smart formatting to be interpreted by Sheets.

Usage Scenarios ​

  • Write tabular data to a specific block of a sheet
  • Update multiple rows and columns in a single call
  • Fill in or overwrite a structured region such as a table, report, or form

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for Sheets API authentication.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file containing the target sheet.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab where the range will be updated.

range ​

Type: Object

Required: Yes

A zero-based object specifying where the top-left of the update block begins. Example:

js
{
  startRowIndex: 5,  // Row 6
  startColIndex: 2   // Column C
}

valuesMatrix ​

Type: Array

Required: Yes

A 2D array of values to write into the specified cell block. Example:

js
[
  ['Name', 'City'],
  ['Alice', 'Denver'],
  ['Bob', 'Austin']
]

Output ​

Type: Promise

Returns a Promise resolving to an object summarizing the operation:

  • status: true if the update was applied successfully
  • data: { range: String } — the A1-style range that was updated (e.g., 'Sheet1!C6:D8')
  • err: If status is false, contains error details

$io.google.updateSheetRows ​

Update one or more specific rows in a Google Sheets tab by index.

Usage ​

js
$io.google.updateSheetRows(connectionName, fileId, sheetName, rowUpdates)

Description ​

This function updates one or more specific rows in a sheet tab using 0-based row indices. Each update must specify the starting row index and an array of cell values for that row.

The sheet name is required, and each update applies to a single row starting at the given index. All updates use USER_ENTERED mode to allow formula entry and number parsing.

Usage Scenarios ​

  • Modify previously written records by their row number
  • Update workflow status, timestamps, or flags on specific rows
  • Apply edits to structured sheet content without rewriting the whole file

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for Sheets API authentication.

fileId ​

Type: String

Required: Yes

The ID of the Google Sheets file containing the target sheet.

sheetName ​

Type: String

Required: Yes

The name of the sheet tab where rows will be updated.

rowUpdates ​

Type: Array

Required: Yes

An array of update objects. Each object must contain a range.startRowIndex (zero-based) and a values array of cells for that row.

Example:

js
[
  { range: { startRowIndex: 3 }, values: ['Alice', 'Smith', 'New York'] },
  { range: { startRowIndex: 7 }, values: ['Bob', 'Jones', 'Chicago'] }
]

Output ​

Type: Promise

Returns a Promise resolving to an object summarizing the operation:

  • status: true if all updates were successfully applied
  • data: { updated: Number } — the number of rows updated
  • err: If status is false, contains error details as a string

$io.google.watchCalendarEventChange ​

Register a trigger to monitor changes to events in a specific Google Calendar (additions, updates, cancellations).

Usage ​

js
$io.google.watchCalendarEventChange(connectionName, calendarId, id, cbFn)

Description ​

This function registers a webhook-based trigger to monitor event changes in a specific Google Calendar.

It tracks:

  • New events (added)
  • Modified events (updated)
  • Cancelled events (cancelled)

The system uses a syncToken to efficiently fetch only incremental changes. If the token expires, a full re-synchronization is performed automatically.

The callback function cbFn receives a structured diff object:

js
{
  added: [...],      // Array of newly created events (or null)
  updated: [...],    // Array of modified events (or null)
  cancelled: [...]   // Array of cancelled events (or null)
}

Usage Scenarios ​

  • Trigger workflows when a user adds, updates, or cancels a calendar event
  • Synchronize an app's local database with changes in a Google Calendar
  • Track bookings, meetings, or appointments in real-time

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used to authenticate Calendar API requests.

calendarId ​

Type: String

Required: Yes

The ID of the calendar whose events should be monitored.

id ​

Type: String

Required: Yes

A unique identifier for this watch registration. Used to manage and remove the watch later.

cbFn ​

Type: Function

Required: Yes

Callback function invoked whenever there are changes. Receives a diff object containing added, updated, and cancelled events.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the watch was successfully registered
  • data: Metadata about the registration
  • err: If status is false, contains error information

$io.google.watchCalendarListChange ​

Register a trigger to detect when a user's Google Calendar list changes (additions, removals, updates).

Usage ​

js
$io.google.watchCalendarListChange(connectionName, id, cbFn)

Description ​

This function sets up a webhook-based trigger that monitors changes to the user's list of calendars.

It invokes the provided callback when:

  • A calendar is added
  • A calendar is removed
  • A calendar is modified (e.g., name, description, color, timezone, access role)

The callback receives a single object: { added: [...], // Array of newly added calendars (or null) removed: [...], // Array of removed calendars (or null) updated: [...] // Array of updated calendars, with list of changed fields }

Usage Scenarios ​

  • Sync an app's calendar list with Google Calendar in real-time
  • Trigger workflows when users add new calendars
  • Detect when users remove or modify calendar properties (e.g., name, color)

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

id ​

Type: String

Required: Yes

A unique identifier for the watch registration. Used to manage and unwatch later.

cbFn ​

Type: Function

Required: Yes

Callback function invoked when the user's calendar list changes. Receives the diff object (added, removed, updated).

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the watch was successfully registered
  • data: Watch registration metadata
  • err: If status is false, contains error details

$io.google.watchDriveChange ​

Register a trigger to track changes to a Google Drive file or folder.

Usage ​

js
$io.google.watchDriveChange(connectionName, id, mimeType, fileId, parentFolder, cbFn)

Description ​

This function registers a trigger to monitor changes to a specific Google Drive file or folder. It uses a persistent change token and periodically checks for updates using the Google Drive API. When a change is detected, the provided callback function cbFn is invoked with detailed information about the update.

Usage Scenarios ​

  • Detect when a specific file or folder is modified in Google Drive
  • Trigger flows or actions in response to Drive changes
  • Synchronize Drive updates with your app in near real-time

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection defined in your app. This must refer to a connection configured with Google OAuth2 credentials.

id ​

Type: String

Required: Yes

A unique identifier for this trigger. It is used internally to manage the lifecycle of the watch.

mimeType ​

Type: String

Required: No

Optional. The MIME type of the file or folder to watch (e.g., 'application/vnd.google-apps.folder'). Used for filtering and reporting purposes.

fileId ​

Type: String

Required: No

Optional. The Drive file or folder ID to track for changes. If omitted, the root folder or broader scope may be monitored depending on the setup.

parentFolder ​

Type: String

Required: No

Optional. The ID of the parent folder used for scope tracking. Helps disambiguate ownership or placement, especially for shared Drive content.

cbFn ​

Type: Function

Required: Yes

A callback function invoked when changes are detected. It receives the following parameters:

  • desc: An object describing the changes with the following properties:
    • fileId: String: The ID of the file or folder that changed
    • fileName: String: The name/title of the file or folder
    • mimeType: String: The MIME type of the item (if available)
    • timestamp: Number: The Unix Timestamp for the change
    • created: String: ISO timestamp of the file's creation
    • modified: String: ISO timestamp of the last modification
    • action: String: The change that occurred: unknown,deleted,trashed,added,modified,opened
    • notes: String: A description of the changes
    • version: String: The file's version
    • parents: Array: The list of parent folder IDs
  • fileInfo: Object: The full metadata object returned by the Google Drive API for the file.

Output ​

Type: Promise

This function returns a Promise that resolves to an object indicating the status of the trigger setup:

  • status: true if the trigger was registered successfully, false otherwise.
  • data: Information about the tracking state (e.g., token or timestamp).
  • err: If status is false, contains error details as a string.

$io.google.watchFileChange ​

Register a trigger to track changes to a specific Google Drive file.

Usage ​

js
$io.google.watchFileChange(connectionName, id, fileId, cbFn)

Description ​

This function registers a trigger to monitor a specific file in Google Drive for changes. It periodically compares file metadata to detect edits, renames, folder moves, and trashing/restoration.

Usage Scenarios ​

  • Monitor a specific file for edits, renames, or movement
  • Trigger flows when shared documents are updated or trashed
  • Log or audit changes to important Google Drive files

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection defined in your app. This must refer to a connection configured with Google OAuth2 credentials.

id ​

Type: String

Required: Yes

A unique identifier for this trigger. It is used internally to manage the watch state.

fileId ​

Type: String

Required: Yes

The Google Drive file ID of the file to monitor. Changes to this file will trigger the callback.

cbFn ​

Type: Function

Required: Yes

A callback function invoked when a change is detected on the specified file. The callback receives two parameters:

  1. desc (Object): A structured change descriptor with the following properties:

    • fileId (String): ID of the file
    • fileName (String): Name of the file
    • timestamp (String): ISO timestamp of the last modification
    • action (String): One of 'modified', 'renamed', 'moved', 'trashed', 'restored', or 'none'
    • changes (Array of Strings): List of detected changes, e.g., ['modified', 'name']
    • notes (String): Additional context about the change or state

  2. fileInfo (Object): The full metadata object returned by the Google Drive API for the file.

Output ​

Type: Promise

This function returns a Promise that resolves to an object indicating the status of the trigger setup:

  • status: true if the trigger was registered successfully, false otherwise.
  • data: Information about the tracking token or metadata
  • err: If status is false, contains error details as a string.

$io.google.watchGmailChange ​

Register a trigger to monitor Gmail inbox activity such as new messages or label changes.

Usage ​

js
$io.google.watchGmailChange(connectionName, id, labelIds, cbFn)

Description ​

This function registers a watch for Gmail inbox changes related to message additions and label assignments.

If no label IDs are provided, it monitors all incoming messages.

The callback function receives an object with the following structure: { messagesAdded: [...], // Newly added messages labelsAdded: [...] // Existing messages with new labels }

Each item in 'messagesAdded' or 'labelsAdded' includes:

  • 'id': Unique message ID
  • 'threadId': Thread ID the message belongs to
  • 'labelIds': Array of Gmail label IDs assigned to the message (only present in 'labelsAdded')
  • 'internalDate': Timestamp of when the message was received (in ms)

You can use $io.google.getGmailMessage to fetch the full message content if needed.

Usage Scenarios ​

  • Trigger workflows when new emails arrive
  • Track messages with specific Gmail labels (e.g., 'INBOX', 'IMPORTANT')
  • Build automation rules based on incoming message activity

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for authentication.

id ​

Type: String

Required: Yes

Unique identifier for this watch registration. Required for later removal.

labelIds ​

Type: Array

Required: No

Optional. Array of Gmail label IDs to restrict the watch scope. If omitted or empty, all messages are tracked.

cbFn ​

Type: Function

Required: Yes

Callback function that receives the change object (messagesAdded, labelsAdded). Called once per trigger.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • 'status': true if the watch was registered
  • 'data':
  • 'err': If status is false, contains error details

$io.google.watchNewDriveFiles ​

Register a trigger to detect newly added files in a Google Drive folder (or globally).

Usage ​

js
$io.google.watchNewDriveFiles(connectionName, id, cbFn, parentFolderId)

Description ​

This function sets up a trigger to detect newly added files in Google Drive.

It wraps watchDriveChange and filters for events where the file's action is 'added'. The callback is only called for new file additions, not updates or deletions.

If parentFolderId is provided, only files added under that folder are considered. If left blank, the trigger applies globally to all accessible Drive content.

Usage Scenarios ​

  • Trigger automations when new files are uploaded to a Drive folder
  • Monitor a shared team drive for new documents or uploads
  • Respond to newly created reports, exports, or form responses

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection to use for Drive API authentication.

id ​

Type: String

Required: Yes

A unique identifier for the trigger. Used to manage the watch lifecycle.

cbFn ​

Type: Function

Required: Yes

A callback function invoked only when a new file is added. Receives two arguments:

js
(desc, file)
  • desc: A descriptor object with metadata about the change (includes fileId, action, etc.)
  • file: The full Google Drive file metadata object

parentFolderId ​

Type: String

Required: No

Optional. The ID of the folder to monitor for new files. If omitted, all files are monitored.

Output ​

Type: Promise

Returns a Promise that resolves to an object indicating the outcome:

  • status: true if the watch was successfully registered
  • data: Metadata about the watch registration
  • err: If status is false, contains error details

$io.google.watchNewFoldersInFolder ​

Register a trigger to detect newly added folders inside a specific Google Drive folder.

Usage ​

js
$io.google.watchNewFoldersInFolder(connectionName, id, parentFolderId, cbFn)

Description ​

This function registers a trigger to watch for newly added folders inside a specific Google Drive folder.

It wraps watchDriveChange with a MIME type filter for Google Drive folders and only invokes the callback if the action is 'added'.

Useful for scenarios where folder creation itself is a meaningful event (e.g., new client folder, new intake folder, etc.).

Usage Scenarios ​

  • Monitor a shared folder for new subfolders created by users
  • Trigger workflows when a new client or project folder is added
  • Detect organization of files into new categories automatically

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection used for Drive API access.

id ​

Type: String

Required: Yes

A unique identifier for the watcher, used for managing its lifecycle.

cbFn ​

Type: Function

Required: Yes

A callback invoked only when a new folder is added. Receives:

js
(desc, file)
  • desc: Metadata about the event (e.g., fileId, action)
  • file: Full Google Drive metadata object for the folder

parentFolderId ​

Type: String

Required: Yes

Optional. The ID of the parent folder in which to monitor for new subfolders.

Output ​

Type: Promise

Returns a Promise resolving to:

  • status: true if the watch was registered
  • data: Information about the watch state
  • err: If status is false, contains error details

$io.google.watchSheetChange ​

Register a trigger to track row-level changes in a specific sheet of a Google Sheets file.

Usage ​

js
$io.google.watchSheetChange(connectionName, id, fileId, sheetName, cbFn)

Description ​

This function registers a trigger that monitors a specific sheet (tab) within a Google Sheets file. It compares row-level snapshots over time and invokes the callback when new rows are added or existing rows are modified.

Note: Even a change to a single cell in a row is considered a row-level change and will be detected. If sheetName is omitted, the default (first) sheet in the file is used.

Usage Scenarios ​

  • Detect new rows added to a sheet and trigger workflows
  • Watch for row modifications in a specific tab of a spreadsheet
  • Build automations that respond to structured data entry or edits

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Google connection defined in your app. Must have Sheets and Drive access.

id ​

Type: String

Required: Yes

A unique identifier for this trigger. Used to manage the watch state.

fileId ​

Type: String

Required: Yes

The Google Sheets file ID that contains the target sheet tab.

sheetName ​

Type: String

Required: No

Optional. The name of the sheet tab to monitor. If not specified, the default or first sheet is monitored.

cbFn ​

Type: Function

Required: Yes

A callback function invoked when row-level changes are detected in the sheet. It receives two parameters:

  1. descriptor (Object) — a structured summary of the change:

    • fileId (String): ID of the spreadsheet
    • sheetName (String): Name of the watched sheet (may be undefined if omitted)
    • range (String): A1-style range of the sheet (e.g., 'Sheet1')
    • action (String): One of 'row_added', 'row_modified', 'row_added_and_modified', or 'none'
    • timestamp (Number): Epoch timestamp of the change
    • addedRows (Array of Arrays): Rows appended since the last check
    • modifiedRows (Array of Objects): Changed rows in the form { index, before, after }

  2. newValues (Array of Arrays): The full sheet data after the change (raw values).

Output ​

Type: Promise

Returns a Promise resolving to an object with the registration status:

  • status: true if the trigger was registered successfully, false otherwise
  • data: Snapshot state used for diffing
  • err: If status is false, contains error details as a string