Google Kalender

Google Kalender wird über Rechnerfunktionen verwaltet: Der Chatbot kommuniziert über Ihr Dienstkonto mit der Google API. Es ist nicht erforderlich, separate HTTP-Anfragen zu konfigurieren.

Anforderungen

Ein Google Cloud-Projekt mit aktivierter Google Kalender API.
Ein Dienstkonto für dieses Projekt und dessen Schlüssel im JSON-Format.
Ein Kalender, für den das Dienstkonto die Berechtigung zum Ändern von Ereignissen hat.

So erstellen Sie ein Dienstkonto und erhalten einen Schlüssel

Gehen Sie zur Google Cloud Console und erstellen Sie ein neues Projekt.

Gehen Sie zu APIs & Dienste → Bibliothek, suchen Sie Google Kalender API und klicken Sie auf Aktivieren. Ohne diesen Schritt geben alle Anfragen einen Fehler zurück.

Gehen Sie zu IAM & Verwaltung → Dienstkonten, erstellen Sie ein Dienstkonto und weisen Sie ihm die Rolle Inhaber zu.

Öffnen Sie das erstellte Dienstkonto → Registerkarte Schlüssel → Schlüssel hinzufügen → Neuen Schlüssel erstellen → wählen Sie JSON.

Die Schlüsseldatei wird auf Ihren Computer heruntergeladen.

Speichern Sie die Dienstkonto-Adresse – das Feld client_email in der heruntergeladenen Datei, z. B. [email protected]. Sie benötigen sie, um dem Dienstkonto Zugriff auf den Kalender zu gewähren.

Wo der Schlüssel gespeichert wird: Variable `calendar_json_keys`

Laden Sie die heruntergeladene JSON-Datei in den Dateispeicher des Projekts hoch, in dem Sie mit Google Kalender arbeiten, klicken Sie dann mit der rechten Maustaste auf die Datei und kopieren Sie ihren Link.

Fügen Sie unter Projektkonstanten eine Variable mit dem Namen calendar_json_keys hinzu und setzen Sie ihren Wert auf ein Array von Schlüsseln:

Mit anderen Worten: Fügen Sie den Link ein, den Sie für die in Ihrem Projekt hochgeladene Schlüsseldatei kopiert haben.

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

Sie können mehrere Schlüssel angeben, z. B. wenn Sie verschiedene Projekte verwenden. Für jede Anfrage verwendet der Builder einen davon:

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

Statt eines Links können Sie den gesamten Schlüssel direkt aus der hochgeladenen Datei angeben:

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

So gewähren Sie dem Dienstkonto Zugriff auf einen Kalender

Öffnen Sie die Einstellungen des gewünschten Kalenders → Für Personen oder Gruppen freigeben → Personen und Gruppen hinzufügen → geben Sie die client_email des Dienstkontos ein und erteilen Sie die Berechtigung Änderungen an Ereignissen vornehmen.

Ohne diese Berechtigung gibt Google Not Found zurück, selbst wenn der Kalender existiert.

Ein mit gcal_create_calendar erstellter Kalender ist sofort für das Dienstkonto verfügbar, sodass Sie ihn nicht separat freigeben müssen.

So finden Sie die Kalender-ID

Öffnen Sie die Kalendereinstellungen → Kalender integrieren → Kalender-ID.

Die ID sieht ungefähr so aus:

[email protected]

Sie können die IDs aller verfügbaren Kalender auch mit folgendem Befehl abrufen:

gcal_calendars_list()

So rufen Sie Funktionen auf, Datumsformate und Zeitzonen

Funktionen, einschließlich aller unten aufgeführten Funktionen, werden im Rechner im Chatbot-Builder eingegeben.

Es ist praktisch, das Ergebnis direkt in einer Variable zu speichern:

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

Jede Funktion gibt die Antwort der Google API im JSON-Format zurück. Wenn ein Fehler auftritt, sieht die Antwort so aus:

{"status": false, "err": "Fehlerbeschreibung"}

Sie können ein bestimmtes Feld aus der Antwort mit der Funktion get abrufen.

Zum Beispiel:

get(event, 'id')

Wertformate

Wert	Format	Beispiel
Datum und Uhrzeit	`dd.mm.yyyy HH:MM`	`20.08.2026 14:00`
Datum (ganztägiges Ereignis)	`dd.mm.yyyy`	`20.08.2026`
Zeitzone	IANA-Bezeichner	`Europe/Moscow`, `Europe/Istanbul`

Wenn keine Zeitzone angegeben ist, wird die in den Projekteinstellungen konfigurierte Zeitzone verwendet.

