Integrar tu agente de voz IA con Google Calendar: guía paso a paso (2026)

Por qué tu agente IA tiene que mirar tu Google Calendar de verdad

El error número uno que vemos en negocios que estrenan un agente de voz IA es este: el agente "tiene agenda", pero esa agenda no es la misma que la tuya. El comercial llama al cliente, el cliente reserva con el agente, y a la hora de la verdad el hueco que el agente reservó ya estaba ocupado en tu Google Calendar real.

Resultado: doble booking, cliente enfadado, recepcionista apagando fuegos.

Esto pasa porque muchos sistemas conversacionales arrancan con una agenda interna del propio agente (más fácil de implementar) y dejan la integración con tu calendario para "más adelante". Si tu agenda real vive en Google Calendar, Outlook o un software vertical (Doctoralia, Booksy, GestiTaller, Audatex…), tu agente IA necesita mirar y escribir ahí, no en otro sitio.

Este artículo va sobre cómo conectarlo bien, con detalle técnico pero sin perderse: qué método de integración usar, qué scopes pedir, cómo evitar conflictos, qué hacer con multi-calendario y qué pasa cuando Google Calendar API se cae a las 11:30 un viernes.

Lo que necesitas antes de empezar

1. Un agente de voz IA con capacidad para llamar a APIs externas (no todos lo permiten — algunos solo tienen agenda interna).
2. Acceso de admin a la cuenta de Google Workspace o cuenta personal que tiene los calendarios.
3. Decidir si vas a tener un solo calendario compartido (recomendado para clínicas / talleres) o un calendario por profesional (recomendado para consultorios multi-doctor).
4. Un servicio donde alojar las credenciales OAuth. En Rinqa lo hace la plataforma; si te montas algo casero, vas a necesitar un backend.

Las 3 formas de integrar agente IA + Google Calendar

Opción A — OAuth 2.0 directo (recomendada)

Tu agente IA recibe permisos del usuario vía OAuth y llama a Google Calendar API en tiempo real. Es la opción nativa y la que Google soporta oficialmente.

Pros:

• Lecturas y escrituras en tiempo real.
• Múltiples calendarios soportados.
• Revocable desde el panel del usuario.

Contras:

• Requiere refresh tokens y manejo de errores 401/403.
• Quotas: 600 requests/minuto por usuario, 1.000.000/día. Suficiente para una clínica, no para un call center con 5.000 llamadas/día.

Scopes mínimos que necesitas pedir:

https://www.googleapis.com/auth/calendar.readonly        // ver disponibilidad
https://www.googleapis.com/auth/calendar.events          // crear/editar eventos

No pidas calendar (full access) salvo que tu agente tenga que borrar calendarios enteros. Si pides más scopes de los necesarios, Google te marca la app como "non-verified" y tus usuarios ven una pantalla amarilla de aviso al conectar.

Opción B — Webhook + middleware (Make, n8n, Zapier)

Tu agente IA dispara un webhook cuando quiere crear una cita. El middleware lo recoge y crea el evento.

Pros:

• No-code. Útil si no quieres tocar OAuth.
• Bueno para prototipos.

Contras:

• Latencia extra (1-3 segundos). El cliente nota el silencio.
• Sin lectura de disponibilidad en tiempo real, salvo que montes consulta previa.
• Frágil: si Make/Zapier se cae, tu agente sigue diciendo "cita confirmada" sin que se cree nada.

Opción C — Sincronización por iCal (lectura solo)

El agente lee un calendario público iCal y nunca escribe.

Pros: Trivial de implementar. Contras: No reserva, solo informa. Solo sirve si tu agente solo lee disponibilidad y la cita se acaba creando humanamente.

Recomendación honesta: Si vas en serio, usa Opción A. La B sirve para empezar pero te dará disgustos cuando el volumen pase de 30-40 llamadas/día.

Paso a paso (OAuth 2.0)

1. Crea un proyecto en Google Cloud Console

• Ve a console.cloud.google.com.
• Crea proyecto "AgenteIA-Calendar" (o lo que quieras).
• Activa Google Calendar API en "APIs y servicios".

2. Configura la pantalla de consentimiento OAuth

• Tipo de usuario: Externo (si vas a conectar varias cuentas de tus clientes) o Interno (si solo es tu organización Workspace).
• Rellena datos de marca (logo, dominio, política de privacidad). Esto es lo que ven los usuarios al autorizar.
• Añade los scopes:
  • /auth/calendar.readonly
  • /auth/calendar.events
• Si vas a tener más de 100 usuarios externos, necesitas verificar la app con Google (proceso de 1-6 semanas que incluye revisión de seguridad). Si no la verificas, Google muestra la pantalla "Esta app no está verificada" y limita a 100 usuarios.

3. Genera credenciales OAuth

• Tipo: Web application.
• Authorized redirect URIs: la URL de tu plataforma donde Google devuelve el código. En Rinqa es https://app.rinqa.com/integrations/google/callback.
• Guarda client_id y client_secret en un secret manager (no en código).

4. Implementa el flujo OAuth en tu backend

El flujo típico:

1. Usuario clic en "Conectar Google Calendar" en tu panel.
2. Redirect a https://accounts.google.com/o/oauth2/v2/auth?
   client_id=...&
   redirect_uri=...&
   response_type=code&
   scope=https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.readonly&
   access_type=offline&
   prompt=consent
