Действие «Google Календарь»

«Google Календарь» — действие в сценарии действий, которое работает с Google Calendar через сервисный аккаунт: создаёт события, читает расписание, проверяет занятость, синхронизирует напоминания, управляет календарями.

В отличие от внутреннего WebApp Календарь, Google Calendar:

интегрирован с почтой команды (события приходят в Google Calendar менеджера);
виден на телефоне в нативном приложении;
работает с приглашениями (отправляет уведомления участникам);
даёт автогенерацию ссылок Google Meet.

Когда использовать

Задача	Что выбрать
Запись клиента в свой календарь Квесчи	WebApp Календарь
Запись в общий рабочий календарь команды	Google Календарь
Создание события с приглашением по email	Google Календарь
Проверка занятости менеджера	Google Календарь (freebusy)
Автоматическая ссылка Google Meet	Google Календарь

Часть 1. Подготовка — сервисный аккаунт

Та же процедура, что для Google Таблиц:

Google Cloud Console → проект → включить Google Calendar API.
IAM & Admin → Service Accounts → Create → скачать JSON-ключ.
В Google Календаре нужного человека/команды:
- Настройки и общий доступ → Поделиться → добавить email сервисного аккаунта с правами «Внесение изменений в мероприятия»;
Скопировать ID календаря (в настройках, формата email@group.calendar.google.com).

Часть 2. Подключение

Шаг 1. Добавьте действие

В сценарии действий → «Добавить действие» → «Google Календарь».

Шаг 2. Сервисный аккаунт

Поле «Сервисный аккаунт» — вставьте JSON-ключ.

Шаг 3. Выберите операцию

В выпадающем списке «Выберите операцию» — 13 операций (см. далее).

Действие Google Календарь

Скриншот 1. Подключение и выбор операции.

Часть 3. Операции с событиями

Операция	Назначение
Событие: получить (`eventget`)	Достать одно событие по ID
Событие: добавить (`eventinsert`)	Создать событие
Событие: удалить (`eventdelete`)	Удалить по ID
Событие: изменить (`eventupdate`)	Обновить существующее
Событие: получить список (`eventlist`)	Получить массив событий из календаря (с фильтрами)
Событие: перенести в другой календарь (`eventmove`)	Перенос между календарями
Событие: настройка уведомлений (`eventwebhook`)	Подписаться на изменения
Событие: обновление уведомлений (`eventwebhookrenew`)	Продлить подписку
Событие: синхронизация (`eventwebhooksync`)	Полная синхронизация изменений

Операции с событиями

Скриншот 2. Список операций.

Параметры операции «Добавить»

Поле	Значение
ID Календаря	`primary` или `xxx@group.calendar.google.com`
Название события	«Консультация с `#{client_name}`»
Описание	Произвольный текст
Дата начала	`[CurrentDate] [CurrentTime]` или из переменной
Дата окончания	Через [AddMinutes(...)] или явно
Часовой пояс	`Europe/Moscow`, `Asia/Almaty` и т.д.
Местоположение	Адрес, ссылка Zoom или Google Meet
Участники (emails)	Через запятую — отправятся приглашения
Google Meet	Галочка — автогенерация ссылки видеовстречи

После создания возвращается ID события в переменную — используйте для обновления/удаления.

Часть 4. Проверка занятости (`freebusy`)

Возвращает свободные/занятые интервалы:

Поле	Значение
ID Календаря	Чей календарь проверяем
Период начало	`2026-08-21T09:00:00+03:00`
Период конец	`2026-08-21T18:00:00+03:00`

В переменную сохранятся массивы занятых интервалов. По ним строится логика «свободно ли время».

Применение

Клиент выбирает время → переменная `#{requested_time}`
Действие Google Календарь → freebusy →
  Если занят → блок «К сожалению, занято. Выберите другое»
  Если свободен → создать событие eventinsert + подтвердить клиенту

Часть 5. Операции с календарями

Операция	Назначение
Календарь: получить (`calget`)	Метаданные календаря
Календарь: добавить (`calinsert`)	Создать новый календарь
Календарь: удалить (`caldelete`)	Удалить календарь
Календарь: изменить (`calupdate`)	Обновить название, часовой пояс

Используется редко — обычно достаточно операций с событиями в существующем календаре.

Часть 6. Уведомления (вебхуки)

Операция	Назначение
Событие: настройка уведомлений (`eventwebhook`)	Подписаться на изменения событий — Квесча будет получать уведомления
Событие: обновление уведомлений (`eventwebhookrenew`)	Продлить подписку (Google требует обновлять)
Событие: синхронизация (`eventwebhooksync`)	Получить все изменения с последней синхронизации

Полезно для двусторонней синхронизации: если менеджер вручную меняет событие в Google Calendar — бот узнаёт и реагирует (например, уведомляет клиента о переносе).

Часть 7. Списки календарей

Списки: получить все (listlist) — массив всех календарей, к которым у сервисного аккаунта есть доступ.

Полезно для:

админских инструментов («покажи все мои календари»);
проверки настройки доступа.

Часть 8. Типовые сценарии

Сценарий 1. Запись клиента в календарь менеджера

Блок 1. «Выберите дату»
  → переменные `#{event_date}`, `#{event_time}`
Блок 2. Проверка занятости
  Сценарий действий «До»:
    - Google Календарь → freebusy →
      start = "`#{event_date}`T`#{event_time}`:00+03:00"
      end = [AddMinutes(start,60)]
      → переменная `#{busy}`
    - Если `#{busy}` > 0 → переход на блок «Занято»
  Сообщение: «Время свободно, подтверждаете?»
  Кнопка «Да» → блок 3