Kalender

So erstellen Sie einen Kalender

Verwenden Sie die folgende Funktion:

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

Parameter:

name – Kalendername;
description – Kalenderbeschreibung;
time_zone – Zeitzone;
location – Standort;
owner_email – E-Mail-Adresse des Google-Kontos, das Inhaberberechtigungen erhält. Das Dienstkonto behält den Zugriff auf den Kalender.

Beispiel:

calendar = gcal_create_calendar("Konsultationstermine", "Bot-Kalender", "Europe/Moscow", "", "[email protected]")

Die Funktion gibt die erstellten Kalenderdaten zurück:

{
  "kind": "calendar#calendar",
  "id": "[email protected]",
  "summary": "Konsultationstermine",
  "timeZone": "Europe/Moscow"
}

Speichern Sie die ID aus dem Feld id in einer Projektvariable – sie wird von allen anderen Funktionen benötigt.

So erhalten Sie Kalenderinformationen

gcal_get_calendar(calendar_id)

Die Funktion gibt den Kalendernamen, die Beschreibung, die Zeitzone und die Adresse zurück.

So erhalten Sie die Kalenderliste des Dienstkontos

gcal_calendars_list()

Die Funktion gibt alle für das Dienstkonto zugänglichen Kalender mit ihren IDs zurück.

So löschen Sie einen Kalender

gcal_remove_calendar(calendar_id)

Wenn der Kalender erfolgreich gelöscht wird, gibt die Funktion Folgendes zurück:

{"status": true}

Ereignisse

So fügen Sie schnell ein Ereignis hinzu

Verwenden Sie die folgende Funktion:

gcal_quick_add_event(calendar_id, event_name)

Google analysiert automatisch Datum und Uhrzeit aus dem Text.

Beispiel:

event = gcal_quick_add_event("[email protected]", "Treffen mit John morgen um 15:00")

So fügen Sie ein Ereignis hinzu

Verwenden Sie die folgende Funktion:

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

Parameter:

calendar_id – Kalender-ID;
event_name – Ereignisname;
start_datetime – Startdatum und -uhrzeit des Ereignisses;
end_datetime – Enddatum und -uhrzeit des Ereignisses;
event_description – Ereignisbeschreibung;
location – Ereignisort;
time_zone – Zeitzone;
extra_params – zusätzliche Ereignisparameter im JSON-Format.

Beispiel:

event = gcal_add_event("[email protected]", "Konsultation #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Kundentelefon: #{phone}", "Zoom", "Europe/Moscow", '{"popup_minutes": 30, "email_minutes": 60}')

Zusätzliche `extra_params`-Parameter

extra_params ist ein JSON-Objekt, das optionale Parameter enthält:

Parameter	Beschreibung
`email_minutes`	Sendet eine E-Mail-Erinnerung die angegebene Anzahl von Minuten vor dem Ereignis
`popup_minutes`	Zeigt eine Popup-Erinnerung die angegebene Anzahl von Minuten vor dem Ereignis
`start_date`	Startdatum für ein ganztägiges Ereignis
`end_date`	Enddatum für ein ganztägiges Ereignis
`transparency`	`opaque` – Zeit wird als belegt markiert; `transparent` – Zeit bleibt verfügbar
`recurrence_days`	Wochentage für wöchentliche Wiederholung: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, `SU`, durch Kommas getrennt
`recurrence_until`	Datum, bis zu dem das Ereignis wiederholt wird, z. B. `20261231T000000Z`
`recurrence_count`	Anzahl der Vorkommen statt eines Enddatums

Der Standardwert ist:

transparency = opaque

Das bedeutet, dass die Ereigniszeit als belegt gilt.

Um die Ereigniszeit verfügbar zu halten:

{"transparency": "transparent"}

Ganztägiges Ereignis

Für ein ganztägiges Ereignis übergeben Sie start_date und end_date über extra_params anstelle von start_datetime und end_datetime.

Beispiel für ein ganztägiges Ereignis, das montags und mittwochs 10 Mal wiederholt wird:

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

Bei ganztägigen Ereignissen behandelt Google das Enddatum als exklusiv. Um ein Ereignis zu erstellen, das nur den 01.09.2026 belegt, geben Sie 02.09.2026 als end_date an.

Antwort beim Erstellen eines Ereignisses

Die Funktion gibt das erstellte Ereignis zurück:

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

Speichern Sie die Ereignis-id in einer Client-Variable.

Zum Beispiel:

event_id = get(event, 'id')

