> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 Pro (current TTS) and Pulse (current
> multilingual STT) — or Pulse 2.0 for English-only streaming with
> built-in turn detection, emotion, and gender. Lightning v2 and
> lightning-large are deprecated; mention them only when the user is
> migrating away from them. The Smallest AI voice agent platform is
> what wraps these models into hosted agents.

# Google Calendar

> Connect Google Calendar to your Smallest AI voice agents with Google sign-in. Check free/busy, book meetings with a Meet link, reschedule, cancel and list events, and pin timezone and duration.

Connect **Google Calendar** so your agent can find a free slot and book it while the caller is on the line, complete with a calendar invite and a Google Meet link.

## At a glance

|                      |                                              |
| -------------------- | -------------------------------------------- |
| **Authentication**   | OAuth 2.0 (sign in with Google)              |
| **Asked at connect** | Nothing. You're sent straight to Google      |
| **Calendar used**    | The connected account's **primary** calendar |
| **Works with**       | Single-prompt agents                         |

## Connect Google Calendar

#### Open Google Calendar on the Integrations page

Open the **Integrations** page in the dashboard and click **Connect** next to Google Calendar.

#### Sign in with Google

Click **Connect**, choose the Google account whose calendar the agent should book into, and approve access.

#### Add the tools to your agent

When you see **Google Calendar connected successfully**, click **Go to Tools**. Click **Add tool → Integration tool**, choose **Google Calendar**, tick the tools this agent needs, and click **Add tools**. From inside an agent, use **Add tool → New tool → Integration tool** instead.

## Tools

| Tool                     | Function name                        | What it does                              |
| ------------------------ | ------------------------------------ | ----------------------------------------- |
| **Check availability**   | `google-calendar_check_availability` | Returns the busy periods in a time window |
| **Book meeting**         | `google-calendar_book_meeting`       | Creates an event and invites the caller   |
| **Reschedule meeting**   | `google-calendar_reschedule_meeting` | Moves an existing event to a new time     |
| **Cancel meeting**       | `google-calendar_cancel_meeting`     | Deletes an event                          |
| **List upcoming events** | `google-calendar_list_events`        | Lists events in a time window             |

> **Note**
>
> Times are a local date and time in the given `timezone`, with no UTC offset, for example `2026-09-01T14:30:00` with `Asia/Kolkata`. Times in replies are local times in that zone too, so clock changes never shift a meeting. Add the `{{current_date}}`, `{{current_time}}` and `{{timezone}}` system variables to the agent's prompt, so it can turn "tomorrow at 3" into a real date and time.

### Fields

#### Check availability

| Field        | Required | Description                                   | Pinnable |
| ------------ | -------- | --------------------------------------------- | -------- |
| `start_time` | Yes      | Start of the window to check                  |          |
| `end_time`   | Yes      | End of the window to check                    |          |
| `timezone`   | Yes      | IANA timezone, for example `America/New_York` | Yes      |

Returns the **busy** intervals in the window, as local times in `timezone`. Anything not listed is free on the calendar, even outside your working hours, so give the agent your hours in its prompt.

#### Book meeting

| Field                  | Required | Description                                      | Pinnable |
| ---------------------- | -------- | ------------------------------------------------ | -------- |
| `start_time`           | Yes      | Meeting start                                    | Yes      |
| `timezone`             | Yes      | IANA timezone the event is created in            | Yes      |
| `attendee_name`        | Yes      | The caller's full name                           | Yes      |
| `attendee_email`       | Yes      | Where the invite goes                            | Yes      |
| `attendee_phone`       | No       | Added to the event description                   |          |
| `title`                | No       | Defaults to "Meeting with *name*"                | Yes      |
| `duration_minutes`     | No       | 1–1440. Defaults to 30                           | Yes      |
| `description`          | No       | Notes for the invite                             | Yes      |
| `location`             | No       | An address, room or URL                          | Yes      |
| `additional_attendees` | No       | Comma-separated guest emails, up to 10           | Yes      |
| `send_updates`         | No       | `all` (default) emails guests; `none` doesn't    | Yes      |
| `create_meeting_room`  | No       | Add a Google Meet link. Defaults to `true`       | Yes      |
| `visibility`           | No       | `default`, `public`, `private` or `confidential` | Yes      |