Блок 3. Создание события
  Сценарий действий «До»:
    - Google Календарь → eventinsert:
      calendar_id = manager@gmail.com
      summary = "Консультация с [Name]"
      description = "Телефон: `#{client_phone}`, Запрос: [Answer1]"
      start = "`#{event_date}`T`#{event_time}`:00+03:00"
      end = [AddMinutes(start,60)]
      attendees = `#{client_email}`, manager@gmail.com
      meet = true (Google Meet ссылка)
      → сохранить event_id, meet_link
  Сообщение: «✅ Записаны на `#{event_date}` `#{event_time}`
              Ссылка: `#{meet_link}`»

Сценарий 2. Отмена и уведомление

Блок «Мои записи» → клиент выбирает запись
Действие Google Календарь → eventget(event_id) → данные
Подтверждение → eventdelete(event_id)
+ Сообщение менеджеру через [Группы Telegram](dejstvie-tgchannel.md)

Сценарий 3. Списать с менеджера, добавить себе

Перенос события: операция eventmove — для перехода клиента к другому менеджеру.

Сценарий 4. Расписание дня для менеджера

Команда /today для менеджера
  Сценарий действий «До»:
    - Google Календарь → eventlist:
      calendar_id = [Self]
      timeMin = [CurrentDate]T00:00:00
      timeMax = [CurrentDate]T23:59:59
      → массив events
    - Перебор → формирование строки в `#{schedule_text}`
  Сообщение: «Расписание на сегодня:
              `#{schedule_text}`»

Сценарий 5. Уведомление клиенту о переносе

Менеджер в Google Calendar изменил время события
  ↓ webhook → eventwebhook
Цепочка «Перенос события»
  Действие «До»:
    - Google Календарь → eventwebhooksync → изменения
    - JS код: разобрать, найти затронутого клиента
  Сообщение клиенту: «Время вашей встречи изменилось на `#{new_time}`»

Часть 9. Архитектура

Принцип 1. ID календарей — в глобальные переменные

g_calendar_main, g_calendar_meet_room — храните там. Один calendar_id на проект.

Принцип 2. Часовой пояс — обязательно

Без timeZone событие может создаться на UTC и клиент придёт за 3 часа до встречи. Всегда указывайте Europe/Moscow или своё.

Принцип 3. Google Meet — для онлайна

При создании события включайте опцию Google Meet — ссылка генерируется автоматически и приходит участникам.

Принцип 4. Приглашения через `attendees`

При указании email-ов клиента и менеджера Google сам отправит им письма-приглашения. Это лучше, чем самому копировать ссылку и отправлять через бот.

Принцип 5. Резервируйте сохранением в список

ID Google-события сохраняйте в локальный список «Записи». Если Google API упал — у вас есть запись.

Принцип 6. WebApp Календарь vs Google Календарь

Используйте WebApp Календарь для UX клиента (выбор слота). Используйте Google Календарь для расписания внутри команды (менеджер видит в своём календаре). Оптимально — оба вместе.

Часть 10. Сравнение с WebApp Календарь

	WebApp Календарь	Google Календарь
UX выбора слота	Отличный	Нет (внешний)
Видно клиенту	✓	✗
Видно команде в Google Calendar	✗	✓
Уведомления клиенту	Встроенные	Через email
Приглашение по email	✗	✓
Google Meet ссылка	✗	✓
Совместимость с CRM команды	Через интеграцию	Натив

Рекомендация: WebApp Календарь для записи, Google Календарь — для отображения у менеджеров.

Частые ошибки

403 Forbidden — не дали сервисному аккаунту доступ к календарю (нужно «Внесение изменений»).
Событие на 3 часа раньше — забыли указать timeZone, попало в UTC.
Гости не получают приглашение — поле attendees пустое или нет права у сервисного аккаунта приглашать.
Меняешь событие, а оно дублируется — используете eventinsert вместо eventupdate. Сохраните event_id при создании.
freebusy возвращает только основные события — события вне основного календаря могут не учитываться. Указывайте calendar_id явно.
Webhook подписки истекают — Google требует обновления каждые ~7 дней через eventwebhookrenew.

Что дальше

WebApp Календарь — для записи клиентов через мессенджер.
Google Таблицы — для отчётов и каталога.
Google Диск — хранение документов.
Списки — резерв записей.
Шаблоны — [CurrentDate], [CurrentTime], [AddDate], [AddMinutes] для дат.

Когда использовать​

Часть 1. Подготовка — сервисный аккаунт​

Часть 2. Подключение​

Шаг 1. Добавьте действие​

Шаг 2. Сервисный аккаунт​

Шаг 3. Выберите операцию​

Часть 3. Операции с событиями​

Параметры операции «Добавить»​

Часть 4. Проверка занятости (freebusy)​

Применение​

Часть 5. Операции с календарями​

Часть 6. Уведомления (вебхуки)​

Часть 7. Списки календарей​

Часть 8. Типовые сценарии​

Сценарий 1. Запись клиента в календарь менеджера​

Сценарий 2. Отмена и уведомление​

Сценарий 3. Списать с менеджера, добавить себе​

Сценарий 4. Расписание дня для менеджера​

Сценарий 5. Уведомление клиенту о переносе​

Часть 9. Архитектура​

Принцип 1. ID календарей — в глобальные переменные​

Принцип 2. Часовой пояс — обязательно​

Принцип 3. Google Meet — для онлайна​

Принцип 4. Приглашения через attendees​

Принцип 5. Резервируйте сохранением в список​

Принцип 6. WebApp Календарь vs Google Календарь​

Часть 10. Сравнение с WebApp Календарь​

Частые ошибки​

Что дальше​