Google Календар керується через функції калькулятора: чат-бот спілкується з Google API за допомогою вашого службового акаунта. Немає потреби налаштовувати окремі HTTP-запити.

Вимоги

  1. Проєкт Google Cloud з увімкненим Google Calendar API.
  2. Службовий акаунт для цього проєкту та його ключ у форматі JSON.
  3. Календар, у якому службовий акаунт має дозвіл на зміну подій.

Як створити службовий акаунт і отримати ключ

  1. Перейдіть до Google Cloud Console і створіть новий проєкт.

  1. Перейдіть до APIs & Services → Library, знайдіть Google Calendar API і натисніть Enable. Без цього кроку всі запити повертатимуть помилку.

  1. Перейдіть до IAM & Admin → Service Accounts, створіть службовий акаунт і призначте йому роль Owner.

  1. Відкрийте створений службовий акаунт → вкладка Keys → Add key → Create new key → оберіть JSON.

Файл ключа буде завантажено на ваш комп'ютер.

  1. Збережіть адресу службового акаунта — поле client_email у завантаженому файлі, наприклад [email protected]. Вона знадобиться для надання службовому акаунту доступу до календаря.

Де зберігати ключ: змінна calendar_json_keys

  1. Завантажте отриманий JSON-файл у файлове сховище проєкту, де ви працюєте з Google Календарем, потім клацніть правою кнопкою миші на файлі та скопіюйте його посилання.

  1. У Константах проєкту додайте змінну з назвою calendar_json_keys і встановіть її значення як масив ключів:

Іншими словами, вставте скопійоване посилання на файл ключа, завантажений у ваш проєкт.

["https://files.mavibot.ai/uploads/file_item/file/your_project_id/your_file_name.json"]

Ви можете вказати кілька ключів, наприклад, якщо використовуєте різні проєкти. Для кожного запиту конструктор використає один із них:

[
  "https://files.mavibot.ai/uploads/file_item/file/your_project_id/your_file_name.json",
  "https://files.mavibot.ai/uploads/file_item/file/your_project_id/your_file_name.json"
]

Замість посилання можна надати весь ключ безпосередньо із завантаженого файлу:

[
  {
    "type": "service_account",
    "project_id": "my-project",
    "private_key": "-----BEGIN PRIVATE KEY-----...",
    "client_email": "[email protected]",
    "..."
  }
]

Як надати службовому акаунту доступ до календаря

Відкрийте налаштування потрібного календаря → Share with people or groups → Add people and groups → введіть client_email службового акаунта та надайте дозвіл Make changes to events.

Без цього дозволу Google повертає Not Found, навіть якщо календар існує.

Календар, створений за допомогою gcal_create_calendar, одразу доступний службовому акаунту, тому окремо ділитися ним не потрібно.

Як знайти ID календаря

Відкрийте налаштування календаря → Integrate calendar → Calendar ID.

ID виглядає приблизно так:

[email protected]

Також можна отримати ID усіх доступних календарів за допомогою:

gcal_calendars_list()

Як викликати функції, формати дат і часові пояси

Функції, включно з усіма переліченими нижче, вводяться в калькуляторі в конструкторі чат-бота.

Зручно зберігати результат безпосередньо у змінну:

event = gcal_add_event("[email protected]", "Консультація", "20.08.2026 14:00", "20.08.2026 15:00")

Кожна функція повертає відповідь Google API у форматі JSON. Якщо сталася помилка, відповідь виглядає так:

{"status": false, "err": "опис помилки"}

Ви можете отримати конкретне поле з відповіді за допомогою функції get.

Наприклад:

get(event, 'id')

Формати значень

Значення Формат Приклад
Дата й час дд.мм.рррр гг:хв 20.08.2026 14:00
Дата (подія на весь день) дд.мм.рррр 20.08.2026
Часовий пояс Ідентифікатор IANA Europe/Moscow, Europe/Istanbul

Якщо часовий пояс не вказано, використовується часовий пояс, налаштований у параметрах проєкту.

Календарі

Як створити календар

Використовуйте таку функцію:

gcal_create_calendar(name, description=null, time_zone=null, location=null, owner_email=null)

Параметри:

  • name — назва календаря;
  • description — опис календаря;
  • time_zone — часовий пояс;
  • location — місцезнаходження;
  • owner_email — електронна адреса облікового запису Google, який отримає права власника. Службовий акаунт збереже доступ до календаря.

Приклад:

calendar = gcal_create_calendar("Запис на консультації", "Календар бота", "Europe/Moscow", "", "[email protected]")

Функція повертає дані створеного календаря:

{
  "kind": "calendar#calendar",
  "id": "[email protected]",
  "summary": "Запис на консультації",
  "timeZone": "Europe/Moscow"
}

Збережіть ID з поля id у змінну проєкту — він потрібен усім іншим функціям.

Як отримати інформацію про календар

gcal_get_calendar(calendar_id)

Функція повертає назву календаря, опис, часовий пояс та адресу.

Як отримати список календарів службового акаунта

gcal_calendars_list()

