> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildassistants.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar Booking Debugging Guide

## Background & Purpose

This SOP is designed to assist in troubleshooting issues related to conversational calendar booking for client-facing interactions. Following the outlined **CASPER triage process** ensures efficient problem identification and resolution, enabling the booking bot to perform as intended and provide reliable support for AI deployment.

## Required Resources

* **Access to conversational booking tool** (e.g., GoHighLevel)
* **Logs for tool activity** (availability checks and booking actions)
* **Client's calendar settings** and availability link
* **Access to assistant configuration** (e.g., prompts, calendar connections)

## The CASPER Methodology

Use this systematic triage order: **C-A-S-P-E-R**

### C - Calendar Access

### A - Ability (Tools)

### S - Settings

### P - Prompt

### E - Event Tool Calls

### R - Refresh Connection

***

## 1. Calendar Access (C)

### Objective

Ensure the assistant has access to the specific calendar and verify correct integration.

### Verification Steps

#### Check Calendar Integration

1. **Navigate to Assistant Settings**
2. **Go to the Calendars tab**
3. **Verify calendar is listed and connected**

#### Add Calendar if Missing

1. **Click "Add Calendars"** to open the calendar menu
2. **Sync your calendars with GoHighLevel**
3. **Click "Add to Assistant"** to begin verification process

#### Verification Process

* **The verification process runs a simulation** for booking
* **Calendar only verifies if simulation is successful**
* **Look for green checkmark** in upper right corner after verification
* **Click "Add to Assistant"** to complete the process

### Success Criteria

✅ Calendar appears in assistant's calendar list
✅ Green checkmark indicates successful verification
✅ Calendar is actively connected to assistant

### Troubleshooting

**Calendar not appearing:**

* Check GoHighLevel calendar permissions
* Verify calendar is properly configured in GoHighLevel
* Ensure OAuth connection is active

**Verification failing:**

* Review calendar availability settings
* Check for booking conflicts or restrictions
* Verify calendar has available time slots

## 2. Ability (A)

### Objective

Confirm the assistant has access to essential tool calls for calendar management.

### Required Tools for Booking

* **Check Availability** - Retrieves available time slots
* **Book Appointment** - Creates appointments on calendar

### Verification Steps

#### Check Existing Tools

1. **Navigate to Tools & Abilities** in assistant settings
2. **Verify presence of calendar management tools**
3. **Confirm "Check Availability" and "Book Appointment" are enabled**

#### Add Missing Tools

1. **Click "Add Function"** if tools are missing
2. **Select from pre-built tools** (should be first two options)
3. **Enable required calendar tools**

### Additional Useful Tools

* **Reschedule Appointments** - Modify existing bookings
* **Cancel Appointments** - Remove scheduled appointments
* **Check Contact's Current Appointments** - View existing bookings

### Success Criteria

✅ "Check Availability" tool is enabled
✅ "Book Appointment" tool is enabled
✅ Tools appear in assistant's function list

### Troubleshooting

**Tools not working:**

* Verify tool permissions are correctly set
* Check tool configuration parameters
* Test tools with simple booking scenarios

## 3. Settings (S)

### Objective

Verify calendar settings to ensure booking works as expected and availability is correctly configured.

### Calendar Settings Verification

#### Access Calendar Settings

1. **Navigate to Calendars** in GoHighLevel
2. **Go to Calendar Settings**
3. **View all configured calendars**

#### Check Objective Availability

1. **Click the 3 dots** on your calendar
2. **Click "Share"** to open popup
3. **Copy the permanent calendar link**
4. **Paste link in new tab** to view public availability

### Common Settings Issues

#### Third-Party Calendar Integration

**Problem:** Google or other calendar integration blocking availability
**Solution:**

* Review third-party calendar settings
* Check for personal calendar conflicts
* Adjust integration settings to allow availability

#### General Calendar Settings

**Potential Conflicts:**

