# Configure calendar booking actions

> Connect Cal.com or Calendly, create a booking action, link it to a voice agent, and test times, time zones, and meeting links before launch.

Canonical: https://help.spacebrain.ai/chat-and-voice/calendar-booking-actions/
Last modified: 2026-09-25T00:00:00.000Z

A calendar booking action lets a voice agent check your availability and book an appointment while it's talking to a caller. It uses an event type from Cal.com or Calendly. This guide is for whoever sets up the agent and the calendar.

## Before you begin [#before-you-begin]

* **One calendar provider per agent.** An agent can use several event types, but they must all come from the same provider, either Cal.com or Calendly.
* **An active event type** in Cal.com or Calendly with the right host, length, location, availability, buffers, and notice period. Spacebrain uses these settings; it doesn't change them.
* **A monitored email address** for booking confirmations.
* **Your time zone** in the full format, such as `America/Vancouver`, not a short form like `PST`.
* **A free test slot** you can book and then cancel.
* **Role:** connecting a calendar may need a workspace admin. Creating, editing, or linking actions also needs admin access; others can only view them.

## Where to find it [#where-to-find-it]

* **Connect the calendar:** **Integrations → Cal.com** or **Calendly**.
* **Create and link actions:** **Chat & Voice → Agents**, open the agent, then select **Actions** in the sidebar. Booking actions are under **Calendar booking**.

## Step 1: Connect Cal.com or Calendly [#step-1-connect-calcom-or-calendly]

1. Open **Integrations** and select **Cal.com** or **Calendly**.
2. Select **Connect**. If you see **Admin access required**, ask a workspace admin to do this step.
3. Enter a display name that makes clear which calendar account this is.
4. Sign in or paste the API key, depending on what the screen asks for.
5. Check the integration shows **Connected**.
6. In Cal.com or Calendly, confirm your event type is active and bookable.

> **Warning — Calendly free plan warning**
>
> If Spacebrain shows **Calendly Free Plan Detected**, fix the plan requirement before relying on the action. The drawer may still let you select **Continue**, but bookings might not work.

## Step 2: Create the booking action [#step-2-create-the-booking-action]

1. Open the agent's **Actions** page. Under **Calendar booking**, select **Create booking action**.
2. Choose **Cal.com** or **Calendly**. You should see **Your … account is successfully connected.** If it says **Please connect your … account to continue.**, go back to Step 1.
3. Pick an event under **Select Event Type**. Spacebrain shows its **Event Name**, **Duration**, and **Description**.
4. Select **Continue**.
5. Enter the **Email** for booking confirmations. Turn on **Send Confirmation SMS** if you also want a text confirmation.
6. Optionally choose **GMeet** or **Zoom** under **Meeting Link**.
7. Set the **Timezone** and the first-offer settings (see below).
8. Select **Save**.

You'll see **Booking action created and added to this agent.** If you see that it was saved but couldn't be added, select **Add existing** to link it. Don't create it again.

### First-offer settings [#first-offer-settings]

These shape the times the agent suggests first. They don't change your real availability.

| Setting                       | Range | Starts at |
| ----------------------------- | ----- | --------- |
| **Days for offering dates**   | 1–14  | 3         |
| **Appointment slots per day** | 1–10  | 3         |
| **Hours between slots**       | 1–8   | 3         |

The **Timezone** is used to look up availability for incoming calls. For outgoing calls, the caller's time zone can be passed in with the `{cal_timezone}` variable.

> **Warning — Initial booking date isn't saved**
>
> The drawer shows **Initial booking date**, but it isn't kept after you save. Set date limits in Cal.com or Calendly instead.

## Step 3: Tell the agent when to book [#step-3-tell-the-agent-when-to-book]

Adding the action gives the agent the ability to book. Your instructions tell it how. In the agent's **Prompt**, cover:

* When to offer a booking.
* What details to collect, such as name, email, and reason for the visit.
* That it must repeat the date, time, and time zone and get a clear "yes" before booking.
* What to say if no times are free or the booking fails.

**Example:** "When a caller wants an appointment, ask for their name and email. Offer the first available times. Before booking, repeat the day, date, time, and time zone and ask them to confirm. If booking fails, apologize and say the clinic will call them back."

## Meeting links [#meeting-links]

Choosing **GMeet** or **Zoom** records your preference. It doesn't sign in to Google or Zoom for you.

1. Make sure the event type's host can create that kind of meeting.
2. Make a test booking.
3. Open the event in your calendar and check a join link exists and works for a guest.

## Reuse, edit, and remove actions [#reuse-edit-and-remove-actions]

One booking action can be shared by several agents.

* **Add existing** shows **Shared booking actions** in your workspace. Select **Add** to link one to this agent.
* **Edit** changes the action for every agent that uses it.
* **Unlink** removes it from this agent only. It stays in your workspace.
* **Delete** asks you to confirm with **Delete for everyone**. This removes it from your workspace and every agent that uses it.

Deleting an action doesn't cancel bookings already made. Manage those in Cal.com or Calendly.

### Switch providers [#switch-providers]

If an agent uses one provider, the other provider's shared actions show **Different provider**. To switch, unlink all of the agent's booking actions first, then create and test new ones for the other provider.

## Test before launch [#test-before-launch]

1. Note a free slot: host, event type, length, and time zone.
2. Make a test call to the agent.
3. Ask for a date, then change your mind about the date or time zone.
4. Check the agent only offers times that are actually free.
5. Pick a slot and listen for the agent to repeat the details.
6. Check the booking in Cal.com or Calendly: host, attendee, length, time zone, and status.
7. Check the invitation, meeting link, confirmation email, and text if enabled.
8. Try again with no free times, an unclear time zone, a date too far out, and asking twice.
9. Cancel the test booking in your calendar.

If the agent says it booked but there's no event, treat it as a failed booking. Check the calendar before trying again so you don't create a duplicate.

## If something goes wrong [#if-something-goes-wrong]

| What you see                                          | What to do                                                                                                                                |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Please connect your … account to continue.**        | Connect the provider under **Integrations**, then reopen the action.                                                                      |
| **No event types found.**                             | Create an active event type in your calendar, then reopen the drawer.                                                                     |
| Other provider's actions show **Different provider**  | Unlink all booking actions from this agent before switching.                                                                              |
| Wrong times offered                                   | Check the action's time zone, `{cal_timezone}`, your calendar's time zone, buffers, and notice period. Watch for daylight saving changes. |
| No meeting link                                       | Check the event type's location setting and the host's Google or Zoom connection.                                                         |
| Agent says booked, but nothing appears                | Treat it as failed. Check the calendar before retrying.                                                                                   |
| **Agent actions are not available for this account.** | Ask your account administrator.                                                                                                           |

## FAQ [#faq]

### Can the agent cancel or reschedule bookings? [#can-the-agent-cancel-or-reschedule-bookings]

Don't assume so. This action books appointments. Handle changes in Cal.com or Calendly unless a separate action for changes appears and passes your tests.

### Can two agents share one booking action? [#can-two-agents-share-one-booking-action]

Yes. Edits apply to both. Use **Unlink** to remove it from one agent only.

### What happens if I disconnect the calendar? [#what-happens-if-i-disconnect-the-calendar]

Agents using it can't book. Pause those agents' traffic first, then reconnect or replace the action and test again.

## Next step [#next-step]

If the agent also needs to text callers, see [Configure in-call SMS actions](/chat-and-voice/in-call-sms-actions/).