Module Detail

The Fetch Free Slots module lets your agent pull a list of open appointment times from a GoHighLevel calendar before booking anything. Use it alongside the Book Appointment tool to give prospects a choice of slots rather than guessing.

Setup

1. Add and Configure the Module

Open Modules → Fetch Free Slots → Add
Calendar ID: Paste the ID from GoHighLevel
- In GHL: Settings → Calendars
- Open the calendar
- Copy the ID from the URL
- Paste into module configuration
Click Save

The module is now ready for any agent.

2. Attach to Agent as Tool

Edit the agent
Click Add Tool → Module → Fetch Free Slots
Leave async OFF (agent needs the response)
Save

Variables the Agent Can Send

start_date (Required)

ISO 8601 date that begins the search window Format: YYYY-MM-DD
Example: 2025-01-15

end_date (Optional)

ISO 8601 date that ends the window Format: YYYY-MM-DD
Example: 2025-01-20 Note: Omit this to fetch only the start_date

timezone (Optional)

IANA zone such as America/New_York Default: Uses agent’s default timezone if omitted Examples:

America/New_York
America/Los_Angeles
Europe/London
Australia/Sydney

Prompt Template

If the user wants to **see what's free** on a specific date or date-range, 
call `fetch_free_slots` with:

{
  "start_date": "<YYYY-MM-DD>",
  "end_date":   "<YYYY-MM-DD>",  // optional – omit for single day
  "timezone":   "<IANA TZ>"
}

Present the returned times and help them choose.

Conversation Examples

Example 1: Single Day

User: “Have you got anything tomorrow afternoon?” Agent: Runs fetch_free_slots with start_date = 2025-01-16, no end_date, and timezone = America/New_York Agent: “Tomorrow I’m free at 14:00, 14:30, 15:00, 15:30, 16:00, and 16:30. Which works best?” User: “Let’s go 3 pm.” Agent: Calls Book Appointment with that slot and confirms

Example 2: Multiple Days

User: “What do you have available this week?” Agent: Runs fetch_free_slots with start_date = 2025-01-15, end_date = 2025-01-19 Agent: “I have openings on:

Monday: 10am, 2pm, 4pm
Tuesday: 9am, 1pm, 3pm
Wednesday: 11am, 2pm
Thursday: 10am, 4pm
Friday: 9am, 1pm

What works for you?” User: “Wednesday at 2pm” Agent: Books appointment

Example 3: Next Available

User: “When’s your next available slot?” Agent: Runs fetch_free_slots for today and tomorrow Agent: “My next available is today at 4:30pm, or tomorrow at 9am. Either of those work?” User: “Tomorrow at 9” Agent: Books appointment

Best Practices

Always Fetch Before Booking

Don’t offer times without checking first. This avoids the agent suggesting slots that are already taken.

## Booking Process

Ask: "What day works best for you?"
Run fetch_free_slots for that day
Present 3-5 available times
Once they choose, run Book Appointment
Confirm the booking details

Single-Day Queries

If you only ever offer single-day choices, skip end_date:

{
  "start_date": "2025-01-15",
  "timezone": "America/New_York"
}

Keep Response Short and Readable

Line up times with commas or bullet points for clarity: Good:

"I have 10am, 2pm, and 4pm available. Which works?"

Better:

"I have:
• 10:00 AM
• 2:00 PM  
• 4:00 PM
Which suits you best?"

Handle No Availability

If fetch_free_slots returns no available times:
"I don't have any openings on [DATE]. Would [NEXT_DATE] work instead?"

[Fetch slots for next day]

Response Format

The module returns an array of available time slots:

{
  "slots": [
    {
      "start_time": "2025-01-15T14:00:00Z",
      "end_time": "2025-01-15T14:30:00Z"
    },
    {
      "start_time": "2025-01-15T15:00:00Z",
      "end_time": "2025-01-15T15:30:00Z"
    }
  ]
}

Parse this to present friendly times to the user.

Common Use Cases

1. General Appointment Booking

