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

# Google Calendar

> Check availability and book appointments during voice calls

## Overview

The Google Calendar integration allows your voice agents to check
calendar availability and create events in real-time during phone calls.

<Note>
  Your agent can book appointments while talking to the caller -
  no manual follow-up required.
</Note>

## What You Can Do

| Feature                     | Description                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------- |
| **Check Availability**      | Query free/busy status for any time slot                                               |
| **Create Events**           | Book appointments with title, description, attendees                                   |
| **Booking Hours**           | Optionally restrict bookings to specific weekly time windows, including a midday break |
| **One Calendar per Person** | Up to five people, each with their own calendar and hours                              |
| **Timezone Support**        | Automatic handling (default: Europe/Paris)                                             |

## Setup

<Steps>
  <Step title="Connect Google Calendar">
    Go to **Integrations** → Click **Create Integration** → Select **Google Calendar**
  </Step>

  <Step title="Authorize Access">
    Sign in with your Google account and grant calendar permissions
  </Step>

  <Step title="Select Your Calendar">
    Choose which editable Google Calendar Tala should read and write. If you skip this
    selection, Tala falls back to your primary calendar for backward compatibility.
  </Step>

  <Step title="Optional: One Calendar per Person">
    If several people take appointments at your business, add one entry per person, up
    to five. Each carries a name, its own calendar and its own booking hours, so a
    part-time colleague never inherits the owner's schedule.

    On a call, Tala asks the caller who they would like to see. When they have no
    preference, it offers whoever is free and announces that person's name. The
    appointment is then created on that person's calendar, against her own booking
    hours, and a name Tala does not recognise is refused rather than guessed.

    Names must be distinct and no two people may share a calendar, otherwise Tala could
    not tell them apart out loud. Leaving a single unnamed calendar keeps the previous
    behaviour untouched.
  </Step>

  <Step title="Optional: Restrict Booking Hours">
    In the Google Calendar configuration dialog, define the weekly time windows Tala is
    allowed to book. Outside those windows, Tala will reject the slot even if the calendar is empty.

    A day can hold several windows, so a midday break is simply two windows, for example
    09:00 to 12:30 and 13:30 to 19:00. Tala never offers a time inside the break, and an
    appointment cannot start in one window and end in the next.
  </Step>

  <Step title="Enable in Workflow">
    In **Workflow Editor** → **Tools** → Enable **Calendar Tools**
  </Step>
</Steps>

<Note>
  If Google shows an "app not verified" warning during OAuth, click **Continue** to finish
  the connection flow.
</Note>

## How It Works During Calls

Your agent has access to two functions:

### Check Availability

```
Agent: "Let me check if Tuesday at 2 PM works..."
[Agent calls check_calendar_availability]
Agent: "I see you're free from 2 PM to 4 PM on Tuesday."
```

### Create Event

```
Agent: "Perfect, I'll book that appointment for you."
[Agent calls create_calendar_event]
Agent: "Done! You'll receive a calendar invite shortly."
```

## Example Conversation

<AccordionGroup>
  <Accordion title="Appointment Booking Flow">
    **Caller:** I'd like to schedule a consultation.

    **Agent:** Of course! When would work best for you?

    **Caller:** How about Thursday afternoon?

    **Agent:** Let me check... I have availability at 2 PM and 4 PM on Thursday.
    Which works better?

    **Caller:** 2 PM is perfect.

    **Agent:** Great! I've booked your consultation for Thursday at 2 PM.
    You'll receive a calendar invite at your email address. Is there
    anything else I can help with?
  </Accordion>

  <Accordion title="Booking With Several People">
    **Caller:** I'd like an appointment on Thursday.

    **Agent:** Of course. Would you like to see Sophie or Marie?

    **Caller:** Whoever is available, I don't mind.

    **Agent:** Marie is free at 2 PM on Thursday. Shall I book that with her?

    **Caller:** Yes, perfect.

    **Agent:** Done, Thursday at 2 PM with Marie.
  </Accordion>
</AccordionGroup>

## Technical Details

| Setting          | Value                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| OAuth Scopes     | `auth/calendar.events`, `auth/calendar.events.freebusy`, `auth/calendar.calendarlist.readonly` |
| Default Timezone | Europe/Paris                                                                                   |
| API Timeout      | 3 seconds (optimized for voice)                                                                |
| Calendar         | Selected calendar, or one per person (up to five), default primary                             |
| Booking Logic    | Busy slots plus optional Tala booking hours                                                    |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent can't access calendar">
    * Verify the integration shows as **Connected** in Integrations page
    * Check that **Calendar Tools** is enabled in your workflow
    * Re-authorize if you recently changed Google account permissions
  </Accordion>

  <Accordion title="Appointment landed on the wrong person">
    * Check that each person has a distinct name: two people the agent cannot tell apart out loud cannot be booked reliably
    * The agent never picks a person on its own when the caller named one, and refuses a name it does not recognise
  </Accordion>

  <Accordion title="Events not appearing">
    * Events are created on the selected calendar, on the calendar of the person the caller chose, or on the **primary** calendar if no selection was saved
    * Check the timezone matches your expectations
    * Verify the Google account has edit permissions
  </Accordion>

  <Accordion title="Agent proposes slots outside coaching hours">
    * Configure **Booking Hours** in the Google Calendar dialog to restrict the allowed windows
    * Tala does not filter empty slots by Google event type
    * If you need event-type-based scheduling, use a dedicated calendar or Calendly
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Google Sheets" icon="table" href="/integrations/google-sheets">
    Import contacts for campaigns
  </Card>

  <Card title="Workflow Tools" icon="wrench" href="/workflows/tools">
    See all available agent tools
  </Card>
</CardGroup>