Google Calendar se gestiona mediante funciones de calculadora: el chatbot se comunica con la API de Google usando tu cuenta de servicio. No es necesario configurar solicitudes HTTP por separado.

Requisitos

  1. Un proyecto de Google Cloud con la API de Google Calendar habilitada.
  2. Una cuenta de servicio para este proyecto y su clave en formato JSON.
  3. Un calendario donde la cuenta de servicio tenga permiso para modificar eventos.

Cómo Crear una Cuenta de Servicio y Obtener una Clave

  1. Ve a Google Cloud Console y crea un nuevo proyecto.

  1. Ve a APIs y servicios → Biblioteca, busca Google Calendar API y haz clic en Habilitar. Sin este paso, todas las solicitudes devolverán un error.

  1. Ve a IAM y administración → Cuentas de servicio, crea una cuenta de servicio y asígnale el rol de Propietario.

  1. Abre la cuenta de servicio que creaste → pestaña Claves → Agregar clave → Crear clave nueva → selecciona JSON.

El archivo de clave se descargará en tu computadora.

  1. Guarda la dirección de la cuenta de servicio: el campo client_email en el archivo descargado, por ejemplo [email protected]. La necesitarás para otorgar acceso a la cuenta de servicio al calendario.

Dónde Almacenar la Clave: Variable calendar_json_keys

  1. Sube el archivo JSON descargado al almacenamiento de archivos del proyecto donde trabajas con Google Calendar, luego haz clic derecho en el archivo y copia su enlace.

  1. En Constantes del proyecto, agrega una variable llamada calendar_json_keys y establece su valor como un array de claves:

En otras palabras, pega el enlace que copiaste para el archivo de clave subido a tu proyecto.

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

Puedes especificar múltiples claves, por ejemplo si usas diferentes proyectos. Para cada solicitud, el constructor usará una de ellas:

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

En lugar de un enlace, puedes proporcionar la clave completa directamente desde el archivo subido:

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

Cómo Otorgar Acceso a la Cuenta de Servicio a un Calendario

Abre la configuración del calendario requerido → Compartir con personas o grupos → Agregar personas y grupos → ingresa el client_email de la cuenta de servicio y otorga el permiso Hacer cambios en los eventos.

Sin este permiso, Google devuelve Not Found incluso si el calendario existe.

Un calendario creado con gcal_create_calendar está inmediatamente disponible para la cuenta de servicio, por lo que no necesitas compartirlo por separado.

Cómo Encontrar el ID del Calendario

Abre la configuración del calendario → Integrar calendario → ID del calendario.

El ID se ve aproximadamente así:

[email protected]

También puedes obtener los IDs de todos los calendarios disponibles usando:

gcal_calendars_list()

Cómo Llamar Funciones, Formatos de Fecha y Zonas Horarias

Las funciones, incluidas todas las enumeradas a continuación, se ingresan en la calculadora del constructor del chatbot.

Es conveniente guardar el resultado directamente en una variable:

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

Cada función devuelve la respuesta de la API de Google en formato JSON. Si ocurre un error, la respuesta se ve así:

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

Puedes recuperar un campo específico de la respuesta usando la función get.

Por ejemplo:

get(event, 'id')

Formatos de Valor

Valor Formato Ejemplo
Fecha y hora dd.mm.yyyy HH:MM 20.08.2026 14:00
Fecha (evento de día completo) dd.mm.yyyy 20.08.2026
Zona horaria Identificador IANA Europe/Moscow, Europe/Istanbul

Si no se especifica una zona horaria, se usa la zona horaria configurada en la configuración del proyecto.

Calendarios

Cómo Crear un Calendario

Usa la siguiente función:

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

Parámetros:

  • name — nombre del calendario;
  • description — descripción del calendario;
  • time_zone — zona horaria;
  • location — ubicación;
  • owner_email — dirección de correo electrónico de la cuenta de Google que recibirá permisos de propietario. La cuenta de servicio conservará el acceso al calendario.

Ejemplo:

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

La función devuelve los datos del calendario creado:

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

Guarda el ID del campo id en una variable del proyecto: es requerido por todas las demás funciones.

Cómo Obtener Información del Calendario

gcal_get_calendar(calendar_id)

La función devuelve el nombre del calendario, descripción, zona horaria y dirección.

