Calendars and Appointment Booking

Gravity Rail's calendar system helps you manage appointments, schedule meetings, and automate booking through AI workflows.

What are Calendars?

Calendars in Gravity Rail are scheduling tools where appointments can be booked. Each calendar has:

• Availability schedules - When the calendar is open for bookings
• Event types - Types of appointments that can be booked (e.g., "Hair Cut", "Doctor Visit")
• Permissions - Control who can view and book appointments
• AI integration - Let AI agents book appointments automatically

Creating a Calendar

1. Go to Calendars
2. Click Create Calendar
3. Fill in the details:
   • Name: What you'll call this calendar (e.g., "Dr. Smith's Office Hours")
   • Description: Optional details about the calendar
   • Timezone: The timezone for all appointments
   • Color: A color to distinguish this calendar in views
   • Default Availability: Choose when the calendar is initially available:
     • Always Available - 24/7 bookings allowed
     • Weekday Business Hours - Monday-Friday, 9am-5pm
     • Always Unavailable - No bookings allowed (manual override only)
4. Click Create Calendar

Setting Up Availability

After creating a calendar, configure when appointments can be booked:

Viewing Availability

1. Open your calendar
2. The calendar view shows:
   • 🟢 Green blocks - Available time slots
   • 🔴 Red blocks - Unavailable/blocked time
   • Click any availability block to edit it

Creating Availability Schedules

1. From your calendar, go to the Availability tab
2. Click Add Schedule
3. Configure the schedule:
   • Name: "Office Hours", "Lunch Break", etc.
   • Type: Available or Unavailable
   • Recurrence:
     • Once - Single date/time block
     • Daily - Repeats every day
     • Weekly - Repeats on specific days of the week
   • Time: Start and end times
   • Event Types (optional): Restrict which appointment types can be booked
4. Click Save

Example Availability Setup:

Schedule: "Office Hours"
Type: Available
Recurrence: Weekly (Monday-Friday)
Time: 9:00 AM - 5:00 PM
Event Types: All

Schedule: "Lunch Break"
Type: Unavailable
Recurrence: Weekly (Monday-Friday)
Time: 12:00 PM - 1:00 PM

Creating Event Types

Event Types define the kinds of appointments that can be booked on your calendar:

1. Go to Calendar Event Types
2. Click Create Event Type
3. Configure:
   • Name: "30-Min Consultation", "Hair Cut", etc.
   • Description: What this appointment includes
   • Duration: How long the appointment takes (in minutes)
   • Buffer Time: Time before/after for prep or cleanup
   • Min/Max Attendees: How many people can attend
   • Color: Visual identifier
4. Click Create

Booking Appointments

Manual Booking

1. Open the calendar
2. Click on an available time slot
3. Fill in the appointment details:
   • Event Type: Choose from configured types
   • Title: Brief description
   • Attendees: Who will attend
   • Description (optional): Additional details
   • Location (optional): Where it will take place
4. Click Create Event

AI-Powered Booking

Let AI agents book appointments automatically by connecting calendars to workflows:

1. Configure Task Calendar Access

1. Go to your Workflows
2. Open a workflow and edit a task
3. Click the Calendars tab
4. Click Choose... and select a calendar
5. Set permissions using the toggle buttons:
   • 👁️‍🗨️ Free/Busy - AI can see if times are available
   • 👁️ Read - AI can view appointment details
   • ✏️ Write - AI can book appointments
   • 🔒 Admin - AI has full calendar control
6. Optionally select a specific Event Type (or leave as "All event types")
7. Click Save

2. Grant Appropriate Permissions

Choose permissions based on what you want the AI to do:

For appointment scheduling:

• Select Write permission
• This allows the AI to:
  • Check availability
  • Find open time slots
  • Book appointments
  • Cancel appointments

For availability checking only:

• Select Free/Busy permission
• The AI can:
  • See if times are available
  • Suggest open slots
  • But cannot book or modify

For viewing schedules:

• Select Read permission
• The AI can:
  • Check availability
  • List upcoming appointments
  • View appointment details
  • But cannot book or modify

3. Example: Appointment Booking Workflow

Scenario: Customer wants to book a doctor's appointment

Setup:

1. Create a workflow called "Appointment Scheduler"
2. Create a task with the system prompt:

   You are a helpful appointment scheduling agent.
   Help patients book appointments with our doctors.
   Always check availability before suggesting times.
   Confirm all bookings with the patient.
   

3. In the Calendars tab:
   • Select "Dr. Smith's Schedule"
   • Set permission to Write
   • Set event type to "Patient Consultation" (or "All event types")
4. Save the task

Customer Conversation:

Customer: "I need to schedule an appointment"

AI: "I'd be happy to help you schedule an appointment!
     Dr. Smith has availability next week.
     Would Tuesday at 2pm or Thursday at 10am work better for you?"

Customer: "Tuesday at 2pm please"

AI: "Perfect! I've booked your appointment with Dr. Smith
     for Tuesday, March 15th at 2:00 PM. You'll receive
     a confirmation via SMS."

