Skip to main content

​
Module Detail

When a client rings or messages asking “What time did I book again?”, the Get Booked Appointments module lets your agent pull every upcoming appointment linked to that contact.

​
What It Returns

  • Date and time (in the zone you specify or agent’s default)
  • Appointment ID (required for cancellation or rescheduling)
  • Calendar/service type
  • Duration
  • Location (if applicable)

​
One-Off Setup

​
1. Add the Module

  1. Go to Modules → Get Booked Appointments → Add
  2. No configuration needed
  3. Click Save

​
2. Attach to Agent

  1. Open your agent
  2. Press Add Tool → Module Library → Custom Modules → Get Booked Appointments
  3. Leave async off (agent must read the response)
  4. Save

​
Optional Variable

timezone: Supply an IANA zone (e.g., America/New_York) if you want the times formatted for the caller’s region Note: Omit it to use the agent’s default timezone

​
Prompt Snippet

If the caller asks when their existing appointment is, run 
get_booked_appointments with:
  timezone = the caller's timezone (ask for city if unknown)

Read the returned list and tell them the date and time.

If they wish to cancel or reschedule, pass the matching 
appointment_id to the appropriate tool.

​
Example Conversations

​
Example 1: Simple Lookup

Caller: “I booked something with you but can’t remember when.” Agent: Runs get_booked_appointments Agent: “I’ve found your booking: Tuesday, July 16 at 3:30pm. Would you like to keep that slot, move it, or cancel?” Caller: “That works, thanks!”

​
Example 2: Reschedule

Caller: “When’s my appointment again?” Agent: Runs module Agent: “You’re booked for Thursday, July 18 at 10am. Need to change it?” Caller: “Yeah, can we do Friday instead?” Agent: Uses the appointment_id from the response to run reschedule tool Agent: “All set! You’re now booked for Friday, July 19 at 10am.”

​
Example 3: Multiple Appointments

Caller: “What do I have scheduled with you?” Agent: Runs module Agent: “You have two upcoming appointments:
  1. Tuesday, July 16 at 2pm - Initial Consultation
  2. Monday, July 22 at 10am - Follow-up Session
Which one were you asking about?” Caller: “The first one - can we move it to Wednesday?” Agent: “Sure! What time works on Wednesday?”

​
Common Use Cases

​
1. Appointment Confirmation

User: "Can you confirm my booking?"
Agent: [runs get_booked_appointments]
       "Yes, you're confirmed for [DATE] at [TIME]. 
        All good, or need to change anything?"

​
2. Rescheduling Request

User: "I need to reschedule"
Agent: [runs get_booked_appointments]
       "You're currently booked for [DATE] at [TIME]. 
        What day would work better?"
User: "Next Thursday"
Agent: [uses appointment_id to reschedule]

​
3. Cancellation

User: "I need to cancel my appointment"
Agent: [runs get_booked_appointments]
       "I see you have [DATE] at [TIME]. Want to cancel 
        that one, or reschedule instead?"
User: "Just cancel it"
Agent: [uses appointment_id to cancel]
       "Done. Your appointment has been cancelled."

​
4. Pre-Appointment Reminder

System triggers call 24 hours before appointment

Agent: "Hi {{firstName}}, this is a reminder about your 
        appointment tomorrow at [TIME from get_booked_appointments]. 
        Are you still able to make it?"

User: "Yes"
Agent: "Great! See you then."

User: "Actually, no"
Agent: "No problem. Want to reschedule or cancel?"

​
Response Format

The module returns an array of appointment objects: 
{
  "appointments": [
    {
      "id": "appt_abc123",
      "calendar_name": "Initial Consultation",
      "start_time": "2025-01-16T14:00:00",
      "end_time": "2025-01-16T14:30:00",
      "timezone": "America/New_York",
      "status": "confirmed"
    }
  ]
}
Key fields:
  • id: Pass this to cancel or reschedule tools
  • start_time: Show to user in friendly format
  • calendar_name: Type of appointment
  • status: confirmed, cancelled, no-show, etc.

​
Best Practices

​
Store Appointment ID

After running get_booked_appointments, store the appointment_id in conversation memory for later use: 
[Runs get_booked_appointments]

Store appointment_id for later reference.

If user wants to cancel or reschedule, use the stored ID.

​
Handle Multiple Appointments

If get_booked_appointments returns multiple appointments:

1. List all appointments with numbers
2. Ask: "Which one are you asking about?"
3. Use the selected appointment_id for further actions

​
Timezone Handling

Always ask for or detect the user’s timezone: 
Before running get_booked_appointments, ask:
"What city are you in?" or "What timezone are you in?"

Use their answer to format times correctly.

​
No Appointments Found

If get_booked_appointments returns empty array:

"I don't see any upcoming appointments for you. 
Would you like to schedule one now?"

​
Integration with Other Modules

​
Complete Appointment Management Flow

## Managing Appointments

1. **Check existing**: Run get_booked_appointments
   
2. **If found**:
   - Show details
   - Ask: "Keep, reschedule, or cancel?"
   
3. **Keep**: Confirm and end
   
4. **Reschedule**: 
   - Run fetch_free_slots
   - Show available times
   - Run cancel_or_reschedule_appointment (reschedule action)
   
5. **Cancel**:
   - Run cancel_or_reschedule_appointment (cancel action)
   - Confirm cancellation

​
Reminder + Rescheduling Flow

[24 hours before appointment]

Agent: Calls customer
Agent: [runs get_booked_appointments]
       "Hi! Reminder: you have [SERVICE] tomorrow at [TIME]. 
        Still good?"

User: "Actually, I can't make it"

Agent: [runs fetch_free_slots for next week]
       "No worries! I have [TIMES] next week. Any of those work?"

User: "Wednesday at 2pm"

Agent: [runs cancel_or_reschedule_appointment with new time]
       "You're all set for Wednesday at 2pm instead!"

​
Troubleshooting

​
No Appointments Returned (but user insists they booked)

  • Wrong contact - verify you’re looking up correct phone/email
  • Different GHL location - check if booking is in different subaccount
  • Past appointment - module only returns future appointments
  • Cancelled previously - check appointment status in GHL

​
Wrong Timezone Displayed

  • Pass timezone explicitly in the request
  • Ask user for their timezone - don’t assume
  • Use IANA format: “America/New_York” not “EST”

​
Appointment ID Not Working for Cancel/Reschedule

  • Verify ID format - should be string from get_booked_appointments
  • Check appointment still exists - may have been cancelled elsewhere
  • Ensure permissions - verify agent has access to modify appointments

​
Advanced: Appointment History

While this module only returns upcoming appointments, you can track history by:
  1. Adding notes after each call
  2. Using custom fields in contact record
  3. Saving to external database via webhook
Example: 
After cancelling appointment:
  Run find_or_create_contact with:
    customField.last_cancelled_date = today's date
    customField.cancellation_reason = user's reason

​
Next Steps

With Get Booked Appointments in place, your agents can instantly answer “When’s my booking?” and smoothly move on to rescheduling or cancelling without hunting through the calendar manually.