3. Usuario autoriza, Google redirige a tu callback con ?code=...
4. Tu backend intercambia el code por access_token + refresh_token
5. Guardas refresh_token cifrado en tu DB asociado al tenant
6. Usas access_token (1h vida) para llamar a la API; cuando caduca, lo refrescas

Importante: access_type=offline y prompt=consent son obligatorios para que Google devuelva refresh token. Si no los pones, el primer día funciona y al día siguiente todo cae.

5. Configura el agente para leer disponibilidad

Antes de proponer un hueco al cliente, el agente consulta:

GET https://www.googleapis.com/calendar/v3/freeBusy
{
  "timeMin": "2026-05-21T09:00:00+02:00",
  "timeMax": "2026-05-21T20:00:00+02:00",
  "timeZone": "Europe/Madrid",
  "items": [{ "id": "agenda@tuclinica.com" }]
}

Esto devuelve los huecos ocupados. Tu agente calcula los huecos libres respetando la duración del servicio (30 min, 45 min, 1h…) y propone 2-3 opciones al cliente.

Truco importante: No propongas el primer hueco libre. Propón un hueco "razonable" (>30 min después de ahora, en horario laboral, no a las 13:50 si cierras a las 14:00). Esto se configura en el agente con reglas suaves, no en la API.

6. Crear el evento cuando el cliente confirma

POST https://www.googleapis.com/calendar/v3/calendars/agenda@tuclinica.com/events
{
  "summary": "Cita María García - Revisión",
  "description": "Reservado vía agente IA. Tlf: +34 600 000 000",
  "start": { "dateTime": "2026-05-21T10:30:00+02:00", "timeZone": "Europe/Madrid" },
  "end":   { "dateTime": "2026-05-21T11:00:00+02:00", "timeZone": "Europe/Madrid" },
  "attendees": [{ "email": "maria@email.com" }],
  "reminders": { "useDefault": true }
}

Devuelve un eventId que guardas en tu CRM asociado a la conversación, para poder modificarlo o cancelarlo después.

7. Webhook de cambios (opcional pero recomendado)

Si tu equipo edita el calendario a mano y la cita cambia, tu agente tiene que enterarse. Configura Calendar push notifications:

POST /calendars/{calendarId}/events/watch
{
  "id": "channel-uuid-xxx",
  "type": "web_hook",
  "address": "https://app.rinqa.com/webhooks/google-calendar"
}

Google notificará cambios a tu endpoint y podrás invalidar caché, avisar al cliente por SMS de la modificación o reabrir el hueco a otras reservas.

Multi-calendario: cuando hay varios profesionales

En clínicas con 3 doctores, talleres con 2 técnicos o salones con 4 estilistas, no quieres un solo calendario — quieres uno por persona.

Patrón recomendado:

1. Un calendario por profesional (maria@tuclinica.com, pedro@tuclinica.com).
2. Un campo "servicio → profesionales que lo realizan" en tu base de datos.
3. Cuando el cliente pide "una revisión", el agente busca freebusy en los calendarios de los profesionales habilitados y muestra el primero disponible.
4. Crea el evento en el calendario de ese profesional, con el cliente como attendee.

Anti-patrón: un calendario único compartido por todos. Se llena rápido, se mezclan eventos personales con profesionales y nadie sabe quién atiende.

Errores reales que verás (y cómo manejarlos)

El más jodido: el 410 Gone que aparece cuando alguien revoca tus permisos OAuth desde la pantalla de "Apps con acceso a tu cuenta". Tu agente sigue intentando reservar y todas las llamadas caen. Detecta este caso y avisa al admin por email + WhatsApp + SMS para que vuelva a conectar.

Lo que no te cuenta el README de la integración

• Diferencia de zona horaria. Si tu cliente llama desde Canarias y tu calendario está en Europe/Madrid, el evento queda mal. Usa siempre timeZone explícito en cada request y nunca asumas la zona del navegador o servidor.
• Eventos recurrentes y excepciones. No reserves sobre series recurrentes sin parsear las excepciones (recurrence + recurringEventId). Es una fuente clásica de double booking.
• Calendar API silencia notificaciones si el evento se crea sin sendUpdates=all. Por defecto, los attendees no reciben el invite. Si quieres que tu cliente reciba el correo automático de Google, añade sendUpdates=all.
• Outlook y Apple Calendar comparten estándar iCal pero no comparten API. Si vas a hacerlo "para todos los calendarios", necesitas integraciones separadas. Hay APIs intermedias (Nylas, Cronofy) que abstraen esto a cambio de coste extra.

Cómo lo resuelve Rinqa (para que sepas qué exigir)

En Rinqa la integración con Google Calendar viene preconfigurada:

• OAuth 2.0 con Google verificado (no aparece la pantalla amarilla).
• Multi-calendario y multi-profesional desde el panel.
• FreeBusy en tiempo real antes de proponer cada hueco.
• Webhook bidireccional para captar cambios manuales.
• Buffer de tiempo configurable por servicio (margen entre citas).
• Fallback automático: si Google Calendar API responde >3s, el agente confirma "te enviamos la cita por SMS en breve" y crea el evento en background para no dejar al cliente esperando.

Si tu proveedor de agente IA no soporta al menos los 4 primeros puntos, su integración con Google Calendar es de juguete.

---

¿Tienes tu agenda en Google Calendar y quieres un agente IA que reserve de verdad? Pide demo y lo conectamos en 30 minutos. Si comparas precios primero, mira los planes o el análisis de precio de recepcionista virtual para clínicas.