Функція повертає всі календарі, доступні службовому акаунту, разом з їхніми ID.

Як видалити календар

gcal_remove_calendar(calendar_id)

Якщо календар успішно видалено, функція повертає:

{"status": true}

Події

Як швидко додати подію

Використовуйте таку функцію:

gcal_quick_add_event(calendar_id, event_name)

Google автоматично розпізнає дату й час із тексту.

Приклад:

event = gcal_quick_add_event("[email protected]", "Зустріч з Джоном завтра о 15:00")

Як додати подію

Використовуйте таку функцію:

gcal_add_event(calendar_id, event_name, start_datetime=null, end_datetime=null, event_description=null, location=null, time_zone=null, extra_params=null)

Параметри:

  • calendar_id — ID календаря;
  • event_name — назва події;
  • start_datetime — дата й час початку події;
  • end_datetime — дата й час завершення події;
  • event_description — опис події;
  • location — місце проведення події;
  • time_zone — часовий пояс;
  • extra_params — додаткові параметри події у форматі JSON.

Приклад:

event = gcal_add_event("[email protected]", "Консультація #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Телефон клієнта: #{phone}", "Zoom", "Europe/Moscow", '{"popup_minutes": 30, "email_minutes": 60}')

Додаткові параметри extra_params

extra_params — це JSON-об'єкт, що містить необов'язкові параметри:

Параметр Опис
email_minutes Надсилає нагадування електронною поштою за вказану кількість хвилин до події
popup_minutes Показує спливаюче нагадування за вказану кількість хвилин до події
start_date Дата початку для події на весь день
end_date Дата завершення для події на весь день
transparency opaque — час позначено як зайнятий; transparent — час залишається вільним
recurrence_days Дні тижня для щотижневого повторення: MO, TU, WE, TH, FR, SA, SU, розділені комами
recurrence_until Дата, до якої повторюється подія, наприклад 20261231T000000Z
recurrence_count Кількість повторень замість дати завершення

Значення за замовчуванням:

transparency = opaque

Це означає, що час події вважається зайнятим.

Щоб час події залишався вільним:

{"transparency": "transparent"}

Подія на весь день

Для події на весь день передайте start_date та end_date через extra_params замість start_datetime і end_datetime.

Приклад події на весь день, яка повторюється по понеділках і середах 10 разів:

event = gcal_add_event("[email protected]", "Вебінар", null, null, "Щотижневий вебінар", "", null, '{"start_date": "01.09.2026", "end_date": "02.09.2026", "recurrence_days": "MO,WE", "recurrence_count": 10}')

Для подій на весь день Google вважає дату завершення виключною. Щоб створити подію, яка займає лише 01.09.2026, вкажіть 02.09.2026 як end_date.

Відповідь під час створення події

Функція повертає створену подію:

{
  "kind": "calendar#event",
  "id": "7b1k2m3n4o5p",
  "status": "confirmed",
  "htmlLink": "https://www.google.com/calendar/event?eid=..."
}

Збережіть id події у змінну клієнта.

Наприклад:

event_id = get(event, 'id')

ID знадобиться пізніше для оновлення, переміщення або видалення події.

Як оновити подію

Використовуйте таку функцію:

gcal_update_event(calendar_id, event_id, event_name=null, start_datetime=null, end_datetime=null, event_description=null, location=null, time_zone=null, extra_params=null)

Передавайте лише ті поля, які потрібно змінити. Усі інші поля залишаться без змін.

Наприклад, щоб перенести наявну подію на 21.08.2026 з 16:00 до 17:00:

event = gcal_update_event("[email protected]", "#{event_id}", null, "21.08.2026 16:00", "21.08.2026 17:00")

Структура extra_params така сама, як для gcal_add_event.

Нагадування оновлюються за типом.

Наприклад, якщо передати лише:

{"popup_minutes": 30}

спливаюче нагадування буде замінено, а наявне нагадування електронною поштою залишиться без змін.

Як отримати список подій

Використовуйте таку функцію:

gcal_get_event_list(calendar_id, start_date=null, end_date=null)

Параметри:

  • calendar_id — ID календаря;
  • start_date — початок періоду у форматі дд.мм.рррр;
  • end_date — кінець періоду у форматі дд.мм.рррр.

Приклад:

events = gcal_get_event_list("[email protected]", "20.08.2026", "27.08.2026")

Якщо дати не вказано, функція повертає події за поточний день:

events = gcal_get_event_list("[email protected]")

Події повертаються відсортованими за часом початку.

Повторювані події повертаються як окремі записи.

Як отримати інформацію про подію

Використовуйте наступну функцію:

gcal_get_event(calendar_id, event_id)

Функція повертає всі дані події, зокрема:

  • назву;
  • опис;
  • дату та час;
  • місцезнаходження;
  • учасників;
  • нагадування;
  • інші параметри події.

Приклад:

event = gcal_get_event("[email protected]", "#{event_id}")

Як перемістити подію до іншого календаря

Використовуйте наступну функцію:

gcal_move_event(calendar_id, event_id, destination_calendar_id)