Sie benötigen die ID später, um das Ereignis zu aktualisieren, zu verschieben oder zu löschen.

So aktualisieren Sie ein Ereignis

Verwenden Sie die folgende Funktion:

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)

Übergeben Sie nur die Felder, die Sie ändern möchten. Alle anderen Felder bleiben unverändert.

Um beispielsweise ein vorhandenes Ereignis auf den 21.08.2026 von 16:00 bis 17:00 zu verschieben:

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

Die Struktur von extra_params ist dieselbe wie bei gcal_add_event.

Erinnerungen werden nach Typ aktualisiert.

Wenn Sie beispielsweise nur Folgendes übergeben:

{"popup_minutes": 30}

wird die Popup-Erinnerung ersetzt, während die vorhandene E-Mail-Erinnerung unverändert bleibt.

So erhalten Sie eine Liste von Ereignissen

Verwenden Sie die folgende Funktion:

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

Parameter:

calendar_id – Kalender-ID;
start_date – Beginn des Zeitraums im Format dd.mm.yyyy;
end_date – Ende des Zeitraums im Format dd.mm.yyyy.

Beispiel:

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

Wenn keine Daten angegeben sind, gibt die Funktion Ereignisse für den aktuellen Tag zurück:

events = gcal_get_event_list("[email protected]")

Ereignisse werden nach Startzeit sortiert zurückgegeben.

Wiederkehrende Ereignisse werden als separate Einträge zurückgegeben.

So erhalten Sie Ereignisinformationen

Verwenden Sie die folgende Funktion:

gcal_get_event(calendar_id, event_id)

Die Funktion gibt alle Ereignisdaten zurück, einschließlich:

Name;
Beschreibung;
Datum und Uhrzeit;
Ort;
Teilnehmer;
Erinnerungen;
andere Ereignisparameter.

Beispiel:

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

So verschieben Sie ein Ereignis in einen anderen Kalender

Verwenden Sie die folgende Funktion:

gcal_move_event(calendar_id, event_id, destination_calendar_id)

wobei:

calendar_id — ID des aktuellen Kalenders;
event_id — Ereignis-ID;
destination_calendar_id — ID des Kalenders, in den das Ereignis verschoben werden soll.

Beispiel:

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

So löschen Sie ein Ereignis

Verwenden Sie die folgende Funktion:

gcal_remove_event(calendar_id, event_id)

Beispiel:

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

Wenn das Ereignis erfolgreich gelöscht wird, gibt die Funktion Folgendes zurück:

{"status": true}

Ereignisteilnehmer

So fügen Sie einen Teilnehmer hinzu

Verwenden Sie die folgende Funktion:

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

Parameter:

calendar_id — Kalender-ID;
event_id — Ereignis-ID;
client_email — E-Mail-Adresse des Teilnehmers;
name — der Name, der im Kalender angezeigt wird;
comment — ein Kommentar für den Teilnehmer.

Beispiel:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Über den Bot gebucht")

Wenn dieser Teilnehmer bereits zum Ereignis hinzugefügt wurde, gibt die Funktion einen Fehler zurück:

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

So entfernen Sie einen Teilnehmer

Verwenden Sie die folgende Funktion:

gcal_remove_client(calendar_id, event_id, client_email)

Parameter:

calendar_id — Kalender-ID;
event_id — Ereignis-ID;
client_email — E-Mail-Adresse des zu entfernenden Teilnehmers.

Beispiel:

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

Wenn der angegebene Teilnehmer nicht im Ereignis ist, gibt die Funktion Folgendes zurück:

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

Mögliche Fehler

Wenn ein Fehler auftritt, geben die Funktionen ein Objekt im folgenden Format zurück:

{
  "status": false,
  "err": "Fehlerbeschreibung"
}

Häufige Fehler:

Antwort	Ursache
`Not Found`	Der Kalender wurde nicht mit dem Dienstkonto geteilt, oder eine falsche `calendar_id` wurde angegeben
`Google Calendar API has not been used in project ... or it is disabled`	Die Google Calendar API ist im Google Cloud-Projekt nicht aktiviert
`The key to access the calendar was not found in the passed link`	Der Link in `calendar_json_keys` gibt die Schlüsseldatei nicht zurück
`wrong datetime "...", expected format is dd.mm.yyyy HH:MM`	Datum und Uhrzeit wurden in einem falschen Format angegeben
`wrong date "...", expected format is dd.mm.yyyy`	Das Datum wurde in einem falschen Format angegeben
`Работает только на тарифах Бизнес и Инфобиз`	Das Projekt hat kein aktives Abonnement, das Zugriff auf diese Funktion beinhaltet

