# Google Calendar

Aktify can schedule appointments directly on your Google Calendars. During a conversation, the Aktify AI agent offers your real open time slots to a lead, and when the lead confirms, Aktify books the appointment on the assigned rep's calendar — no manual back-and-forth required.

This guide walks through connecting Google Calendar to a campaign. For behavior shared with GoHighLevel — timezones, the one-scheduler-per-campaign rule, arrival windows, and more — see the [Appointment Scheduling overview](./index).

## How it works

Aktify connects to Google Calendar using a dedicated **service account** — a Google identity that belongs to Aktify. You grant Aktify access by **sharing your calendar** with that service account, the same way you'd share a calendar with a coworker. There is no password to hand over and no OAuth login screen.

Once a calendar is shared, Aktify can:

- **Read availability** — so the agent only offers slots that are actually open.
- **Create, reschedule, and cancel events** — so confirmed appointments land on the rep's calendar automatically.

You can connect **multiple reps**, each with their own calendar, to a single campaign. Aktify spreads bookings across them and respects the capacity you configure.

## Before you begin

You'll need:

- The **Aktify service account email address**:

  ```
  aktify-gcal-scheduler@aktify-api.iam.gserviceaccount.com
  ```

  This is the Google identity you'll share your calendar with. It's the same for every Aktify customer.
