Google Actions

List Calendar Events

Tell user how busy their week is

Bot command → list this week's events → reply with the count

Telegram Bot

Bot Update

userID

Google

List Calendar Events

timeMin
2026-06-01T00:00:00Z
timeMax
2026-06-08T00:00:00Z
events
count

Telegram Bot

Send Message

chatId
userID
text
count

Read events from your primary Google Calendar in a time range. Useful for finding free slots, sending daily digests, or any flow that needs to react to your schedule.

Inputs

InputTypeDescription
timeMinstringOptional ISO 8601 datetime — only return events ending after this time. E.g. 2026-06-01T00:00:00+03:00 or 2026-06-01T00:00:00Z. Without it, all upcoming events come back.
timeMaxstringOptional ISO 8601 datetime — only return events starting before this time.
qstringOptional free-text search across event title / description / attendees.
maxResultsstringOptional. Defaults to 100, capped at 250 (Google's per-page limit).

Outputs

OutputTypeDescription
eventsjsonJSON-encoded array of simplified event objects — see schema below. Empty array ([]) when no matches.
countnumberNumber of events returned (0..maxResults).
errorstringEmpty on success. Contains Google's error message when status is ERROR.

events element schema

Each entry in the events array is stripped down to fields a flow author actually uses:

{
  "id": "string",
  "summary": "string",
  "description": "string",
  "location": "string",
  "htmlLink": "string",
  "start": "ISO 8601 (or all-day date)",
  "end": "ISO 8601 (or all-day date)",
  "attendees": ["email1", "email2"]
}

For all-day events Google omits the time and returns just a date — start / end are then date-only strings (e.g. "2026-06-15").

To use individual events in a flow, parse the JSON with a JSON function and iterate with a List or forEach action.

Permissions required

This action needs the Manage Calendar events capability on the Google connection (OAuth scope calendar.events). The same scope used by Create Event covers reads.

Sorting and recurring events

The action always passes singleEvents=true&orderBy=startTime, so:

  • Recurring events are expanded into their concrete instances.
  • Results are sorted by start.dateTime ascending — earliest first.

Example use cases

  • Find free slots tomorrow — set timeMin = tomorrow 09:00, timeMax = tomorrow 18:00, then compute gaps in events to suggest meeting times.
  • Daily digest at 7am — list today's events and send via Telegram or Email.
  • Conflict check before Create Event — list events for the requested slot; if count > 0, refuse or warn.

Errors you might see

error outputMeaning
Insufficient PermissionConnection lacks calendar.events. Reconnect with the box checked.
Calendar listEvents failed: 400 / Invalid value (or similar)One of timeMin / timeMax is malformed — must be ISO 8601.
Google connection has been revoked — reconnect it from the Connections page.The user revoked Fainflow on Google's side, or refresh token expired.