Google Calendar

Google Calendar is managed through calculator functions: the chatbot communicates with the Google API using your service account. There is no need to configure separate HTTP requests.

Requirements

A Google Cloud project with the Google Calendar API enabled.
A service account for this project and its key in JSON format.
A calendar where the service account has permission to modify events.

How to Create a Service Account and Get a Key

Go to the Google Cloud Console and create a new project.

Go to APIs & Services → Library, find Google Calendar API, and click Enable. Without this step, all requests will return an error.

Go to IAM & Admin → Service Accounts, create a service account, and assign it the Owner role.

Open the service account you created → Keys tab → Add key → Create new key → select JSON.

The key file will be downloaded to your computer.

Save the service account address — the client_email field in the downloaded file, for example [email protected]. You will need it to grant the service account access to the calendar.

Where to Store the Key: `calendar_json_keys` Variable

Upload the downloaded JSON file to the file storage of the project where you are working with Google Calendar, then right-click the file and copy its link.

In Project Constants, add a variable named calendar_json_keys and set its value to an array of keys:

In other words, paste the link you copied for the key file uploaded to your project.

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

You can specify multiple keys, for example if you use different projects. For each request, the builder will use one of them:

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

Instead of a link, you can provide the entire key directly from the uploaded file:

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

How to Grant the Service Account Access to a Calendar

Open the settings of the required calendar → Share with people or groups → Add people and groups → enter the service account's client_email and grant the Make changes to events permission.

Without this permission, Google returns Not Found even if the calendar exists.

A calendar created using gcal_create_calendar is immediately available to the service account, so you do not need to share it separately.

How to Find the Calendar ID

Open the calendar settings → Integrate calendar → Calendar ID.

The ID looks approximately like this:

[email protected]

You can also get the IDs of all available calendars using:

gcal_calendars_list()

How to Call Functions, Date Formats, and Time Zones

Functions, including all the functions listed below, are entered in the calculator in the chatbot builder.

It is convenient to save the result directly to a variable:

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

Each function returns the Google API response in JSON format. If an error occurs, the response looks like this:

{"status": false, "err": "error description"}

You can retrieve a specific field from the response using the get function.

For example:

get(event, 'id')

Value Formats

Value	Format	Example
Date and time	`dd.mm.yyyy HH:MM`	`20.08.2026 14:00`
Date (all-day event)	`dd.mm.yyyy`	`20.08.2026`
Time zone	IANA identifier	`Europe/Moscow`, `Europe/Istanbul`

If no time zone is specified, the time zone configured in the project settings is used.

Calendars

How to Create a Calendar

Use the following function:

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

Parameters:

name — calendar name;
description — calendar description;
time_zone — time zone;
location — location;
owner_email — email address of the Google account that will receive owner permissions. The service account will retain access to the calendar.

Example:

calendar = gcal_create_calendar("Consultation Bookings", "Bot calendar", "Europe/Moscow", "", "[email protected]")

The function returns the created calendar data:

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

Save the ID from the id field to a project variable — it is required by all other functions.

How to Get Calendar Information

gcal_get_calendar(calendar_id)

The function returns the calendar name, description, time zone, and address.

How to Get the Service Account's Calendar List

gcal_calendars_list()

The function returns all calendars accessible to the service account, along with their IDs.

How to Delete a Calendar

gcal_remove_calendar(calendar_id)

If the calendar is deleted successfully, the function returns:

{"status": true}

Events

How to Quickly Add an Event

Use the following function:

gcal_quick_add_event(calendar_id, event_name)

Google will automatically parse the date and time from the text.

Example:

event = gcal_quick_add_event("[email protected]", "Meeting with John tomorrow at 15:00")

How to Add an Event

Use the following function:

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

Parameters:

calendar_id — calendar ID;
event_name — event name;
start_datetime — event start date and time;
end_datetime — event end date and time;
event_description — event description;
location — event location;
time_zone — time zone;
extra_params — additional event parameters in JSON format.

Example:

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

Additional `extra_params` Parameters

extra_params is a JSON object containing optional parameters:

Parameter	Description
`email_minutes`	Sends an email reminder the specified number of minutes before the event
`popup_minutes`	Shows a popup reminder the specified number of minutes before the event
`start_date`	Start date for an all-day event
`end_date`	End date for an all-day event
`transparency`	`opaque` — time is marked as busy; `transparent` — time remains available
`recurrence_days`	Days of the week for weekly recurrence: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, `SU`, separated by commas
`recurrence_until`	Date until which the event repeats, for example `20261231T000000Z`
`recurrence_count`	Number of occurrences instead of an end date

The default value is:

transparency = opaque

This means that the event time is considered busy.

To keep the event time available:

{"transparency": "transparent"}

All-Day Event

For an all-day event, pass start_date and end_date through extra_params instead of start_datetime and end_datetime.

Example of an all-day event that repeats on Mondays and Wednesdays 10 times:

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

For all-day events, Google treats the end date as exclusive. To create an event that occupies only 01.09.2026, specify 02.09.2026 as the end_date.

Response When Creating an Event

The function returns the created event:

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

Save the event id to a client variable.

For example:

event_id = get(event, 'id')

You will need the ID later to update, move, or delete the event.

How to Update an Event

Use the following function:

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)

Pass only the fields you want to change. All other fields will remain unchanged.