Calendar Permissions

Control who can access and modify your calendars:

Permission Levels

• None - Cannot see or access the calendar
• Free/Busy - Can only see if time slots are available (not event details)
• Read - Can view all event details
• Write - Can create and edit events
• Admin - Full control including calendar settings

Setting Permissions (TODO)

1. Open your calendar
2. Click Settings → Permissions
3. Add member roles and assign permission levels
4. Click Save

Viewing Calendars

Calendar Views

Switch between different views using the view buttons:

• Day - Hourly breakdown of a single day
• Week - 7-day view with time slots
• Month - Traditional monthly calendar
• List - Chronological list of upcoming events

Filtering Events

• Click on an event to see full details
• Click availability blocks (green/red) to edit schedules
• Use the date navigation buttons to move forward/backward

Managing Appointments

Editing an Event

1. Click on the event in the calendar
2. Update the details
3. Click Update Event

Canceling an Event

1. Click on the event
2. Click Cancel Event
3. Optionally provide a cancellation reason
4. Click Confirm Cancellation

Canceled events remain in the calendar with a "Cancelled" status for record-keeping.

Calendar Feeds (iCal Subscriptions)

Subscribe to your Gravity Rail calendars in external calendar apps like Google Calendar, Apple Calendar, or Outlook:

Generating a Feed URL

1. Open your calendar
2. Click Settings (gear icon)
3. Scroll to iCal Feed Subscription
4. Click Generate Feed Token
5. Copy the feed URL

Subscribing in Google Calendar

1. Copy your feed URL from Gravity Rail
2. Open Google Calendar
3. Click + next to "Other calendars"
4. Select From URL
5. Paste the feed URL
6. Click Add calendar

Your Gravity Rail appointments will now appear in Google Calendar and update automatically.

Subscribing in Apple Calendar

1. Copy your feed URL from Gravity Rail
2. Open the Calendar app
3. Go to File → New Calendar Subscription
4. Paste the feed URL
5. Click Subscribe
6. Choose update frequency and location
7. Click OK

Subscribing in Microsoft Outlook

1. Copy your feed URL from Gravity Rail
2. Open Outlook Calendar
3. Click Add Calendar → From Internet
4. Paste the feed URL
5. Click OK

Security Note

⚠️ Protect your feed URL - Anyone with the URL can view your calendar. If the URL is compromised:

1. Open calendar settings
2. Click Regenerate Token
3. Update the subscription in your calendar app with the new URL

To completely disable feed access, click Revoke Token.

Common Use Cases

Healthcare Practice

Setup:

• Calendar: "Dr. Smith's Schedule"
• Availability: Mon-Fri, 9am-5pm (except 12pm-1pm lunch)
• Event Types:
  • Initial Consultation (60 min)
  • Follow-up Visit (30 min)
  • Lab Results Review (15 min)
• Workflow: "Appointment Scheduler" with Write permission

Result: Patients can schedule appointments through SMS/chat, AI finds available slots, books appointments, and sends reminders.

Hair Salon

Setup:

• Calendars: One per stylist
• Availability: Tue-Sat, 10am-7pm
• Event Types:
  • Haircut (45 min)
  • Color (90 min, 30 min buffer)
  • Styling (30 min)
• Public booking page (TODO)

Result: Customers can book online, choose their stylist, and receive confirmation texts.

Office Hours

Setup:

• Calendar: "Manager Office Hours"
• Availability: Thursday, 2pm-5pm (weekly)
• Event Type: One-on-One (30 min slots)
• Permissions: Employees can book

Result: Team members can book time with their manager, no double-booking, automatic Zoom links.

Tips

Availability Schedules

• Create recurring schedules for regular hours
• Use unavailable blocks for holidays, vacations, or breaks
• Set priority levels when schedules overlap (higher number = higher priority)

Event Types

• Add buffer time to prevent back-to-back appointments
• Set realistic durations based on actual appointment length
• Use clear, descriptive names

AI Integration

• Start with Free/Busy permission to test
• Use specific event types to prevent wrong bookings
• Include clear booking instructions in your task prompt
• Always verify bookings with the customer before confirming

Calendar Organization

• Use colors to differentiate calendars
• Descriptive names help users choose the right calendar
• Keep event type names simple and clear

Troubleshooting

"No available slots found"

• Check that availability schedules are configured
• Verify schedules aren't marked as "Unavailable"
• Ensure the date range includes future dates
• Check that event type is allowed on the calendar

"AI cannot book appointments"

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

"Calendar feed not updating"

• External calendar apps typically update every 15-60 minutes
• Try manually refreshing the subscription
• Verify feed token hasn't been revoked

"Booking conflicts"

• Check for overlapping events
• Verify availability schedules aren't conflicting
• Ensure buffer times aren't causing issues

Related

• Workflows — Connect calendars to AI-powered booking workflows
• Abilities — Configure calendar booking as an AI ability
• Phone & Voice — Let callers book appointments by phone
• Actions — Automate notifications when appointments are booked