Skip to main content

Google Calendar

This is the tool that powers every "book me a meeting" flow in Insighto. Each connection is a real per-user OAuth grant against a Google account — yours, your teammate's, or a shared resource calendar. The assistant uses it to find open slots and create real events on that calendar; Google sends out the invite, attaches a Meet link, and the booking shows up on everyone's calendar the same way any other meeting would.

What you can do with this tool​

  • List open slots that respect the user's working hours, existing events, and minimum-notice rules.
  • Book a meeting — Google Calendar event with attendees, invite emails, and a Meet link.
  • Round-robin across a team by bundling several connections into a Calendar Pool.

Business use cases​

Solo practitioner — one-person practice​

A therapist runs a one-person practice. She connects her Google Calendar once. Her voice assistant has the connection attached. Callers ask for an appointment, the assistant calls find_available_slots, reads three options that respect her configured working hours (Mon–Thu, 10am–6pm) and 24-hour minimum notice, and books with book_appointment. The new client gets a calendar invite with the Zoom-replacement Meet link attached. She never had to touch a scheduling page.

Team round-robin booking for a clinic​

A dental practice has three hygienists, each with their own Google Calendar. Each hygienist connects their own calendar to Insighto (one connection per person — there's no admin override). The practice manager bundles all three into a Calendar Pool with round-robin rotation. The voice assistant has the Pool attached. Callers asking for a cleaning get booked with whichever hygienist is next in line, on whichever chair is open. Booking volume balances itself.

Sales-rep booking widget​

A B2B SaaS company puts a chat widget on its pricing page. The widget assistant has each AE's Google Calendar in a Calendar Pool. Prospects pick a time during the conversation, the assistant books it with the round-robin AE, and the prospect leaves with a Meet link in their inbox and an event on their calendar.

Multi-location practice​

A medical group has three clinic locations, each with its own resource calendar (the chair, the exam room, the dentist's chair). They connect each clinic's calendar separately and configure each one's working hours and timezone. When the assistant takes a call, the system prompt tells it which calendar to use based on the location the caller asks for.

Per-user OAuth, no service accounts​

Each calendar owner whose calendar you want to expose logs in and grants access themselves. There's no admin override or workspace-wide service account — Google's privacy model assumes the calendar owner has explicitly consented.

  • One-person practice: connect once.
  • Five-person team: each person logs in and connects their own calendar.
  • Team round-robin: bundle the connections into a Calendar Pool.

Connecting your calendar​

Step-by-step​

  1. Go to Tools & Integrations → Google Calendar → Connect.
  2. Google's consent screen opens. Pick the account whose calendar you want to expose.
  3. Approve the scope below.
  4. Back in Insighto, pick which calendar inside the account this connection points to (most users have several — work, personal, etc.).
  5. Configure:
    • Timezone (IANA, e.g. America/New_York).
    • Appointment duration in minutes.
    • Event title template — what the booked event's title will say.
    • Working hours per day, e.g. Monday 09:00–17:00, Tuesday 10:00–17:00. Multi-window days are supported (e.g. 09:00–12:30 and 14:00–17:00 for a lunch break).
    • Minimum notice (minutes) — the earliest bookable slot is now + minimum_notice. Use this to prevent same-minute bookings.
    • Optional: invite description, email BCC address for confirmations.
  6. Name the connection after the person ("Dr. Smith — Bookings") so it's identifiable in Calendar Pools.

Insighto refreshes tokens automatically — there's nothing to reconnect periodically.

Scope requested​

https://www.googleapis.com/auth/calendar

Full Calendar scope (read/write). Insighto uses it to read free/busy and to create events. There's no read-only mode today.

Prerequisites​

  • A Google account (personal or Workspace) with calendar access.
  • For Workspace users: admin permission to use third-party OAuth apps, if your admin restricts them.

Functions the assistant can call​

find_available_slots​

Lists available slots across a date range, respecting the connection's working hours, existing events, and minimum-notice setting.

  • Arguments
    • appointment_start_date (string, required) — YYYY-MM-DD.
    • appointment_end_date (string, required) — YYYY-MM-DD.
  • Returns — 
    {
      "available_time_slots": ["2026-05-20 09:00", "2026-05-20 09:30"],
      "unavailable_time_slots": ["2026-05-20 10:30"],
      "duration_in_minutes": 30,
      "timezone": "America/New_York"
    }

get_earliest_appointments​

Convenience wrapper that looks at the next 14 days from today.

  • Arguments — none required.
  • Returns — same shape as find_available_slots.

book_appointment​

Creates a real Google Calendar event. Validates the slot is still free first, generates a Meet link, sends invites.

  • Arguments
    • appointment_date (string, required) — YYYY-MM-DD.
    • appointment_time (string, required) — HH:MM.
    • email (string, optional) — attendee email; gets the invite.
    • phone (string, optional) — included in the event details.
  • Returns — booking confirmation or "Slot not available" if it was taken in the gap between lookup and booking.

get_timezone​

Returns the connection's configured timezone. Used at conversation start to anchor "today's date and time" in the assistant's awareness.

  • Arguments — none.
  • Returns — IANA timezone string.

Example invocation​

Finding slots for a Tuesday-Wednesday window:

{
  "function": "find_available_slots",
  "arguments": {
    "appointment_start_date": "2026-05-20",
    "appointment_end_date": "2026-05-22"
  }
}

Result:

{
  "available_time_slots": ["2026-05-20 09:00", "2026-05-20 09:30", "2026-05-20 13:00"],
  "duration_in_minutes": 30,
  "timezone": "America/New_York"
}

Booking one of them:

{
  "function": "book_appointment",
  "arguments": {
    "appointment_date": "2026-05-20",
    "appointment_time": "09:00",
    "email": "alice@example.com"
  }
}

System prompt guidance​

A few patterns that hold consistently:

When a caller asks to book, call find_available_slots for the requested window. List at most three options aloud — reading 30 slots is robotic. Once they pick one, confirm name and email, then call book_appointment.

The "at most three options" rule is important on voice. find_available_slots can return 30+ entries for a multi-day window; reading them all aloud is painful.

Working hours, buffers, minimum notice​

Working hours are configured per day, with support for multi-window days:

{
  "Monday": ["09:00-12:30", "14:00-17:00"],
  "Tuesday": ["10:00-17:00"],
  "Wednesday": ["09:00-11:30", "14:00-17:00"]
}

find_available_slots parses each window, generates back-to-back slots of your configured duration, and filters out anything that conflicts with existing events. There's no separate "buffer" setting — the buffer is implicit in how you carve out your working hours.

Minimum notice (minutes from now) is honored — slots earlier than now + minimum_notice are dropped. Use this to prevent "book a 9am slot at 8:57am" panic moves.

Every booking automatically gets a Google Meet URL attached. Attendees see it in their invite. No extra configuration needed.

Sending invitations​

Calendar invites go to the email passed in the email argument (if any), plus the optional BCC address you configured on the connection. Invitations come from the connected calendar's Google account (dr.smith@clinic.com), not from Insighto.

Timezone handling​

appointment_date + appointment_time are always interpreted in the connection's configured timezone. The assistant is told "today's date and time" in the same timezone at the start of every conversation, so relative phrases like "next Tuesday" resolve correctly.

For cross-region practices, configure each connection's timezone explicitly during setup, and tell the assistant in the prompt to "confirm the appointment time in the customer's own words" — don't ask it to compute offsets.

Cancellation and rescheduling​

Not currently part of this tool. If you need cancel/reschedule flows, either:

Failure modes​

  • Token revoked from Google's side — happens when users change passwords or run security checkups. The next call fails; the user reconnects.
  • Calendar deleted or renamed — the stored calendar reference becomes stale. Delete the connection and re-add.
  • Free/busy rate limits — high-volume deployments may hit Google's free/busy query limits. Spread across multiple connected accounts or use Calendar Pools.
  • All-day events block bookings — vacations marked 9am–5pm only block business hours; mark them all-day to fully block the day.
  • Slot taken between lookup and booking — book_appointment re-checks availability before inserting. If filled in the gap, returns "Slot not available" and the assistant should offer another.

Where to next​

  • Set up team round-robin with Calendar Pools.
  • Pair with HubSpot so bookings auto-log to the contact.
  • Send the booking confirmation via SMS right after.