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]",
    "..."
  }
]

Как предоставить сервисному аккаунту доступ к календарю

Откройте настройки нужного календаря → Поделиться с людьми или группами → Добавить людей и группы → введите client_email сервисного аккаунта и предоставьте разрешение Вносить изменения в события.

Без этого разрешения Google возвращает Not Found, даже если календарь существует.

Календарь, созданный с помощью gcal_create_calendar, сразу доступен сервисному аккаунту, поэтому отдельно делиться им не нужно.

Как найти идентификатор календаря

Откройте настройки календаря → Интеграция календаря → Идентификатор календаря.

Идентификатор выглядит примерно так:

[email protected]

Вы также можете получить идентификаторы всех доступных календарей с помощью:

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 в переменную проекта — он требуется всем остальным функциям.

Как получить информацию о календаре

gcal_get_calendar(calendar_id)

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

Как получить список календарей сервисного аккаунта

gcal_calendars_list()

Функция возвращает все календари, доступные сервисному аккаунту, вместе с их идентификаторами.

Как удалить календарь

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 — идентификатор календаря;
  • 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')

Идентификатор понадобится позже для обновления, перемещения или удаления события.

Как обновить событие

Используйте следующую функцию:

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 — идентификатор календаря;
  • 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 — идентификатор текущего календаря;
  • event_id — идентификатор события;
  • destination_calendar_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 — идентификатор календаря;
  • event_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 — идентификатор календаря;
  • event_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, действительного ключа, правильного формата даты или существующего события.