Cancel & Reschedule Cal.com Appointments

​

What You’ll Learn

• Creating and configuring a custom mid-call tool with headers and parameters
• Building an automation flow that handles both cancellation and rescheduling via Cal.com API v2
• Understanding the difference between /test and /sync webhook endpoints
• Converting timezone-aware dates to UTC for the Cal.com API
• Writing AI prompt instructions so the assistant knows when and how to use the tool
• Testing the full flow end-to-end

​

Prerequisites

• Autocalls.ai platform access
• Cal.com account with API key (v2)
• AI assistant already created and configured
• Phone number assigned for inbound or outbound calls

​

Step 1: Create the Mid-Call Tool

1. Go to Mid Call Tools in the sidebar
2. Click New Mid Call Tool
3. Configure the basic settings:
   • Name: modify_booking — must contain only lowercase letters, numbers, and underscores
   • Description: Use this tool to cancel or reschedule a booking
   • Endpoint: We’ll fill this in after creating the automation (Step 5)
   • Timeout: 20 seconds
   • Method: POST

​

Step 2: Add Headers

1. Go to cal.com and click Go to App
2. Navigate to Settings → API Keys
3. Click Create new key, check Never expires, give it a name (e.g., “Reschedule/Cancel booking”)
4. Save and copy the key
5. Paste it as the value for the calApiKey header

​

Step 3: Configure Parameters

​

Step 4: Create the Automation Flow

1. Go to Automation Platform by clicking “Automate platform” in the sidebar
2. Click New Flow and select From Scratch
3. Search for Webhook and select Catch Webhook as your trigger
4. Copy the generated webhook URL
5. Click Test to start listening for incoming data

​

Step 5: Set the Tool Endpoint

1. Paste the webhook URL into the Endpoint field
2. Add /test at the end — e.g.: https://your-webhook-url.com/api/v1/webhooks/abc123.../test
3. Save the tool
4. Click Test Tool in the mid-call tool page — you should see the test data arrive in the automation platform

​

Step 6: Fetch the Customer’s Upcoming Bookings

1. Click + to add an action
2. Search for HTTP and select Send HTTP Request
3. Configure the request:

4. Add these headers:

5. Add these query parameters:

​

Step 7: Add Branch Logic — Cancel or Reschedule?

1. Click + and search for Branch
2. Set the first value: Select from Catch Webhook → Body → cancel_appt
3. Set the condition: Boolean is True

• True branch → Customer wants to cancel
• False branch → We check for reschedule next

4. On the False branch, add another Branch step
5. Set the first value: Select from Catch Webhook → Body → reschedule_appt
6. Set the condition: Boolean is True

​

Step 8: Build the Reschedule Branch (True side of second Branch)

​

8a: Format the Date to UTC

1. On the True path of the reschedule branch, click + and search for Format Date
2. Configure:
   • Input: Select from Catch Webhook → Body → startDateTime
   • From Format: ISO format
   • From Timezone: Your assistant’s timezone (e.g., Europe/Bucharest)
   • To Format: ISO format
   • To Timezone: UTC (GMT)
3. Test to verify the conversion works correctly

​

8b: Call the Reschedule API

1. Add an HTTP Request step after Format Date:

2. Add these headers:

3. Set Body type to JSON and enter:

{
  "start": "{{format_date_step.result}}",
  "reschedulingReason": "{{trigger.body.reschedule_reason}}"
}

​

8c: Return Response

1. Add a Return Response step (search for Webhook → Return Response)
2. Click on the body field, select dynamic value
3. Delete the {} and insert the full body from the reschedule HTTP request step

​

Step 9: Build the Cancel Branch (True side of first Branch)

1. On the True path of the first branch, add an HTTP Request step:

2. Add these headers:

3. Set Body type to JSON:

{
  "cancellationReason": "{{trigger.body.cancellationReason}}"
}

4. Add a Return Response step after the cancel request
5. Click on the body field, select dynamic value, delete the {}, and insert the full body from the cancel HTTP request step

​

Step 10: Publish and Switch to /sync

1. Verify all steps are correctly configured
2. Click Publish to make the flow live
3. Go back to your mid-call tool and change the endpoint from /test to /sync
4. Save the tool

​

Step 11: Attach the Tool to Your Assistant

1. Navigate to your AI assistant
2. Go to Prompts and Tools tab
3. In the Custom Tools section, attach the modify_booking tool
4. Save the assistant

​

Step 12: Configure the AI Prompt

If the customer wants to cancel or reschedule an appointment:
1. First ask for their email address
2. For reschedule: call the get_slots tool first to check available times, then call modify_booking with the chosen slot
3. For cancel: ask for cancellation reason, then call modify_booking
4. Always confirm the action with the customer before proceeding

​

Step 13: Test End-to-End

​

Using Test Assistant (Chat)

1. Click Test Assistant to open the chat test interface
2. Start a conversation and try booking an appointment first
3. Then ask to reschedule or cancel — the assistant should ask for your email, and proceed with the appropriate action

​

Using Speak to Assistant (Voice)

1. Click Speak to Assistant for a live voice test
2. Request a cancellation or reschedule during the conversation
3. Check the automation platform to verify the flow executed correctly and the correct branch was taken

​

Production Testing

​

Best Practices

​

Tool Configuration

• Use descriptive parameter descriptions — the AI relies on these to extract the right data from the conversation
• Set timeout to 20 seconds — the flow involves multiple API calls (get bookings + cancel/reschedule)
• Always use /sync in production — otherwise the AI won’t receive the response data

​

Prompt Design

• Request email early — the tool needs it for the Cal.com booking lookup
• For reschedule: use get_slots first — have the AI check available times before calling the reschedule tool
• Handle edge cases — what if the customer doesn’t know their email? What if no upcoming bookings are found? Add instructions for these scenarios

​

Security

• Pass API keys via headers — not in the request body or parameters
• Never expose keys in parameter descriptions or prompt instructions

​

Troubleshooting

​

Common Issues

• Make sure you’re using /sync not /test in production
• Verify the Return Response step is configured in your flow
• Check that the flow is published

• Review the tool description — it must clearly indicate when to use it
• Check that the tool is attached to the correct assistant
• Verify your prompt includes explicit instructions about when to call the tool

• Confirm your API key is valid and has the correct permissions
• Check the cal-api-version header matches (2024-08-13)
• Verify the booking UID exists and status is “upcoming”

• Make sure the Format Date step converts from your assistant’s timezone to UTC
• Verify the “From Timezone” matches your assistant’s configured timezone

• Ensure cancel_appt and reschedule_appt are True/False type parameters, not strings
• Check that Branch conditions use “Boolean is True” operator

​

Next Steps

• Send confirmation SMS — add a post-action SMS step using SMS automation
• Log actions to Google Sheets — track all cancellations and reschedules using Google Sheets sync
• Add email notifications — send confirmation emails with Post-Call Email Automation
• Handle multiple bookings — modify the flow to let the customer choose which booking to modify if they have more than one