VoiceAgent Tools: Cal.com - CloudTalk Help Center

This example demonstrates how to set up two tools that work together to handle appointment scheduling through Cal.com. One tool is used to fetch available time slots, and the other is used to book a selected time once the customer confirms.

User level: Admin

Before you start

Before you start, make sure you have:

active account in Cal.com and admin access to it
active AI Receptionist or AI Specialist subscription on your account

Tool 1: Fetching Available Time Slots

Section	Field	Value	Description
General	Tool Name	`get_free_slots`	Describes what the tool does.
	Description	When the customer asks for available slots, use this tool to get the list. The response will include dates and times in UTC.	Helps LLM decide when to call this tool.
	Awaiting Response Message	Let me check the availability. One moment please.	Message played while the tool request is being processed.
Request Definition	Method	`GET`	Request method.
	URL	`https://api.cal.com/v2/slots?username=#{{userName}}&eventTypeSlug=#{{eventType}}&start=#{{startDate}}&end=#{{endDate}}`	Endpoint URL with parameters.
Headers	cal-api-version	`2024-09-04`	Required by Cal.com.
	Authorization	`Bearer cal_live_76*REDACTED*17`	Replace with your Cal.com API key.
Path Parameters	username	Constant: `elise-marshall`	Your Cal.com username. Can be found in your profile.
	eventType	Constant: `30min`	Slug from the event’s detail page in Cal.com. Use LLM Prompt if multiple types are available.
	startDate	Parameter: `startDate`	Define the start of the search window. Should be passed as a System Prompt variable.
	endDate	Parameter: `endDate`	Define the end of the search window. Also passed via System Prompt variable.

Tool 2: Booking the Appointment

Section	Field	Value	Description
General	Tool Name	`book_meeting`	Descriptive tool name.
	Description	This tool books a meeting in the calendar after the customer chooses a time.	Helps the LLM understand when to use the tool.
	Awaiting Response Message	I’m scheduling the meeting now. Please wait.	Message played while booking is in progress.
Request Definition	Method	`POST`	Request method.
	URL	`https://api.cal.com/v2/bookings`	Endpoint for booking a meeting.
Headers	cal-api-version	`2024-08-13`	As required by Cal.com.
	Authorization	`Bearer cal_live_76*REDACTED*17`	Replace with your API key from Cal.com API settings.
Body Parameters	username	Constant: `elise-marshall`	Your Cal.com username.
	eventTypeSlug	Constant: `30min`	Type of event being scheduled.
	start	LLM Prompt: The start time of the booking in ISO 8601 format in UTC timezone, e.g. `2024-08-13T09:00:00Z`.	Extracted from the conversation.
	attendee.name	Parameter: `name`	Passed via System Prompt.
	attendee.email	LLM Prompt: Email of the customer booking the meeting.	Extracted dynamically.
	attendee.timezone	Constant or LLM Prompt	Set based on your workflow.

Need help or have a question? Just reach out through our Support portal — we’re here for you.