Cómo Obtener la Lista de Calendarios de la Cuenta de Servicio

gcal_calendars_list()

La función devuelve todos los calendarios accesibles para la cuenta de servicio, junto con sus IDs.

Cómo Eliminar un Calendario

gcal_remove_calendar(calendar_id)

Si el calendario se elimina correctamente, la función devuelve:

{"status": true}

Eventos

Cómo Agregar Rápidamente un Evento

Usa la siguiente función:

gcal_quick_add_event(calendar_id, event_name)

Google analizará automáticamente la fecha y hora del texto.

Ejemplo:

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

Cómo Agregar un Evento

Usa la siguiente función:

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

Parámetros:

  • calendar_id — ID del calendario;
  • event_name — nombre del evento;
  • start_datetime — fecha y hora de inicio del evento;
  • end_datetime — fecha y hora de fin del evento;
  • event_description — descripción del evento;
  • location — ubicación del evento;
  • time_zone — zona horaria;
  • extra_params — parámetros adicionales del evento en formato JSON.

Ejemplo:

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}')

Parámetros Adicionales de extra_params

extra_params es un objeto JSON que contiene parámetros opcionales:

Parámetro Descripción
email_minutes Envía un recordatorio por correo electrónico el número especificado de minutos antes del evento
popup_minutes Muestra un recordatorio emergente el número especificado de minutos antes del evento
start_date Fecha de inicio para un evento de día completo
end_date Fecha de fin para un evento de día completo
transparency opaque — el tiempo se marca como ocupado; transparent — el tiempo permanece disponible
recurrence_days Días de la semana para repetición semanal: MO, TU, WE, TH, FR, SA, SU, separados por comas
recurrence_until Fecha hasta la cual se repite el evento, por ejemplo 20261231T000000Z
recurrence_count Número de ocurrencias en lugar de una fecha de fin

El valor predeterminado es:

transparency = opaque

Esto significa que el tiempo del evento se considera ocupado.

Para mantener el tiempo del evento disponible:

{"transparency": "transparent"}

Evento de Día Completo

Para un evento de día completo, pasa start_date y end_date a través de extra_params en lugar de start_datetime y end_datetime.

Ejemplo de un evento de día completo que se repite los lunes y miércoles 10 veces:

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}')

Para eventos de día completo, Google trata la fecha de fin como exclusiva. Para crear un evento que ocupe solo 01.09.2026, especifica 02.09.2026 como end_date.

Respuesta al Crear un Evento

La función devuelve el evento creado:

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

Guarda el id del evento en una variable de cliente.

Por ejemplo:

event_id = get(event, 'id')

Necesitarás el ID más tarde para actualizar, mover o eliminar el evento.

Cómo Actualizar un Evento

Usa la siguiente función:

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)

Pasa solo los campos que deseas cambiar. Todos los demás campos permanecerán sin cambios.

Por ejemplo, para reprogramar un evento existente al 21.08.2026 de 16:00 a 17:00:

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

La estructura de extra_params es la misma que para gcal_add_event.

Los recordatorios se actualizan por tipo.

Por ejemplo, si pasas solo:

{"popup_minutes": 30}

el recordatorio emergente se reemplazará, mientras que el recordatorio por correo electrónico existente permanecerá sin cambios.

Cómo Obtener una Lista de Eventos

Usa la siguiente función:

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

Parámetros:

  • calendar_id — ID del calendario;
  • start_date — inicio del período en formato dd.mm.yyyy;
  • end_date — fin del período en formato dd.mm.yyyy.

Ejemplo:

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

Si no se especifican fechas, la función devuelve eventos para el día actual:


events = gcal_get_event_list("[email protected]")

Los eventos se devuelven ordenados por hora de inicio.

Los eventos recurrentes se devuelven como entradas separadas.

Cómo Obtener Información de un Evento

Usa la siguiente función:

gcal_get_event(calendar_id, event_id)

La función devuelve todos los datos del evento, incluyendo:

  • nombre;
  • descripción;
  • fecha y hora;
  • ubicación;
  • asistentes;
  • recordatorios;
  • otros parámetros del evento.

Ejemplo:

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

Cómo Mover un Evento a Otro Calendario

Usa la siguiente función:

gcal_move_event(calendar_id, event_id, destination_calendar_id)

