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

# Calendar Integration

> Let the AI book meetings on your Google Calendar or Outlook Calendar during a live call.

When Calendar Integration is turned on, the AI assistant can offer a meeting and check your real availability. It can then book the slot directly on your calendar. It does all of this during the same phone call. hyzl supports both **Google Calendar** and **Outlook Calendar**. The AI presents times in the contact's local timezone. hyzl emails a calendar invite automatically, with a video meeting link where the provider supports it (see [Video Conferencing](#video-conferencing)).

This is different from the Meeting Link follow-up SMS, which sends the contact a scheduling link to fill in themselves. Direct booking commits the meeting on the call, while you have the contact's attention.

## What you need

* A Google account with Google Calendar, **or** a Microsoft account with Outlook Calendar. Both work/school (Microsoft 365) and personal (Outlook.com, Hotmail, Live) accounts are supported
* An AI Calling campaign (or the willingness to create one)
* Permission to connect calendars at your account or team level

## Connect your calendar

Connect your calendar once at the account level. The same connection is then available to any campaign you configure. You can connect Google, Outlook, or both.

### Google Calendar

1. Open **Settings** from the avatar menu
2. Find the **Google Calendar** section
3. Click **Connect Google Calendar**
4. Sign in with your Google account in the popup window
5. Grant calendar access when Google asks. hyzl requests permission to read your busy times and create new events.
6. Choose which calendar to use from the dropdown. It defaults to your **Primary** calendar.
7. Click **Save**

### Outlook Calendar

1. Open **Settings** from the avatar menu
2. Find the **Outlook Calendar** section, right alongside Google Calendar
3. Click **Connect Outlook Calendar**
4. Sign in with your Microsoft account in the popup window. Work/school (Microsoft 365) and personal (Outlook.com, Hotmail, Live) accounts both work.
5. Grant calendar access when Microsoft asks. hyzl requests permission to read your busy times and create new events.
6. Choose which calendar to use from the dropdown. It defaults to your primary **Calendar**.
7. Click **Save**

For either provider, the connection status updates to **Connected**, with the calendar's timezone shown alongside it. Your AI assistant can now book meetings on this calendar for any campaign that has booking turned on. You can change the calendar or disconnect at any time from the same Settings section.

<Note>
  The connection is per-user. On a team, every member who wants the AI to book on their calendar must connect it themselves. They do that from their own Settings page.
</Note>

## Connect both providers

You can connect Google Calendar and Outlook Calendar at the same time. The AI books on exactly one of them:

* The **most recently connected** provider becomes the active one by default
* A radio selector in the booking settings lets you choose which connected provider the AI books on. You can switch any time without reconnecting.
* Disconnecting the active provider automatically falls back to the other connected provider, if there is one

## Set up booking on a campaign

Booking is opt-in per campaign. It is off by default, even after the calendar is connected. Turn it on inside the campaign you want it for.