For example, to reschedule an existing event to 21.08.2026 from 16:00 to 17:00:

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

The structure of extra_params is the same as for gcal_add_event.

Reminders are updated by type.

For example, if you pass only:

{"popup_minutes": 30}

the popup reminder will be replaced, while the existing email reminder will remain unchanged.

How to Get a List of Events

Use the following function:

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

Parameters:

calendar_id — calendar ID;
start_date — start of the period in dd.mm.yyyy format;
end_date — end of the period in dd.mm.yyyy format.

Example:

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

If no dates are specified, the function returns events for the current day:

events = gcal_get_event_list("[email protected]")

Events are returned sorted by start time.

Recurring events are returned as separate entries.

How to Get Event Information

Use the following function:

gcal_get_event(calendar_id, event_id)

The function returns all event data, including:

name;
description;
date and time;
location;
attendees;
reminders;
other event parameters.

Example:

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

How to Move an Event to Another Calendar

Use the following function:

gcal_move_event(calendar_id, event_id, destination_calendar_id)

where:

calendar_id — ID of the current calendar;
event_id — event ID;
destination_calendar_id — ID of the calendar to which the event should be moved.

Example:

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

How to Delete an Event

Use the following function:

gcal_remove_event(calendar_id, event_id)

Example:

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

If the event is deleted successfully, the function returns:

{"status": true}

Event Attendees

How to Add an Attendee

Use the following function:

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

Parameters:

calendar_id — calendar ID;
event_id — event ID;
client_email — attendee's email address;
name — the name that will be displayed in the calendar;
comment — a comment for the attendee.

Example:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Booked through the bot")

If this attendee has already been added to the event, the function returns an error:

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

How to Remove an Attendee

Use the following function:

gcal_remove_client(calendar_id, event_id, client_email)

Parameters:

calendar_id — calendar ID;
event_id — event ID;
client_email — email address of the attendee to remove.

Example:

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

If the specified attendee is not in the event, the function returns:

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

Possible Errors

If an error occurs, the functions return an object in the following format:

{
  "status": false,
  "err": "error description"
}

Common errors:

Response	Cause
`Not Found`	The calendar has not been shared with the service account, or an incorrect `calendar_id` was specified
`Google Calendar API has not been used in project ... or it is disabled`	Google Calendar API is not enabled in the Google Cloud project
`The key to access the calendar was not found in the passed link`	The link in `calendar_json_keys` does not return the key file
`wrong datetime "...", expected format is dd.mm.yyyy HH:MM`	The date and time were provided in an incorrect format
`wrong date "...", expected format is dd.mm.yyyy`	The date was provided in an incorrect format
`Работает только на тарифах Бизнес и Инфобиз`	The project does not have an active subscription that includes access to this feature

`Not Found` Error

If Google returns:

Not Found

check the following:

Make sure the calendar_id is correct.
Make sure the service account's client_email has been added to the calendar settings.
Make sure the service account has the Make changes to events permission.

Even if the calendar exists, Google may return Not Found if the service account does not have access to it.

Google Calendar API Is Not Enabled

The error looks approximately like this:

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

Open your project in Google Cloud and enable:

APIs & Services → Library → Google Calendar API → Enable

After enabling the API, repeat the request.

Service Account Key Not Found

Error:

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

Check the value of:

calendar_json_keys

If you use a file link, it must directly return the JSON file containing the service account key.

Example:

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

You can also provide the key directly in calendar_json_keys as a JSON object.

Incorrect Date and Time Format

Error:

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

Correct format:

dd.mm.yyyy HH:MM

Example:

20.08.2026 14:00

Incorrect examples:

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

If the function expects both date and time, you must provide the date together with hours and minutes.

Incorrect Date Format

Error:

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

Correct format:

dd.mm.yyyy

Example:

20.08.2026

No Eligible Subscription Plan

Error:

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

This means that the project does not have an active subscription that allows the use of Google Calendar functions.

Quick Example

Create an event and save its ID:

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

event_id = get(event, 'id')

Add the client to the created event:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Booked through the bot")

If the client decides to reschedule:

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

If the client cancels the booking:

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

Google API errors are returned unchanged in the err field. The error message helps determine what is missing: calendar access, an enabled API, a valid key, the correct date format, or an existing event.

Google Calendar

Requirements

How to Create a Service Account and Get a Key

Where to Store the Key: calendar_json_keys Variable

How to Grant the Service Account Access to a Calendar

How to Find the Calendar ID

How to Call Functions, Date Formats, and Time Zones

Value Formats

Calendars

How to Create a Calendar

How to Get Calendar Information

How to Get the Service Account's Calendar List

How to Delete a Calendar

Events

How to Quickly Add an Event

How to Add an Event

Additional extra_params Parameters

All-Day Event

Response When Creating an Event

How to Update an Event

How to Get a List of Events

How to Get Event Information

How to Move an Event to Another Calendar

How to Delete an Event

Event Attendees

How to Add an Attendee

How to Remove an Attendee

Possible Errors

Not Found Error

Google Calendar API Is Not Enabled

Service Account Key Not Found

Incorrect Date and Time Format

Incorrect Date Format

No Eligible Subscription Plan

Quick Example

Where to Store the Key: `calendar_json_keys` Variable

Additional `extra_params` Parameters

`Not Found` Error