Работа с Google Календарём идёт через функции калькулятора: чат-бот сам ходит в Google API от вашего сервисного аккаунта. Отдельных HTTP-запросов настраивать не нужно.

Что потребуется

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

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

  1. Перейдите в консоль Google Cloud и создайте новый проект.
  2. В разделе APIs & Services → Library найдите Google Calendar API и нажмите Enable. Без этого шага все запросы будут возвращать ошибку.


  3. В разделе IAM & Admin → Service Accounts создайте сервисный аккаунт и выдайте ему роль Owner.


  4. Откройте созданный аккаунт → вкладка Keys → Add key → Create new key → тип JSON.



    Файл с ключом скачается на компьютер.
  5. Запомните адрес сервисного аккаунта — поле client_email внутри скачанного файла, вида bot-calendar@my-project.iam.gserviceaccount.com. Он понадобится, чтобы выдать доступ к календарю.

Куда положить ключ: переменная calendar_json_keys

  1. Загрузите скачанный JSON-файл в файловое хранилище проекта, в котором работаете с google-календарем, и скопируйте ссылку на файл правой кнопкой мыши.
  2. В «Константы проекта» добавьте переменную calendar_json_keys со значением — массивом ключей:

То есть вставляйте скопированную вами ссылку на файл, загруженный в проект с ключом.

["https://files.salebot.pro/uploads/file_item/file/id_вашего_проекта/название_вашего_файла.json"]

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

[
  "https://files.salebot.pro/uploads/file_item/file/id_вашего_проекта/название_вашего_файла.json",
  "https://files.salebot.pro/uploads/file_item/file/id_вашего_проекта/название_вашего_файла.json"
]

Вместо ссылки можно вписать сам ключ целиком (из вашего загруженного файла):

[
  {
    "type": "service_account",
    "project_id": "my-project",
    "private_key": "-----BEGIN PRIVATE KEY-----...",
    "client_email": "bot-calendar@my-project.iam.gserviceaccount.com",
    "..."
  }
]

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

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

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

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

Как узнать идентификатор календаря

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

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

c_a1b2c3@group.calendar.google.com

Идентификаторы всех доступных календарей также отдаёт функция:

gcal_calendars_list()

Как вызывать функции, форматы дат и таймзона

Функции (все ниже перечисленные в том числе) прописываются в калькуляторе в конструкторе чат-ботов.

Результат удобно сразу записать в переменную:

event = gcal_add_event("c_a1b2c3@group.calendar.google.com", "Консультация", "20.08.2026 14:00", "20.08.2026 15:00")

Каждая функция возвращает ответ Google API в формате JSON, а при ошибке:

{"status": false, "err": "описание ошибки"}

Достать нужное поле из ответа можно функцией get.

Например:

get(event, 'id')

Форматы значений

Что Формат Пример
Дата и время dd.mm.yyyy HH:MM 20.08.2026 14:00
Дата (событие на весь день) dd.mm.yyyy 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", "", "manager@gmail.com")

Функция вернёт данные созданного календаря:

{
  "kind": "calendar#calendar",
  "id": "c_a1b2c3@group.calendar.google.com",
  "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("c_a1b2c3@group.calendar.google.com", "Встреча с Иваном завтра в 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("c_a1b2c3@group.calendar.google.com", "Консультация #{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_datetime и end_datetime передайте start_date и end_date через extra_params.

Пример события на весь день, которое повторяется по понедельникам и средам 10 раз:

event = gcal_add_event("c_a1b2c3@group.calendar.google.com", "Вебинар", null, null, "Еженедельный вебинар", "", null, '{"start_date": "01.09.2026", "end_date": "02.09.2026", "recurrence_days": "MO,WE", "recurrence_count": 10}')

В событиях на весь день Google не включает конечную дату в событие. Чтобы занять только 01.09.2026, в end_date нужно передать 02.09.2026.

Ответ при создании события

Функция возвращает созданное событие:

{
  "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("c_a1b2c3@group.calendar.google.com", "#{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 — начало периода в формате dd.mm.yyyy;
  • end_date — конец периода в формате dd.mm.yyyy.

Пример:

events = gcal_get_event_list("c_a1b2c3@group.calendar.google.com", "20.08.2026", "27.08.2026")

Если даты не переданы, функция вернёт события текущих суток:

events = gcal_get_event_list("c_a1b2c3@group.calendar.google.com")

События возвращаются отсортированными по времени начала.

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

Как получить информацию о событии

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

gcal_get_event(calendar_id, event_id)

Функция возвращает все данные события, включая:

  • название;
  • описание;
  • дату и время;
  • место проведения;
  • участников;
  • напоминания;
  • другие параметры события.

Пример:

event = gcal_get_event("c_a1b2c3@group.calendar.google.com", "#{event_id}")

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

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

gcal_move_event(calendar_id, event_id, destination_calendar_id)

где:

  • calendar_id — идентификатор текущего календаря;
  • event_id — идентификатор события;
  • destination_calendar_id — идентификатор календаря, в который нужно перенести событие.

Пример:

event = gcal_move_event("c_a1b2c3@group.calendar.google.com", "#{event_id}", "c_d4e5f6@group.calendar.google.com")

Как удалить событие

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

gcal_remove_event(calendar_id, event_id)

Пример:

result = gcal_remove_event("c_a1b2c3@group.calendar.google.com", "#{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("c_a1b2c3@group.calendar.google.com", "#{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("c_a1b2c3@group.calendar.google.com", "#{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 Cloud не включён Google Calendar API
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 Календаря.

Краткий пример работы

Создадим событие и сохраним его идентификатор:

event = gcal_add_event("c_a1b2c3@group.calendar.google.com", "Консультация #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Телефон клиента: #{phone}", "Zoom", "Europe/Moscow")

event_id = get(event, 'id')

Добавим клиента в созданное событие:

event = gcal_add_client("c_a1b2c3@group.calendar.google.com", "#{event_id}", "#{email}", "#{name}", "Записался через бота")

Если клиент решил перенести запись:

event = gcal_update_event("c_a1b2c3@group.calendar.google.com", "#{event_id}", null, "21.08.2026 16:00", "21.08.2026 17:00")

Если клиент отменил запись:

result = gcal_remove_event("c_a1b2c3@group.calendar.google.com", "#{event_id}")

Ошибки Google API приходят в поле err без изменений. По тексту ошибки можно определить, чего именно не хватает: доступа к календарю, включённого API, корректного ключа, правильного формата даты или существующего события.