User: "I'd like to schedule a consultation"
Agent: "Great! What day works for you?"
User: "Next Tuesday"
Agent: [fetches slots for Tuesday]
       "I have 10am, 1pm, and 3pm available. Which is best?"

2. Rescheduling

User: "I need to move my appointment"
Agent: [gets existing appointment with Get Booked Appointments]
       "No problem! What day would work better?"
User: "Friday"
Agent: [fetches Friday slots]
       "Friday I have 9am, 11am, and 2pm open. Preference?"

3. Next Available Slot

User: "Get me in ASAP"
Agent: [fetches today + tomorrow]
       "Earliest I can do is today at 4pm or tomorrow at 9am. 
        Which works?"

4. Date Range Browsing

User: "Show me what you have next week"
Agent: [fetches Mon-Fri next week]
       "Next week I have:
        Monday: 10am, 2pm
        Wednesday: 11am, 3pm
        Friday: 9am, 1pm
        
        Any of those work for you?"

Advanced: Dynamic Scheduling

Buffer for Prep Time

If you need 2-hour notice for appointments:

Before calling fetch_free_slots, get the current time.

Set start_date to:
- If requesting same day: 2 hours from now
- If requesting future day: Start of business hours

This ensures you don't offer slots you can't actually fulfill.

Business Hours Only

Configure in GoHighLevel calendar settings:

Working hours
Buffers between appointments
Blackout dates

Fetch Free Slots automatically respects these settings.

Multiple Service Types

If you offer different service durations:

Ask: "Are you looking for a 30-min or 60-min session?"

[Fetch from appropriate calendar]
- 30-min calendar: Standard consultations
- 60-min calendar: Deep dives

Troubleshooting

No Slots Returned

Calendar might be full - check GHL calendar directly
Date range in the past - verify start_date is future
Outside working hours - check calendar business hours
Wrong calendar ID - verify ID is correct

Wrong Timezone

Specify timezone explicitly in the request
Don’t rely on default - always pass timezone for accuracy
Use IANA format: “America/New_York” not “EST”

Too Many Slots

Narrow the date range - single day instead of week
Filter in prompt: “Show only morning slots” or “Only afternoons”

Slots Don’t Match Manual Check

Cache lag - GHL updates may take 30-60 seconds
Different calendar - verify you’re checking same calendar
Timezone mismatch - slots shown in different timezone

Performance Tips

Cache Results

For chatbots, store fetched slots for 5-10 minutes to avoid redundant API calls:

If user says "actually, can you show me those times again?",
reshow the previously fetched slots instead of calling the API again.

Limit Range

Don’t fetch more than 7 days at once unless necessary:

Faster API response
Easier for user to digest
Reduces token usage in agent response

Next Steps

Use with Book Appointment to complete the booking
Combine with Get Booked Appointments to show existing bookings
Set up Cancel or Reschedule for flexibility

With the Fetch Free Slots module in place, your agents can check availability in real-time, making bookings smoother and keeping prospects in control.

Platform Overview

Prompt Engineering

Chat Agent Examples

Voice Agent Examples

GoHighLevel Integration

Telephony Setup

Module Library

​Module Detail

​Setup

​1. Add and Configure the Module

​2. Attach to Agent as Tool

​Variables the Agent Can Send

​start_date (Required)

​end_date (Optional)

​timezone (Optional)

​Prompt Template

​Conversation Examples

​Example 1: Single Day

​Example 2: Multiple Days

​Example 3: Next Available

​Best Practices

​Always Fetch Before Booking

​Single-Day Queries

​Keep Response Short and Readable

​Handle No Availability

​Response Format

​Common Use Cases

​1. General Appointment Booking

​2. Rescheduling

​3. Next Available Slot

​4. Date Range Browsing

​Advanced: Dynamic Scheduling

​Buffer for Prep Time

​Business Hours Only

​Multiple Service Types

​Troubleshooting

​No Slots Returned

​Wrong Timezone

​Too Many Slots

​Slots Don’t Match Manual Check

​Performance Tips

​Cache Results

​Limit Range

​Next Steps