Дії Google

Отримати події з Calendar

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

Читає події з основного Google Календаря у заданому діапазоні часу. Корисно для пошуку вільних слотів, щоденних дайджестів або будь-якого flow що реагує на ваш розклад.

Входи

Вхід	Тип	Опис
timeMin	string	Опціональний ISO 8601 datetime — повертати лише події що закінчуються після цього часу. Наприклад `2026-06-01T00:00:00+03:00` або `2026-06-01T00:00:00Z`. Без нього — всі майбутні події.
timeMax	string	Опціональний ISO 8601 datetime — повертати лише події що починаються до цього часу.
q	string	Опціональний текстовий пошук по назві / опису / учасниках.
maxResults	string	Опціонально. За замовчуванням 100, максимум 250 (ліміт Google на сторінку).

Виходи

Вихід	Тип	Опис
events	json	JSON-масив спрощених event-об'єктів (схема нижче). Порожній масив (`[]`) якщо немає збігів.
count	number	Кількість повернутих подій (0..maxResults).
error	string	Порожній при успіху. Містить повідомлення Google при статусі ERROR.

Схема елементу `events`

Кожен елемент масиву events урізаний до полів які реально використовуються у flow:

{
  "id": "string",
  "summary": "string",
  "description": "string",
  "location": "string",
  "htmlLink": "string",
  "start": "ISO 8601 (або date для повноденних)",
  "end": "ISO 8601 (або date для повноденних)",
  "attendees": ["email1", "email2"]
}

Для повноденних подій Google повертає тільки дату — start / end тоді мають формат "2026-06-15".

Щоб використати окремі події у flow, розпарсте JSON через JSON-функцію та проітеруйте через List або forEach.

Необхідні дозволи

Дія потребує capability Manage Calendar events на Google-з'єднанні (OAuth scope calendar.events). Той самий scope який використовує Create Event покриває й читання.

Сортування й повторювані події

Дія завжди шле singleEvents=true&orderBy=startTime, тому:

Повторювані події (recurring) розгортаються в окремі екземпляри.
Результати відсортовані за start.dateTime за зростанням — найраніша спочатку.

Приклади використання

Пошук вільних слотів на завтра — timeMin = завтра 09:00, timeMax = завтра 18:00, далі обчислити гепи між events і запропонувати слоти для зустрічі.
Щоденний дайджест о 7 ранку — отримати події на сьогодні й надіслати в Telegram або Email.
Перевірка конфлікту перед Create Event — отримати події на запитуваний слот; якщо count > 0, відмовити або попередити.

Можливі помилки

`error` output	Що означає
`Insufficient Permission`	З'єднанню не вистачає `calendar.events`. Перепідключіть з відміченою галкою.
`Calendar listEvents failed: 400` / `Invalid value` (або подібне)	Один з `timeMin` / `timeMax` має невалідний формат — потрібен ISO 8601.
`Google connection has been revoked — reconnect it from the Connections page.`	Користувач відкликав Fainflow зі свого Google-акаунта, або refresh token протух.