Google Calendar est géré via des fonctions de calculatrice : le chatbot communique avec l'API Google en utilisant votre compte de service. Il n'est pas nécessaire de configurer des requêtes HTTP séparées.

Exigences

  1. Un projet Google Cloud avec l'API Google Calendar activée.
  2. Un compte de service pour ce projet et sa clé au format JSON.
  3. Un calendrier pour lequel le compte de service a la permission de modifier les événements.

Comment créer un compte de service et obtenir une clé

  1. Allez dans la console Google Cloud et créez un nouveau projet.

  1. Allez dans API et services → Bibliothèque, trouvez Google Calendar API, et cliquez sur Activer. Sans cette étape, toutes les requêtes renverront une erreur.

  1. Allez dans IAM et administration → Comptes de service, créez un compte de service et attribuez-lui le rôle Propriétaire.

  1. Ouvrez le compte de service que vous avez créé → onglet Clés → Ajouter une clé → Créer une nouvelle clé → sélectionnez JSON.

Le fichier de clé sera téléchargé sur votre ordinateur.

  1. Enregistrez l'adresse du compte de service — le champ client_email dans le fichier téléchargé, par exemple [email protected]. Vous en aurez besoin pour accorder au compte de service l'accès au calendrier.

Où stocker la clé : variable calendar_json_keys

  1. Téléchargez le fichier JSON téléchargé dans le stockage de fichiers du projet où vous travaillez avec Google Calendar, puis faites un clic droit sur le fichier et copiez son lien.

  1. Dans Constantes du projet, ajoutez une variable nommée calendar_json_keys et définissez sa valeur sur un tableau de clés :

En d'autres termes, collez le lien que vous avez copié pour le fichier de clé téléchargé dans votre projet.

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

Vous pouvez spécifier plusieurs clés, par exemple si vous utilisez différents projets. Pour chaque requête, le constructeur utilisera l'une d'elles :

[
  "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"
]

Au lieu d'un lien, vous pouvez fournir la clé entière directement depuis le fichier téléchargé :

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

Comment accorder au compte de service l'accès à un calendrier

Ouvrez les paramètres du calendrier requis → Partager avec des personnes ou des groupes → Ajouter des personnes et des groupes → saisissez le client_email du compte de service et accordez la permission Apporter des modifications aux événements.

Sans cette permission, Google renvoie Not Found même si le calendrier existe.

Un calendrier créé avec gcal_create_calendar est immédiatement disponible pour le compte de service, vous n'avez donc pas besoin de le partager séparément.

Comment trouver l'ID du calendrier

Ouvrez les paramètres du calendrier → Intégrer le calendrier → ID du calendrier.

L'ID ressemble approximativement à ceci :

[email protected]

Vous pouvez également obtenir les ID de tous les calendriers disponibles en utilisant :

gcal_calendars_list()

Comment appeler les fonctions, formats de date et fuseaux horaires

Les fonctions, y compris toutes celles listées ci-dessous, sont saisies dans la calculatrice du constructeur de chatbot.

Il est pratique d'enregistrer le résultat directement dans une variable :

event = gcal_add_event("[email protected]", "Consultation", "20.08.2026 14:00", "20.08.2026 15:00")

Chaque fonction renvoie la réponse de l'API Google au format JSON. Si une erreur se produit, la réponse ressemble à ceci :

{"status": false, "err": "description de l'erreur"}

Vous pouvez récupérer un champ spécifique de la réponse en utilisant la fonction get.

Par exemple :

get(event, 'id')

Formats de valeurs

Valeur Format Exemple
Date et heure jj.mm.aaaa HH:MM 20.08.2026 14:00
Date (événement sur une journée) jj.mm.aaaa 20.08.2026
Fuseau horaire Identifiant IANA Europe/Moscow, Europe/Istanbul

Si aucun fuseau horaire n'est spécifié, le fuseau horaire configuré dans les paramètres du projet est utilisé.

Calendriers

Comment créer un calendrier

Utilisez la fonction suivante :

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

Paramètres :

  • name — nom du calendrier ;
  • description — description du calendrier ;
  • time_zone — fuseau horaire ;
  • location — lieu ;
  • owner_email — adresse e-mail du compte Google qui recevra les permissions de propriétaire. Le compte de service conservera l'accès au calendrier.

Exemple :

calendar = gcal_create_calendar("Réservations de consultations", "Calendrier du bot", "Europe/Moscow", "", "[email protected]")

La fonction renvoie les données du calendrier créé :

{
  "kind": "calendar#calendar",
  "id": "[email protected]",
  "summary": "Réservations de consultations",
  "timeZone": "Europe/Moscow"
}

Enregistrez l'ID du champ id dans une variable de projet — il est requis par toutes les autres fonctions.

Comment obtenir les informations d'un calendrier

gcal_get_calendar(calendar_id)

La fonction renvoie le nom du calendrier, la description, le fuseau horaire et l'adresse.

Comment obtenir la liste des calendriers du compte de service

gcal_calendars_list()

La fonction renvoie tous les calendriers accessibles au compte de service, avec leurs ID.

Comment supprimer un calendrier

gcal_remove_calendar(calendar_id)