- The **Google Calendar ID** for each calendar you want to take appointments on (see [Step 2 — Find your Calendar ID](#step-2--find-your-calendar-id)).
- Portal access with an **Admin** or **Editor** role on the campaign you're configuring.

## Step 1 — Share your calendar with Aktify

Repeat this for each rep's calendar.

1. Open [Google Calendar](https://calendar.google.com) as the rep (or as an admin who manages the rep's calendar).
2. In the left sidebar, hover over the calendar you want to share, click the **⋮** menu, and choose **Settings and sharing**.
3. Scroll to **Share with specific people or groups** and click **Add people and groups**.
4. Enter the Aktify service account email: `aktify-gcal-scheduler@aktify-api.iam.gserviceaccount.com`
5. Set its permission to **Make changes to events**.
6. Click **Send**.

:::info Why "Make changes to events"?
Aktify needs to both read availability and write appointments. The **Make changes to events** permission grants exactly that. The broader **Make changes and manage sharing** permission also works but isn't required.
:::

## Step 2 — Find your Calendar ID

You'll enter a **Calendar ID** for each rep in the Portal.

1. In Google Calendar, open **Settings and sharing** for the calendar (same menu as above).
2. Scroll to **Integrate calendar**.
3. Copy the **Calendar ID**.

A primary calendar's ID is usually the account's email address (for example, `rep@yourcompany.com`). A secondary calendar's ID is a long string ending in `@group.calendar.google.com`.

## Step 3 — Configure Google Calendar in the Portal

1. Open the campaign and go to **Settings → Integrations**.
2. Under **Appointment Scheduling**, select **Google Calendar**.
3. **Add your reps.** For each rep, add a row with a **name** and a **Calendar ID**. Use **Add rep** to connect more than one.

   :::tip Just one calendar? That's fine.
   If you want to book everything onto a single shared calendar, add just one rep row. The **name** is only a label used inside the Portal — it can be anything you like (for example, "Main Calendar" or your business name). Only the **Calendar ID** has to be exact.
   :::
4. **Test access.** Click **Test access** next to each rep. Aktify checks that the calendar has been shared with the service account and reports back inline. If you see a "share not in place" message, revisit [Step 1](#step-1--share-your-calendar-with-aktify) — the share may not have been sent, or it may have been blocked (see [Google Workspace notes](#google-workspace-notes)).
5. **Set open hours.** Configure a single open-hours window per day, and uncheck any days the business is closed. Defaults to **9:00 AM – 5:00 PM, Monday–Friday**.
6. **Set your scheduling options** (see the [Configuration reference](#configuration-reference) below).
7. **Save.** Saving activates Google Calendar scheduling for the campaign.

:::warning
Saving Google Calendar as active **deactivates any other scheduler** on this campaign. See [one scheduler per campaign](./index#one-scheduler-per-campaign).
:::

## Configuration reference

| Setting | What it controls |
| :--- | :--- |
| **Reps** | One or more `{ name, Calendar ID }` rows. The name is a display label only; the Calendar ID must be exact. Use a single row to book everything onto one shared calendar, or one row per rep to spread bookings across calendars. |
| **Open hours** | The bookable window for each day of the week. One window per day; uncheck a day to mark it closed. Defaults to 9–5, Mon–Fri. |
| **Slot length** | The length of each appointment slot, in minutes. |
| **Appointments per slot** | How many appointments can be booked into the same time slot before it's considered full. Defaults to `1`. |
| **Days ahead** | How far into the future the agent is allowed to offer slots. |
| **Schedule date range** | An optional start/end date that bounds when appointments may be scheduled. |
| **Timezone** | The IANA timezone of the calendar / business location (for example, `America/Denver`). See [Timezones](#timezones). |
| **Arrival window** | For field-service appointments, the size of the technician arrival window in hours. Leave at `0` for exact-time appointments. See [Arrival windows](#arrival-windows). |
| **Event memo** | Optional text used as the prefix of the calendar event title. With a memo, events are titled `<memo> - <First Last>`; without one, `Appointment with <First Last>`. |

## How scheduling works for your leads

### Availability

The agent only offers slots that fall within your open hours, lie inside your scheduling window, and aren't already full. When **appointments per slot** is greater than one, a slot stays bookable until it reaches capacity — at which point the agent stops offering it and suggests the next open time instead.

With multiple reps, capacity is the sum across reps. For example, 3 reps with **appointments per slot** of 2 allows 6 concurrent appointments in the same slot.

### Timezones

Set the **Timezone** to the IANA timezone where the calendar (and business) lives — for example, `America/New_York`, `America/Chicago`, or `America/Denver`. Aktify books in this timezone and converts each offered time into the lead's own local timezone (see [how timezones work](./index#leads-always-hear-their-own-local-time)).

:::tip
If you leave the timezone unset, Aktify falls back to the calendar's own Google timezone setting. Setting it explicitly is recommended so availability and confirmations are always unambiguous.
:::

### Arrival windows

Set the **Arrival window** field to the number of hours in the window, or leave it at `0` for exact-time appointments. See [arrival windows](./index#arrival-windows) for how it's used.

## Google Workspace notes

Connecting a **Google Workspace** calendar works exactly like a personal Gmail calendar — share the calendar with the service account and you're done. A couple of admin-controlled settings are worth knowing about:

:::warning External sharing must be allowed
If your Google Workspace administrator has **disabled external calendar sharing**, the share you send in [Step 1](#step-1--share-your-calendar-with-aktify) will silently fail — Google drops the external recipient without an error, and Aktify never gains access. The calendar will then look completely free, and bookings will fail.

If **Test access** reports that the share isn't in place even though you sent it, ask your IT admin to allow `aktify-gcal-scheduler@aktify-api.iam.gserviceaccount.com` as an exception to external sharing.
:::

:::info Audit transparency
Every appointment Aktify books appears in your Google Workspace Calendar audit log, attributed to the service account — so admins always have a full record of what was scheduled.
:::

## Troubleshooting

| Symptom | Likely cause | Fix |
| :--- | :--- | :--- |
| **Test access** reports the share isn't in place | The calendar wasn't shared with the service account, the wrong address was used, or external sharing is blocked | Re-do [Step 1](#step-1--share-your-calendar-with-aktify); confirm the exact service account email; check Workspace external-sharing settings |
| The agent offers slots that are already busy, or every slot looks open | The calendar isn't actually shared, so Aktify reads it as empty | Run **Test access** and confirm the share; a calendar with no access reads as 100% free |
| Bookings appear at the wrong time | Timezone misconfigured | Set **Timezone** to the calendar's IANA timezone (see [Timezones](#timezones)) |
| Appointments stop being offered for a popular time | The slot reached its **appointments per slot** capacity | Increase capacity, add another rep, or leave as-is if the slot is genuinely full |

## FAQ

**Do I need to give Aktify my Google password or sign in with OAuth?**
No. Access is granted entirely by sharing your calendar with the Aktify service account. You can revoke it at any time by removing that share.

**Can I connect more than one rep?**
Yes. Add a row per rep, each with their own Calendar ID. Aktify books across all connected reps and respects the per-slot capacity.

**Can I use both Google Calendar and GoHighLevel on the same campaign?**
No — see [one scheduler per campaign](./index#one-scheduler-per-campaign).

**How do I disconnect Google Calendar?**
Disable Google Calendar for the campaign in the Portal, and optionally remove the service account from your calendar's share list in Google Calendar.