* **"Look Busy" settings** limiting availability
* **Date range restrictions** blocking certain periods
* **Buffer time conflicts** consuming available slots
* **Working hours** not properly configured

### Settings Audit Checklist

* ✅ **Working hours** align with intended availability
* ✅ **Buffer times** are appropriate
* ✅ **Third-party integrations** don't block availability
* ✅ **Date restrictions** are properly configured
* ✅ **Public availability** matches expectations

### Troubleshooting

**Availability doesn't match expectations:**

* Review all calendar integrations
* Check working hours and time zones
* Verify buffer and break settings
* Audit any special restrictions or rules

## 4. Prompt (P)

### Objective

Ensure prompts are concise and focused solely on booking tasks without confusion.

### The Simplicity Principle

> **Key Insight:** You can create a perfectly functional booking assistant with a simple prompt: "You are an appointment booking bot"

### Common Prompt Problems

#### Information Overload

**Problem:** Using prompt as a place to dump context and information
**Issues:**

* Confuses the AI about primary objectives
* Creates conflicting instructions
* Interferes with booking functionality

**Solution:** Use appropriate tools for different content types:

#### Proper Content Distribution

**Prompt Should Contain:**

* **Personality/Identity** - Who the assistant is
* **Response Guidelines** - How to communicate
* **Style Guardrails** - Tone and approach
* **Important Points** - Key behavioral notes
* **Instruction Set** - What to do and when

**Knowledge Base Should Contain:**

* **Domain Knowledge** - Industry-specific information
* **Business Information** - Company details
* **FAQs** - Frequently asked questions
* **Objection Handling** - Response strategies
* **Pricing Information** - Simple pricing details
* **Key-Value Trained Output** - Structured responses

**Tools Should Handle:**

* **Context Injection** - Conditional instructions
* **Data Retrieval** - Getting information
* **Data Processing** - Performing actions
* **Parameter Scaling** - Dynamic functionality

### Prompt Best Practices

#### Structure Guidelines

