> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar tools

> Configure Google Calendar tools in Retell AI to check free times, book events with attendees, and find, reschedule, or cancel appointments during calls.

Google Calendar tools let your agent check free times and manage events on a [connected Google account](https://docs.retellai.com/integrations/google-calendar.md). Each tool uses the fixed `calendar_id` you choose in its inputs.

## Available tools

Add these tools from a [prompt agent's Functions menu](https://docs.retellai.com/build/single-multi-prompt/integration-tools.md) or a [conversation flow function node](https://docs.retellai.com/build/conversation-flow/integration-tools.md). They also work in [agent workflows](https://docs.retellai.com/agent/agent-workflow.md).

| Tool | Inputs beyond `calendar_id` | Result |
| - | - | - |
| **Check Availability** | `start_time`, `end_time`, `timezone` | `free_intervals`, each with a start and end time. |
| **Book Event** | `start_time`, `timezone`, `title`; optional booking fields below | The created `event`, including `event_id` and `html_link`. |
| **List Events** | `attendee_email`, `start_time`, `end_time`, `timezone` | Matching `events` ordered by start time, plus `count`. Returns up to 50 events (as of November 2026). |
| **Get Event** | `event_id` | One `event` with its details and attendees. |
| **Reschedule Event** | `event_id`, `start_time`, `timezone` | The updated `event`, keeping its original duration. |
| **Cancel Event** | `event_id` | `success: true` after deletion. |

Times are local ISO 8601 strings, such as `2026-12-03T14:00:00`, paired with an IANA timezone such as `America/Los_Angeles`. Don't convert the local time to UTC yourself. For a time window, `end_time` must be after `start_time`.

## Book an appointment

A home services agent can check Thursday afternoon on the estimators' calendar, offer a 30-minute opening, and book a visit after the caller confirms their time and email.

**1. Check a bounded time window**

Configure **Check Availability** with your calendar. Let the agent infer the requested date and timezone, or use [custom input instructions](https://docs.retellai.com/integrations/overview.md#configure-a-tools-inputs-and-outputs) to restrict checks to your business hours.

The result contains free intervals, not appointment slots of a fixed length. Choose a start time that leaves room for the whole appointment inside an interval. Only the selected calendar's busy times are checked; attendees' calendars aren't checked.

**2. Configure Book Event**

Choose the same `calendar_id`. Configure the required `start_time`, `timezone`, and `title` fields. Use **Add input** to include optional fields:

| Field | What to supply |
| - | - |
| `duration_minutes` | A positive number of minutes. Defaults to 30 when omitted. |
| `description` | Event notes, such as the service requested. |
| `location` | An address or an existing meeting link. This tool doesn't create a Google Meet link. |
| `attendees` | An array of people to invite. Each entry requires `email`; `name` is optional. Omit it to create an event without invitees. |

For an attendee list collected during the call, choose **Let AI infer**, or **Custom** to set instructions for the list and its **Every item** fields. For a predetermined list, choose **Array items** and fill the numbered rows. See [array inputs](https://docs.retellai.com/integrations/overview.md#configure-array-inputs) for both approaches.

**3. Confirm the details and book**

Instruct the agent to confirm the time, timezone, and attendee emails before calling **Book Event**. Google is asked to send invitations to all supplied attendees.

Booking and rescheduling don't recheck availability or reserve a slot in advance. Check availability close to the write, and don't announce success until the tool succeeds.

**4. Keep the event ID**

In **Function fields → Output**, map `event.event_id` to a dynamic variable such as `google_event_id`. If the path isn't listed, use **Manually add fields** to enter it. Pass `{{google_event_id}}` to a later **Get Event**, **Reschedule Event**, or **Cancel Event** tool using **Value** mode.

Event responses also include the title, start and end times, attendee details, and `html_link`. See [output field selection](https://docs.retellai.com/integrations/overview.md#run-a-test-to-get-a-tools-output-fields) for choosing fields or adding a path manually.

## Find or change an existing event

When you don't have the event ID, use **List Events** with the attendee's confirmed email and a narrow time window. It matches the event's attendee email, not a name or email mentioned only in the title or notes. Ask the caller which result they mean before changing it.

Use the selected event's `event_id` with **Reschedule Event** or **Cancel Event**. Rescheduling keeps the original duration; both tools ask Google to notify all attendees. For a recurring event, use the ID of one occurrence returned by **List Events**. These tools reject changes to an entire recurring series, and **Reschedule Event** also rejects all-day events.

## Test the configuration

Start with **Check Availability** or **List Events** on a calendar you control. In **Run a test**, supply concrete sample values for inferred inputs. For attendee arrays, add sample rows and fill every required email; **Every item** instructions aren't executed by the test panel. Use an [agent test](https://docs.retellai.com/test/test-web.md) to verify collection from a conversation.

> [!WARNING]
>
> Tests call Google Calendar for real. Testing **Book Event**, **Reschedule Event**, or **Cancel Event** changes calendar events and can send attendee notifications. Use a test calendar and addresses you control.

## Troubleshooting

> [accordion] Availability includes evenings or times I don't want to offer
>
> The tool subtracts busy times from the window you request. It doesn't apply working hours, buffers, minimum notice, or Google appointment-schedule rules. Restrict the time window and tell the agent which hours it may offer.

> [accordion] List Events can't find the caller's booking
>
> Check the selected calendar, attendee email, and time window. An event created without that email in its attendee list won't match. Narrow the search if there are many results; the tool returns a bounded list.

> [accordion] The calendar is inaccessible or a write fails
>
> Check the connected Google account's access to the selected calendar. A successful connection check doesn't guarantee access to every calendar. Restore the calendar permissions or [reconnect the account](https://docs.retellai.com/integrations/google-calendar.md#faq), then retry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.