де:

  • calendar_id — ID поточного календаря;
  • event_id — ID події;
  • destination_calendar_id — ID календаря, до якого потрібно перемістити подію.

Приклад:

event = gcal_move_event("[email protected]", "#{event_id}", "[email protected]")

Як видалити подію

Використовуйте наступну функцію:

gcal_remove_event(calendar_id, event_id)

Приклад:

result = gcal_remove_event("[email protected]", "#{event_id}")

Якщо подію успішно видалено, функція повертає:

{"status": true}

Учасники події

Як додати учасника

Використовуйте наступну функцію:

gcal_add_client(calendar_id, event_id, client_email, name=null, comment=null)

Параметри:

  • calendar_id — ID календаря;
  • event_id — ID події;
  • client_email — електронна адреса учасника;
  • name — ім'я, яке буде відображатися в календарі;
  • comment — коментар для учасника.

Приклад:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Заброньовано через бота")

Якщо цього учасника вже додано до події, функція повертає помилку:

{"status": false, "err": "attendee already exists"}

Як видалити учасника

Використовуйте наступну функцію:

gcal_remove_client(calendar_id, event_id, client_email)

Параметри:

  • calendar_id — ID календаря;
  • event_id — ID події;
  • client_email — електронна адреса учасника, якого потрібно видалити.

Приклад:

event = gcal_remove_client("[email protected]", "#{event_id}", "#{email}")

Якщо вказаного учасника немає в події, функція повертає:

{"status": false, "err": "attendee not found"}

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

Якщо виникає помилка, функції повертають об'єкт у наступному форматі:

{
  "status": false,
  "err": "опис помилки"
}

Поширені помилки:

Відповідь Причина
Not Found Календар не надано спільний доступ до службового облікового запису або вказано неправильний calendar_id
Google Calendar API has not been used in project ... or it is disabled Google Calendar API не ввімкнено в проєкті Google Cloud
The key to access the calendar was not found in the passed link Посилання в calendar_json_keys не повертає файл ключа
wrong datetime "...", expected format is dd.mm.yyyy HH:MM Дата та час надані в неправильному форматі
wrong date "...", expected format is dd.mm.yyyy Дата надана в неправильному форматі
Работает только на тарифах Бизнес и Инфобиз Проєкт не має активної підписки, яка включає доступ до цієї функції

Помилка Not Found

Якщо Google повертає:

Not Found

перевірте наступне:

  1. Переконайтеся, що calendar_id правильний.
  2. Переконайтеся, що client_email службового облікового запису додано до налаштувань календаря.
  3. Переконайтеся, що службовий обліковий запис має дозвіл Вносити зміни до подій.

Навіть якщо календар існує, Google може повернути Not Found, якщо службовий обліковий запис не має доступу до нього.

Google Calendar API не ввімкнено

Помилка виглядає приблизно так:

Google Calendar API has not been used in project ... or it is disabled

Відкрийте свій проєкт у Google Cloud і ввімкніть:

APIs & Services → Library → Google Calendar API → Enable

Після ввімкнення API повторіть запит.

Ключ службового облікового запису не знайдено

Помилка:

The key to access the calendar was not found in the passed link

Перевірте значення:

calendar_json_keys

Якщо ви використовуєте посилання на файл, воно має безпосередньо повертати JSON-файл, що містить ключ службового облікового запису.

Приклад:

["https://files.salebot.pro/xxxxxxxx/key.json"]

Ви також можете надати ключ безпосередньо в calendar_json_keys як JSON-об'єкт.

Неправильний формат дати та часу

Помилка:

wrong datetime "...", expected format is dd.mm.yyyy HH:MM

Правильний формат:

dd.mm.yyyy HH:MM

Приклад:

20.08.2026 14:00

Неправильні приклади:

2026-08-20 14:00
20/08/2026 14:00
20.08.2026

Якщо функція очікує і дату, і час, ви повинні надати дату разом із годинами та хвилинами.

Неправильний формат дати

Помилка:

wrong date "...", expected format is dd.mm.yyyy

Правильний формат:

dd.mm.yyyy

Приклад:

20.08.2026

Немає відповідного тарифного плану

Помилка:

Работает только на тарифах Бизнес и Инфобиз

Це означає, що проєкт не має активної підписки, яка дозволяє використання функцій Google Calendar.

Швидкий приклад

Створіть подію та збережіть її ID:

event = gcal_add_event("[email protected]", "Консультація #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Телефон клієнта: #{phone}", "Zoom", "Europe/Moscow")

event_id = get(event, 'id')

Додайте клієнта до створеної події:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Заброньовано через бота")

Якщо клієнт вирішив перенести запис:

event = gcal_update_event("[email protected]", "#{event_id}", null, "21.08.2026 16:00", "21.08.2026 17:00")

Якщо клієнт скасовує бронювання:

result = gcal_remove_event("[email protected]", "#{event_id}")

Помилки Google API повертаються без змін у полі err. Повідомлення про помилку допомагає визначити, чого бракує: доступу до календаря, увімкненого API, дійсного ключа, правильного формату дати або існуючої події.