1. Open the campaign in the campaign editor
2. Go to the campaign **Options** step
3. Find the **Direct Calendar Booking** section
4. Turn **Direct Booking** on
5. Choose whose calendar to book on. It defaults to the campaign owner. On a team, you can choose any team member who has connected their calendar.
6. Set the meeting **length** in minutes (30 is a good default)
7. Set the **availability window**: the days of the week and the start and end time the AI can offer. hyzl reads that window in the calendar owner's timezone.
8. Set **buffer times** before and after each meeting. The AI does not offer slots that overlap with these.
9. Set the **minimum notice** (the AI will not offer anything sooner than this many minutes from now)
10. Set the **look-ahead window**: how many days into the future the AI can look for slots
11. Choose the **meeting type**:
    * **Video meeting**. hyzl creates a video meeting link and puts it in the calendar invite. The link is Google Meet or Microsoft Teams, depending on the connected provider. See [Video Conferencing](#video-conferencing) for the personal-Microsoft-account caveat.
    * **Phone**. The meeting happens by phone. hyzl puts the contact's phone number on the event.
    * **In-person**. Provide an address that goes on the event.
12. Customize the **meeting title** and **description** templates. The calendar invite shows what you write here.
13. Use the variables (e.g. `{recipient.firstName}`) to personalize the templates per call
14. Review the campaign
15. Launch the campaign as normal

If your campaign owner has not connected a calendar, the **Options** step shows an inline prompt. The prompt links to Settings.

<Tip>
  Add a buffer of at least 5 to 10 minutes after each meeting. Back-to-back calls then do not collide if a meeting runs over.
</Tip>

## Video conferencing

Which video link the invite carries depends on the connected provider:

| Provider                  | Video link                                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Google Calendar**       | Google Meet, created automatically and included in the invite                                                            |
| **Outlook (work/school)** | Microsoft Teams, created automatically and included in the invite                                                        |
| **Outlook (personal)**    | No video link. Microsoft does not support adding Teams links to events on personal accounts (Outlook.com, Hotmail, Live) |

<Warning>
  Connect a work or school Microsoft account, or Google Calendar, when a video
  link matters to you. On a **personal Microsoft account** hyzl still books the
  meeting, and the contact still gets the calendar invite by email. That invite
  carries no video meeting link. The AI then tells the contact the meeting
  details are in the invite, instead of promising a link.
</Warning>

## What the contact hears

The AI guides the contact through the booking naturally. A typical conversation:

> **AI**: Would you like to set up a 30-minute meeting?
>
> **Contact**: Sure.
>
> **AI**: What is your email address?
>
> **Contact**: john at example dot com
>
> **AI**: Let me read that back: J as in Juliet, O, H, N at example dot com. Did I get that right?
>
> **Contact**: Yes.
>
> **AI**: Great. I have Tuesday at 2 PM Eastern available. That is 11 AM your time. Does that work?
>
> **Contact**: Yes.
>
> **AI**: Booked. You will get a calendar invite by email shortly.

The NATO read-back ("J as in Juliet…") is automatic. It is how the AI confirms the email letter-by-letter. That way a one-character mistake does not send the invite into a void.

<Note>
  The invite email comes from whichever provider the AI booked on. Google Calendar sends it when Google is the active provider. Outlook sends it when Outlook is the active provider.
</Note>

## Timezones

There are three timezones in play during a booking. hyzl handles all three for you, but it is worth knowing how they line up:

| Timezone           | What It Controls                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Calendar owner** | Defines the availability window. "9 AM to 5 PM, Monday to Friday" means 9 to 5 in the calendar owner's timezone.                |
| **Contact**        | What the AI reads out loud. Inferred automatically from the contact's phone area code, then confirmed verbally during the call. |
| **UTC**            | What is actually stored on the calendar event. The contact's invite email renders in their own timezone wherever they read it.  |

You do not need to configure anything beyond your availability window. The AI does the conversion in real time.

## Work on a team

Each team member connects their own calendar (Google or Outlook) from their own Settings page. Calendars are not shared across the team automatically.

On a team, the **calendar owner** dropdown lists every team member who has connected a calendar. The dropdown sits in the **Direct Calendar Booking** section of the **Options** step. Choose whichever team member's calendar the meetings should land on for this campaign. The calendar owner does not have to be the campaign creator. A manager can build a campaign that books on a salesperson's calendar.

## Mid-call rescheduling

Contacts sometimes change their mind about the slot they just booked. The AI handles this on the same call:

* The contact says "Actually, can we make it Wednesday instead?"
* The AI checks the new slot against the calendar
* If the new slot is free, the AI moves the meeting and confirms verbally
* If the new slot is taken, the AI offers the next available alternatives

The AI can only move meetings it booked on this same call. It cannot touch unrelated events on your calendar.

## Fix common problems

### "Calendar access has expired"

This can happen with either provider. The refresh token expires if it is not used for a long time, or if you change your account password. Reconnect your calendar from **Settings → Google Calendar** or **Settings → Outlook Calendar**, whichever shows the expired connection. The campaign keeps running in the meantime. The AI skips booking on calls until you reconnect.

### "Need admin approval" when connecting Outlook

Some Microsoft 365 work/school organizations restrict which apps users can grant access to. If your tenant does, the Microsoft sign-in popup shows **"Need admin approval"** (error code AADSTS65001) instead of the consent screen. Ask your IT administrator to approve calendar access for hyzl. When they have, reconnect from Settings. Personal Microsoft accounts are never affected by this.

### Direct Booking is on but the AI did not offer to book

Check three things:

1. Confirm the campaign owner has a connected calendar in **Settings**
2. Confirm the campaign's **Direct Booking** setting is on
3. Confirm the contact's call reached a stage where booking made sense

The AI does not open with "want to book a meeting?". It offers booking when the conversation reaches the right point.

If all three look right and you still do not see booking offers in transcripts, run a test call. Listen for whether the AI gets a chance to suggest a meeting at all. The call may be ending before that point.

### I want to turn booking off for one campaign but keep it for others

You configure booking per campaign. Open the campaign that should not book, go to the **Options** step, and turn **Direct Booking** off. The calendar connection itself stays in place.

### Two contacts want the same slot at the same time

hyzl handles this automatically. The first contact to confirm wins the slot. The AI tells the second contact the slot was just taken and offers the next available alternatives. The conversation continues without the AI getting confused.

### The contact gave a typo'd email

The AI reads the address back letter-by-letter using the NATO alphabet ("J as in Juliet, O as in Oscar…"). It then asks the contact to confirm before booking. If the contact confirms a wrong character, the invite goes to the wrong inbox. hyzl cannot detect this. You will see the failed delivery if your calendar shows attendee responses.

### No video link on a booked meeting

Two common causes:

* **The wrong meeting type.** You chose **Phone** or **In-person** instead of **Video meeting**. Check the meeting type in the campaign's **Options** step. Re-launch the campaign.
* **A personal Microsoft account.** The AI booked on Outlook.com, Hotmail, or Live. Teams links are not available there. The invite still goes out with the meeting details, and it carries no link. See [Video Conferencing](#video-conferencing).

## What hyzl stores

The same applies to both providers. When you connect Google Calendar, hyzl stores:

* A refresh token. hyzl uses it to read your busy/free schedule and create new events on the calendar you chose.
* The calendar ID and timezone you chose
* A timestamp of the connection

When you connect Outlook Calendar, hyzl stores the equivalent:

* An encrypted Microsoft refresh token. hyzl uses it to read your busy/free schedule and create new events on the calendar you chose.
* The calendar ID and timezone you chose
* A timestamp of the connection

hyzl does **not** read the contents of your existing events. It reads only whether each window is free or busy. New events created by the AI live on your provider's servers, Google or Microsoft, not hyzl's. You see them in your calendar like any other event.

You can disconnect either provider at any time from **Settings**. Disconnecting revokes hyzl's access immediately. If the disconnected provider was the active one, the AI switches to your other connected provider. If no connected provider remains, booking turns off on every campaign that was using your calendar.

## Next steps

<CardGroup cols={2}>
  <Card title="Create a campaign" icon="plus" href="/docs/ai-calling/creating-a-campaign/call-details">
    Build a campaign that uses calendar booking
  </Card>

  <Card title="Test Call" icon="phone" href="/docs/ai-calling/creating-a-campaign/test-call">
    Check the booking flow before going live
  </Card>
</CardGroup>