Before creating the event, the slot is checked again. If it was taken in the meantime, the agent is told to pick another time.

#### Reschedule meeting

| Field              | Required | Description                                                     |
| ------------------ | -------- | --------------------------------------------------------------- |
| `booking_uid`      | Yes      | The event ID, from **Book meeting** or **List upcoming events** |
| `start_time`       | Yes      | The new start time                                              |
| `timezone`         | Yes      | IANA timezone the new start time is in                          |
| `duration_minutes` | No       | The meeting's length. Defaults to 30                            |

> **Warning**
>
> Rescheduling doesn't re-check availability, and guests may not get an email about the change, so tell the caller the new time before hanging up. Have the agent call **Check availability** for the new time first, and pass `duration_minutes` to keep a meeting that isn't 30 minutes long.

#### Cancel meeting

| Field         | Required | Description  |
| ------------- | -------- | ------------ |
| `booking_uid` | Yes      | The event ID |

#### List upcoming events

| Field          | Required | Description                                   | Pinnable |
| -------------- | -------- | --------------------------------------------- | -------- |
| `start_time`   | Yes      | Start of the window                           |          |
| `end_time`     | Yes      | End of the window                             |          |
| `timezone`     | Yes      | IANA timezone the window is in                |          |
| `q`            | No       | Free-text filter, such as the caller's name   |          |
| `max_results`  | No       | Defaults to 10, up to 50                      | Yes      |
| `order_by`     | No       | `startTime` (default) or `updated`            | Yes      |
| `show_deleted` | No       | Include cancelled events. Defaults to `false` | Yes      |
| `page_token`   | No       | From the previous response, for the next page |          |

## Pin the values that never change

| Field                 | Typical pin         | Why                                                    |
| --------------------- | ------------------- | ------------------------------------------------------ |
| `timezone`            | `Asia/Kolkata`      | The agent never has to ask, and never guesses wrong    |
| `duration_minutes`    | `30`                | Every booking is the same length                       |
| `title`               | `Discovery call`    | Events are easy to spot in your calendar               |
| `location`            | Your office address | In-person meetings always have the address             |
| `create_meeting_room` | `false`             | Turn off the Meet link for phone or in-person meetings |

## How it works on a call

#### Find a time

The caller asks for "Thursday afternoon". The agent calls **Check availability** for that window and offers a time that isn't busy.

#### Collect details

The agent confirms the caller's name and email, and reads the email back.

#### Book

**Book meeting** creates the event and emails the invite. The caller hears the confirmed time before hanging up.

| Tool                   | Example condition prompt                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| **Check availability** | *Whenever the caller suggests a time, check it before agreeing.*                                  |
| **Book meeting**       | *Only after the caller confirms the time and you've read their email back.*                       |
| **Cancel meeting**     | *Only when the caller explicitly asks to cancel. Find the event with List upcoming events first.* |

## Limits

* Bookings always go on the connected account's **primary** calendar.
* **One Google Calendar account per organization.** To switch to a different one, click **Disconnect**, then **Connect** again.

## Troubleshooting

#### 'must be a local date and time'

The agent sent a time that isn't a plain local date and time. Add `{{current_date}}`, `{{current_time}}` and `{{timezone}}` to its prompt so it knows today's date, the time and your timezone, or pin `timezone`.

#### 'That slot is no longer available'

Someone took the slot between checking and booking. The agent should check availability again and offer another time.

#### Calendar calls start failing after working before

Google access was removed, for example from the Google Account's third-party connections page or by a Workspace admin. On the Integrations page click **Disconnect**, then **Connect** and sign in again.

## Related

#### [Integrations overview](/voice-agents/integrate/integrations)

Connecting, pinning fields and disconnecting

#### [Cal.com](/integrations/connected-apps/cal-com)

Book against Cal.com event types instead