Si le calendrier est supprimé avec succès, la fonction renvoie :

{"status": true}

Événements

Comment ajouter rapidement un événement

Utilisez la fonction suivante :

gcal_quick_add_event(calendar_id, event_name)

Google analysera automatiquement la date et l'heure à partir du texte.

Exemple :

event = gcal_quick_add_event("[email protected]", "Réunion avec Jean demain à 15:00")

Comment ajouter un événement

Utilisez la fonction suivante :

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

Paramètres :

  • calendar_id — ID du calendrier ;
  • event_name — nom de l'événement ;
  • start_datetime — date et heure de début de l'événement ;
  • end_datetime — date et heure de fin de l'événement ;
  • event_description — description de l'événement ;
  • location — lieu de l'événement ;
  • time_zone — fuseau horaire ;
  • extra_params — paramètres supplémentaires de l'événement au format JSON.

Exemple :

event = gcal_add_event("[email protected]", "Consultation #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Téléphone du client : #{phone}", "Zoom", "Europe/Moscow", '{"popup_minutes": 30, "email_minutes": 60}')

Paramètres supplémentaires extra_params

extra_params est un objet JSON contenant des paramètres optionnels :

Paramètre Description
email_minutes Envoie un rappel par e-mail le nombre de minutes spécifié avant l'événement
popup_minutes Affiche un rappel contextuel le nombre de minutes spécifié avant l'événement
start_date Date de début pour un événement sur une journée
end_date Date de fin pour un événement sur une journée
transparency opaque — le temps est marqué comme occupé ; transparent — le temps reste disponible
recurrence_days Jours de la semaine pour la récurrence hebdomadaire : MO, TU, WE, TH, FR, SA, SU, séparés par des virgules
recurrence_until Date jusqu'à laquelle l'événement se répète, par exemple 20261231T000000Z
recurrence_count Nombre d'occurrences au lieu d'une date de fin

La valeur par défaut est :

transparency = opaque

Cela signifie que le temps de l'événement est considéré comme occupé.

Pour garder le temps de l'événement disponible :

{"transparency": "transparent"}

Événement sur une journée

Pour un événement sur une journée, passez start_date et end_date via extra_params au lieu de start_datetime et end_datetime.

Exemple d'un événement sur une journée qui se répète les lundis et mercredis 10 fois :

event = gcal_add_event("[email protected]", "Webinaire", null, null, "Webinaire hebdomadaire", "", null, '{"start_date": "01.09.2026", "end_date": "02.09.2026", "recurrence_days": "MO,WE", "recurrence_count": 10}')

Pour les événements sur une journée, Google traite la date de fin comme exclusive. Pour créer un événement qui n'occupe que le 01.09.2026, spécifiez 02.09.2026 comme end_date.

Réponse lors de la création d'un événement

La fonction renvoie l'événement créé :

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

Enregistrez l'id de l'événement dans une variable client.

Par exemple :

event_id = get(event, 'id')

Vous aurez besoin de l'ID plus tard pour mettre à jour, déplacer ou supprimer l'événement.

Comment mettre à jour un événement

Utilisez la fonction suivante :

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)

Passez uniquement les champs que vous souhaitez modifier. Tous les autres champs resteront inchangés.

Par exemple, pour reprogrammer un événement existant au 21.08.2026 de 16:00 à 17:00 :

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

La structure de extra_params est la même que pour gcal_add_event.

Les rappels sont mis à jour par type.

Par exemple, si vous passez uniquement :

{"popup_minutes": 30}

le rappel contextuel sera remplacé, tandis que le rappel par e-mail existant restera inchangé.

Comment obtenir une liste d'événements

Utilisez la fonction suivante :

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

Paramètres :

  • calendar_id — ID du calendrier ;
  • start_date — début de la période au format jj.mm.aaaa ;
  • end_date — fin de la période au format jj.mm.aaaa.

Exemple :

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

Si aucune date n'est spécifiée, la fonction renvoie les événements du jour courant :

события = gcal_get_event_list("[email protected]")

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

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

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

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

gcal_get_event(calendar_id, event_id)

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

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

Пример:

событие = gcal_get_event("[email protected]", "#{event_id}")

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

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

gcal_move_event(calendar_id, event_id, destination_calendar_id)

где:

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

Пример:

событие = gcal_move_event("[email protected]", "#{event_id}", "[email protected]")

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

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

gcal_remove_event(calendar_id, event_id)

Пример:

результат = 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 — комментарий для участника.

Пример:

событие = 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 — адрес электронной почты участника, которого нужно удалить.

Пример:

событие = 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

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

дд.мм.гггг ЧЧ:ММ

Пример:

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

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

дд.мм.гггг

Пример:

20.08.2026

Нет подходящего тарифного плана

Ошибка:

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

Это означает, что в проекте нет активной подписки, которая позволяет использовать функции Google Calendar.

Быстрый пример

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

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

идентификатор_события = get(событие, 'id')

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

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

Если клиент решит перенести встречу:

событие = gcal_update_event("[email protected]", "#{event_id}", null, "21.08.2026 16:00", "21.08.2026 17:00")

Если клиент отменит бронирование:

результат = gcal_remove_event("[email protected]", "#{event_id}")

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