* **Be concise and direct**
* **Use clear, simple language**
* **Avoid complex scenario handling**
* **Remove unnecessary markdown** (only use ## headers)
* **Focus on core booking functionality**

#### Example Effective Booking Instruction

```
6. Get your availability and use that to book an appointment with the user
```

### Success Criteria

✅ Prompt is concise and focused
✅ Booking instructions are clear and simple
✅ No conflicting or confusing directives
✅ Business information moved to knowledge base

### Troubleshooting

**AI not following booking protocol:**

* Simplify prompt language
* Remove conflicting instructions
* Separate business info into knowledge base
* Test with minimal prompt first

## 5. Event Tool Calls (E)

### Objective

Confirm tools successfully execute for booking and availability checking.

### Log Analysis

#### Check Task Performed Events

1. **Review conversation logs**
2. **Look for "Task Performed" entries**
3. **Examine metadata for tool calls**

#### Availability Check Issues

**AI Giving Improper Times:**

* **Verify availability tool call** shows in logs
* **Check metadata** for retrieved time slots
* **Compare with actual GoHighLevel availability**
* **If discrepancy exists:** Review calendar settings (not OAuth issue)

**Common Prompt Conflicts:**

* **Conflicting booking instructions**
* **Unclear language** around appointment scheduling
* **Complex time handling** instructions

#### Booking Execution Issues

**AI Giving Correct Times but Not Booking:**

* **Check booking tool metadata** for GoHighLevel response
* **Review error codes** in tool call results

**Common Error Scenarios:**

* **Authorization Errors:** OAuth configuration issues
* **Bad Request:** Instruction injection or timezone conflicts
* **Permission Denied:** Insufficient OAuth permissions

### Tool Call Verification

#### Successful Tool Calls Should Show:

* **Timestamps** for when tools were executed
* **Calendar details** in metadata
* **Response metadata** (e.g., "appointment booked")
* **No error codes** like "unauthorized" or "bad request"

### Success Criteria

✅ Availability checks show correct time slots
✅ Booking attempts execute successfully
✅ Tool metadata shows proper responses
✅ No authorization or permission errors

### Troubleshooting

**Tool calls failing:**

* Check OAuth connection status
* Verify tool permissions
* Review instruction clarity
* Test with simple booking scenarios

## 6. Refresh Connection (R)

### Objective

If all settings and tools appear correctly configured but issues persist, refresh all connections.

### Comprehensive Refresh Process

#### OAuth Connection Reset

1. **Disconnect OAuth** from GoHighLevel
2. **Clear any cached connections**
3. **Reconnect with fresh authentication**
4. **Verify all permissions** are granted

#### Tool Refresh

1. **Remove calendar tools** from assistant
2. **Re-add tools** with fresh configuration
3. **Test each tool** individually
4. **Verify tool permissions**

#### Calendar Resync

1. **Delete calendar** from assistant
2. **Resync calendar** with GoHighLevel
3. **Complete verification process** again
4. **Test booking functionality**

#### Prompt Reset

1. **Simplify prompt** to basics
2. **Remove unnecessary information**
3. **Build complexity gradually**
4. **Test after each modification**

### Testing After Refresh

1. **Run simple availability check**
2. **Attempt test booking**
3. **Verify booking appears in calendar**
4. **Test with multiple time slots**

### Success Criteria

✅ Fresh OAuth connection established
✅ Tools responding correctly
✅ Calendar properly synced
✅ Test bookings work flawlessly

## Definition of Done

This debugging checklist is complete when:

* ✅ **Assistant accurately checks** for availability
* ✅ **Booking functionality** works reliably
* ✅ **Calendar times align** with intended availability
* ✅ **Prompts are clean** and focused
* ✅ **Tool call logs** show successful operations
* ✅ **No error responses** in system logs

## Additional Troubleshooting

### Common Error Messages

#### "Unauthorized" Error

**Cause:** OAuth connection issues
**Solution:**

* Refresh OAuth connection
* Verify all permissions granted
* Check GoHighLevel account access

#### "Bad Request" Error

**Cause:** Instruction injection or data formatting issues
**Solution:**

* Simplify booking instructions
* Let AI handle timezone conversions naturally
* Remove conflicting prompt directives

#### Incorrect Availability Times

**Cause:** Calendar configuration issues
**Solution:**

* Check GoHighLevel calendar settings
* Review third-party calendar integrations
* Verify working hours and restrictions

### Quick Reference CASPER Checklist

#### C - Calendar Access

* [ ] Calendar connected to assistant
* [ ] Verification successful (green checkmark)
* [ ] Calendar appears in assistant settings

#### A - Ability (Tools)

* [ ] "Check Availability" tool enabled
* [ ] "Book Appointment" tool enabled
* [ ] Tools configured with proper permissions

#### S - Settings

* [ ] Calendar availability matches expectations
* [ ] Third-party integrations working correctly
* [ ] Working hours and restrictions properly set

#### P - Prompt

* [ ] Prompt is concise and focused
* [ ] No conflicting instructions
* [ ] Business info moved to knowledge base

#### E - Event Tool Calls

* [ ] Availability checks working in logs
* [ ] Booking tool calls successful
* [ ] No error codes in metadata

#### R - Refresh

* [ ] OAuth connection refreshed if needed
* [ ] Tools removed and re-added
* [ ] Calendar resynced if necessary

## Best Practices

### Prompt Engineering

* **Start simple** with basic booking instructions
* **Add complexity gradually** only when needed
* **Test each change** thoroughly
* **Keep business information** in knowledge base

### System Maintenance

* **Regular OAuth checks** to ensure connection health
* **Periodic calendar setting audits**
* **Monitor tool call success rates**
* **Keep prompts clean and focused**

### Testing Strategy

* **Test with real scenarios** regularly
* **Use multiple time slots** for testing
* **Verify bookings** appear correctly in calendar
* **Check from user perspective** using public calendar link

This comprehensive debugging guide ensures reliable calendar booking functionality through systematic troubleshooting and best practices implementation.