`Not Found`-Fehler

Wenn Google Folgendes zurückgibt:

Not Found

überprüfen Sie Folgendes:

Stellen Sie sicher, dass die calendar_id korrekt ist.
Stellen Sie sicher, dass die client_email des Dienstkontos zu den Kalendereinstellungen hinzugefügt wurde.
Stellen Sie sicher, dass das Dienstkonto die Berechtigung Änderungen an Ereignissen vornehmen hat.

Selbst wenn der Kalender existiert, kann Google Not Found zurückgeben, wenn das Dienstkonto keinen Zugriff darauf hat.

Google Calendar API ist nicht aktiviert

Der Fehler sieht ungefähr so aus:

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

Öffnen Sie Ihr Projekt in Google Cloud und aktivieren Sie:

APIs & Dienste → Bibliothek → Google Calendar API → Aktivieren

Nachdem Sie die API aktiviert haben, wiederholen Sie die Anfrage.

Dienstkontoschlüssel nicht gefunden

Fehler:

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

Überprüfen Sie den Wert von:

calendar_json_keys

Wenn Sie einen Dateilink verwenden, muss dieser direkt die JSON-Datei mit dem Dienstkontoschlüssel zurückgeben.

Beispiel:

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

Sie können den Schlüssel auch direkt in calendar_json_keys als JSON-Objekt angeben.

Falsches Datums- und Uhrzeitformat

Fehler:

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

Richtiges Format:

dd.mm.yyyy HH:MM

Beispiel:

20.08.2026 14:00

Falsche Beispiele:

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

Wenn die Funktion sowohl Datum als auch Uhrzeit erwartet, müssen Sie das Datum zusammen mit Stunden und Minuten angeben.

Falsches Datumsformat

Fehler:

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

Richtiges Format:

dd.mm.yyyy

Beispiel:

20.08.2026

Kein geeigneter Abonnementplan

Fehler:

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

Dies bedeutet, dass das Projekt kein aktives Abonnement hat, das die Nutzung der Google-Kalenderfunktionen ermöglicht.

Kurzbeispiel

Erstellen Sie ein Ereignis und speichern Sie seine ID:

event = gcal_add_event("[email protected]", "Beratung #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Kundentelefon: #{phone}", "Zoom", "Europe/Moscow")

event_id = get(event, 'id')

Fügen Sie den Kunden zum erstellten Ereignis hinzu:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Über den Bot gebucht")

Wenn der Kunde umbuchen möchte:

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

Wenn der Kunde die Buchung storniert:

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

Google-API-Fehler werden unverändert im Feld err zurückgegeben. Die Fehlermeldung hilft festzustellen, was fehlt: Kalenderzugriff, aktivierte API, ein gültiger Schlüssel, das richtige Datumsformat oder ein vorhandenes Ereignis.

Google Kalender

Anforderungen

So erstellen Sie ein Dienstkonto und erhalten einen Schlüssel

Wo der Schlüssel gespeichert wird: Variable calendar_json_keys

So gewähren Sie dem Dienstkonto Zugriff auf einen Kalender

So finden Sie die Kalender-ID

So rufen Sie Funktionen auf, Datumsformate und Zeitzonen

Wertformate

Kalender

So erstellen Sie einen Kalender

So erhalten Sie Kalenderinformationen

So erhalten Sie die Kalenderliste des Dienstkontos

So löschen Sie einen Kalender

Ereignisse

So fügen Sie schnell ein Ereignis hinzu

So fügen Sie ein Ereignis hinzu

Zusätzliche extra_params-Parameter

Ganztägiges Ereignis

Antwort beim Erstellen eines Ereignisses

So aktualisieren Sie ein Ereignis

So erhalten Sie eine Liste von Ereignissen

So erhalten Sie Ereignisinformationen

So verschieben Sie ein Ereignis in einen anderen Kalender

So löschen Sie ein Ereignis

Ereignisteilnehmer

So fügen Sie einen Teilnehmer hinzu

So entfernen Sie einen Teilnehmer

Mögliche Fehler

Not Found-Fehler

Google Calendar API ist nicht aktiviert

Dienstkontoschlüssel nicht gefunden

Falsches Datums- und Uhrzeitformat

Falsches Datumsformat

Kein geeigneter Abonnementplan

Kurzbeispiel

Wo der Schlüssel gespeichert wird: Variable `calendar_json_keys`

Zusätzliche `extra_params`-Parameter

`Not Found`-Fehler