donde:

  • calendar_id — ID del calendario actual;
  • event_id — ID del evento;
  • destination_calendar_id — ID del calendario al que se debe mover el evento.

Ejemplo:

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

Cómo Eliminar un Evento

Usa la siguiente función:

gcal_remove_event(calendar_id, event_id)

Ejemplo:

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

Si el evento se elimina correctamente, la función devuelve:

{"status": true}

Asistentes del Evento

Cómo Añadir un Asistente

Usa la siguiente función:

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

Parámetros:

  • calendar_id — ID del calendario;
  • event_id — ID del evento;
  • client_email — dirección de correo electrónico del asistente;
  • name — el nombre que se mostrará en el calendario;
  • comment — un comentario para el asistente.

Ejemplo:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Reservado a través del bot")

Si este asistente ya ha sido añadido al evento, la función devuelve un error:

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

Cómo Eliminar un Asistente

Usa la siguiente función:

gcal_remove_client(calendar_id, event_id, client_email)

Parámetros:

  • calendar_id — ID del calendario;
  • event_id — ID del evento;
  • client_email — dirección de correo electrónico del asistente a eliminar.

Ejemplo:

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

Si el asistente especificado no está en el evento, la función devuelve:

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

Posibles Errores

Si ocurre un error, las funciones devuelven un objeto con el siguiente formato:

{
  "status": false,
  "err": "descripción del error"
}

Errores comunes:

Respuesta Causa
Not Found El calendario no se ha compartido con la cuenta de servicio, o se especificó un calendar_id incorrecto
Google Calendar API has not been used in project ... or it is disabled La API de Google Calendar no está habilitada en el proyecto de Google Cloud
The key to access the calendar was not found in the passed link El enlace en calendar_json_keys no devuelve el archivo de clave
wrong datetime "...", expected format is dd.mm.yyyy HH:MM La fecha y hora se proporcionaron en un formato incorrecto
wrong date "...", expected format is dd.mm.yyyy La fecha se proporcionó en un formato incorrecto
Работает только на тарифах Бизнес и Инфобиз El proyecto no tiene una suscripción activa que incluya acceso a esta función

Error Not Found

Si Google devuelve:

Not Found

verifica lo siguiente:

  1. Asegúrate de que calendar_id sea correcto.
  2. Asegúrate de que el client_email de la cuenta de servicio se haya añadido a la configuración del calendario.
  3. Asegúrate de que la cuenta de servicio tenga el permiso Make changes to events.

Incluso si el calendario existe, Google puede devolver Not Found si la cuenta de servicio no tiene acceso a él.

La API de Google Calendar No Está Habilitada

El error se ve aproximadamente así:

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

Abre tu proyecto en Google Cloud y habilita:

APIs & Services → Library → Google Calendar API → Enable

Después de habilitar la API, repite la solicitud.

Clave de Cuenta de Servicio No Encontrada

Error:

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

Verifica el valor de:

calendar_json_keys

Si usas un enlace de archivo, debe devolver directamente el archivo JSON que contiene la clave de la cuenta de servicio.

Ejemplo:

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

También puedes proporcionar la clave directamente en calendar_json_keys como un objeto JSON.

Formato de Fecha y Hora Incorrecto

Error:

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

Formato correcto:

dd.mm.yyyy HH:MM

Ejemplo:

20.08.2026 14:00

Ejemplos incorrectos:

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

Si la función espera tanto fecha como hora, debes proporcionar la fecha junto con las horas y minutos.

Formato de Fecha Incorrecto

Error:

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

Formato correcto:

dd.mm.yyyy

Ejemplo:

20.08.2026

Sin Plan de Suscripción Elegible

Error:

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

Esto significa que el proyecto no tiene una suscripción activa que permita el uso de las funciones de Google Calendar.

Ejemplo Rápido

Crea un evento y guarda su ID:

event = gcal_add_event("[email protected]", "Consulta #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Teléfono del cliente: #{phone}", "Zoom", "Europe/Moscow")

event_id = get(event, 'id')

Añade al cliente al evento creado:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Reservado a través del bot")

Si el cliente decide reprogramar:

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

Si el cliente cancela la reserva:

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

Los errores de la API de Google se devuelven sin cambios en el campo err. El mensaje de error ayuda a determinar qué falta: acceso al calendario, una API habilitada, una clave válida, el formato de fecha correcto o un evento existente.