Calendars

Calendars let you publish bookable schedules — patient appointments, consultations, salon visits, office hours, and more. Each calendar has its own availability, event types, and permissions, and your AI agents can check availability and book appointments on a member's behalf.

Creating a Calendar

Go to Calendars to see all calendars in your workspace. The page has three tabs: Calendars, Event Types, and Sync.

1. On the Calendars tab, click Create Calendar
2. Fill in the form:
   • Calendar Name — e.g., "Office Hours" or "Dr. Smith's Schedule"
   • Description — optional details about the calendar
   • Timezone — used for all event times on this calendar
   • Color — a hex color to distinguish the calendar in views (e.g., #3B82F6)
   • Public Calendar — allow external users to view and book appointments
   • Slug — URL-friendly identifier; auto-generated from name if left empty
3. Click Create Calendar

After creating, click the calendar in the table to open its Day, Week, Month, or List view, where you can add events, manage schedules, and configure permissions.

Adding Availability Schedules

Schedules tell the calendar when bookings are allowed (or explicitly blocked).

1. Open the calendar and go to the Schedules tab
2. Click Add Schedule
3. Fill in the form:
   • Schedule Name — e.g., "Office Hours" or "Lunch Break"
   • Description — optional
   • Availability Type — Available (open for bookings) or Unavailable (blocked)
   • Recurrence — Once, Daily, Weekly, or Monthly
   • Start Time / End Time — time window for the schedule
   • Days of Week — for weekly recurrence, pick which days apply
   • Recurrence End Date — optional cutoff for repeating schedules
4. Click Save

Stack schedules to model real-world hours. For example, a weekly Available schedule from 9 AM–5 PM combined with a weekly Unavailable "Lunch Break" from 12 PM–1 PM will keep noon-hour slots out of bookable times.

Adding Event Types

Event types define what can be booked on your calendars. They live on the workspace-wide Event Types tab and can be reused across calendars.

1. On the Calendars page, click the Event Types tab
2. Click Create Event Type
3. Fill in the form:
   • Name — e.g., "30-Min Consultation"
   • Slug — URL-friendly identifier (e.g., one-on-one-meeting)
   • Description — what this appointment includes
   • Duration — appointment length in minutes
   • Color — visual identifier
   • Buffer Before / Buffer After — minutes of prep or cleanup around each appointment
   • Min Attendees / Max Attendees — how many people can attend
   • Active — toggle to enable or disable the event type
4. Click Create

Restrict an event type to specific schedules by selecting it on the schedule's form — useful when, for example, only certain hours allow long appointments.

Granting Permissions

Permissions control who can see, book on, and administer each calendar.

Member Role Permissions

1. Open the calendar and go to Settings → Permissions
2. Add a member role and assign it a permission level
3. Click Save

You can also restrict individual event types to specific roles — for example, customers can book "Consultations" but not "Staff Meetings."

AI Agent Permissions

To let an AI agent check availability or book appointments during a workflow:

1. Open the workflow and edit a task
2. Go to the Calendars tab on the task editor
3. Click Choose… and select a calendar
4. Set the permission level — Free/Busy, Read, Write, or Admin
5. Optionally pick a specific event type (or leave as "All event types")
6. Click Save

For appointment booking, grant Write. The AI can then check availability, suggest open slots, and create appointments on the member's behalf.

Google Calendar Sync

Gravity Rail can sync calendars bidirectionally with Google Calendar over OAuth. Events you create in Gravity Rail push to Google, and events on your Google Calendar pull back into Gravity Rail — so a single source of truth works across both systems.

This is a different path from the iCal Feed Subscription below. iCal is one-way, read-only, and works with any calendar client. Google Calendar sync requires a Google account and is read/write.

HIPAA note for healthcare workspaces. Google Calendar is a third-party system and, for most Gravity Rail customers, is not covered by a Business Associate Agreement. Avoid putting Protected Health Information (patient names, diagnoses, medication details, clinical notes) in event titles, descriptions, or attendee notes before enabling sync. Use generic titles (e.g., "Consultation — Member #1234") and keep clinical detail in the Gravity Rail chat or data record instead.

Connecting Google Calendar

1. Go to Calendars and open the Sync tab
2. In the Google Calendar card, click Connect Google Calendar
3. Sign in to Google and grant calendar access on the consent screen
4. You'll be redirected back to the Sync tab and see a green Connected badge with your Google email

Once connected, the Sync tab lists all Google Calendars on your account (including your primary calendar and any shared calendars you have access to).

Linking a Calendar

Each Gravity Rail calendar links to exactly one Google Calendar. You can link in either direction:

From the Sync tab (creates a new local calendar):

1. Find the Google Calendar you want to sync in the Your Google Calendars list
2. Click Connect next to it
3. A new Gravity Rail calendar is created with the Google Calendar's name, timezone, and color, and the two are linked

From an existing calendar (links an existing local calendar):

1. Open the calendar you want to sync
2. Scroll to the Google Calendar Sync section
3. Pick a Google Calendar from the dropdown
4. Click Link to Google Calendar

After linking, an initial sync pulls every event from the Google Calendar into Gravity Rail. Going forward:

• Events created in Gravity Rail are pushed to the linked Google Calendar
• Events created, edited, or deleted in Google Calendar flow back into Gravity Rail
• Attendee response statuses (accepted, declined, tentative) sync both ways

Sync Status Indicators

Each calendar row shows a sync status dot on the Calendars tab, and individual events carry a status as they move between systems:

Manually Running a Sync

Sync runs automatically, but you can trigger it on demand:

1. Open the linked calendar
2. In the Google Calendar Sync section, click Sync Now
3. Wait for the confirmation — the button shows Syncing... while it runs

Sync Now only appears once a calendar is linked to a Google Calendar. If you don't see the button, the calendar is Not Linked — follow Linking a Calendar first.

Use Sync Now after you've made a batch of changes in Google Calendar and don't want to wait, or when resolving a FAILED status.

Reconnecting When Permissions Change

The Sync tab shows a yellow warning reading "Your Google Calendar permissions need to be updated" when the OAuth grant Gravity Rail holds is no longer sufficient. Common causes:

• Token revoked — the user removed Gravity Rail from their Google third-party access page, or Google expired the refresh token after a long period of inactivity
• Scope change — Gravity Rail began requesting an additional calendar scope (e.g., read-only → read/write), and the existing grant doesn't cover it
• Google Workspace admin policy — a domain admin restricted or reset third-party app access for the account
• Password reset or 2FA change — Google invalidates outstanding refresh tokens after certain account security events

To restore sync:

1. Click Reconnect Google Account on the warning banner
2. Sign back into Google and approve the calendar scopes
3. The banner clears and sync resumes

Unlinking a Calendar

Unlinking stops sync but keeps all your local events.

From the Sync tab:

1. Find the linked Google Calendar in the list
2. Click Disconnect next to it
3. Confirm in the dialog

From the calendar's Google Calendar Sync section:

1. Click Unlink Google Calendar
2. Confirm

When you unlink:

• The connection to Google is removed
• New events are no longer synced in either direction
• Previously-synced events remain in your Gravity Rail calendar as local-only events
• Events in Google Calendar are untouched

Disconnecting Your Google Account

To remove Gravity Rail's access to Google entirely (affects every linked calendar):

1. On the Sync tab, click Disconnect in the Google Calendar card
2. Every linked calendar reverts to local-only

You'll need to reconnect and re-link each calendar to resume syncing.

iCal Feed Subscription

The iCal feed is a one-way, read-only publication of a Gravity Rail calendar to any calendar client (Google Calendar, Apple Calendar, Outlook). Events flow out of Gravity Rail; nothing flows back. Use this when you just need to see Gravity Rail events in another app — for the full two-way experience with Google Calendar, use Google Calendar Sync instead.

Generating a Feed URL

1. Open the calendar
2. Open the iCal Feed Subscription section in the calendar settings
3. Click Generate Token
4. Copy the Feed URL

To rotate or disable access, use Regenerate Token (existing subscriptions break and must be updated) or Revoke Token (disables the feed entirely).

Subscribing in Google Calendar

1. Open Google Calendar
2. Next to Other calendars, click + → From URL
3. Paste the feed URL and click Add calendar

Subscribing in Apple Calendar

1. Open the Calendar app
2. Choose File → New Calendar Subscription
3. Paste the feed URL and click Subscribe
4. Pick an update frequency and click OK

Subscribing in Outlook

1. Open Outlook Calendar
2. Click Add Calendar → From Internet
3. Paste the feed URL and click OK

External apps refresh the feed every 15–60 minutes, depending on the app.

Protect your feed URL. Anyone with the link can read your calendar. If a URL is exposed, regenerate the token and update the subscription in your calendar app.

Tips

• Start with Free/Busy for AI — Test the booking flow with read-only access before granting Write permission.
• Use buffer time — Add a few minutes before and after each event type to prevent back-to-back appointments.
• Pick clear event type names — These appear in AI conversations and member-facing booking confirmations.
• Match timezone to the booker, not the operator — Event times are stored in UTC and rendered in the calendar's timezone.

Troubleshooting

"No available slots found"

• Check that availability schedules are configured on the calendar
• Verify the relevant schedule is Available (not Unavailable)
• Ensure the date range includes future dates
• Confirm the event type isn't restricted to a different schedule

"AI cannot book appointments"

• Verify the task has Write permission (not just Read or Free/Busy)
• Check that the calendar is selected in the task's Calendars tab
• Ensure the event type exists and is marked Active

"Calendar feed not updating"

• External calendar apps typically refresh every 15–60 minutes
• Try manually refreshing the subscription in the external app
• Verify the feed token hasn't been revoked or regenerated — if it was, update the subscription with the new URL

"Google Calendar events aren't syncing"

• On the Sync tab, confirm the Google Calendar card shows a green Connected badge
• Open the calendar and check the sync status indicator — FAILED means the last attempt errored; PENDING means it's still queued
• Click Sync Now in the Google Calendar Sync section to force a run
• If a yellow "permissions need to be updated" banner is showing, click Reconnect Google Account and re-grant calendar scopes
• Verify the local calendar is actually linked — an unlinked calendar shows Not Linked in the sync section

"Connected to Google but no calendars show up"

• Click Refresh Status on the Sync tab
• Make sure your Google account has at least one calendar (the primary calendar is always present)
• Disconnect and reconnect if the list stays empty — this forces Gravity Rail to re-fetch your calendar list from Google

"Booking conflicts"

• Check for overlapping Available schedules with different event type restrictions
• Verify buffer times aren't pushing neighboring appointments into unavailable windows

Related

• Calendar Booking — Configure calendar booking as an AI ability
• Workflows — Connect calendars to AI agents for automated booking
• Phone & Voice — Let callers book appointments by phone
• Actions — Send reminders and follow-ups around appointments