Book Appointment Cal function returns error

Support Help
1

Hi there, need some help.
I’m struggling with a Book Appointment Cal function in a Conversional Flow local component:

I’ve been trying different setups, including variables and prompts to explain, but the function fails to send a correct payload and returns an error. The check_availability_cal function works correctly with the same credentials, the phone number is available, and in the e.164 format - so I guess the issue is somewhere in the setup. Has anyone met and resolved such an issue before?

retell3
retell3703×449 43.3 KB

Cheers,
Roman

2

Based on the available sources, here are some troubleshooting steps for your Cal.com Book Appointment function issue:

Common Setup Issues

When setting up Cal.com’s preset tools in Retell AI, ensure you’ve configured both functions correctly(1):

  1. Check Availability - Retrieves open time slots(1)
  2. Book Appointments - Books appointment in a specific slot(1)

Configuration Requirements

Make sure you’ve properly set up the Cal.com integration(2):

  • Enter the necessary Cal.com credentials and event ID(2)
  • Configure the correct time zone settings on both the Cal.com platform and the Retell AI dashboard(2)

Conversation Flow Structure

Based on a similar issue reported in the community, the problem often relates to how the conversation flow is structured(3). A key insight from resolving a similar case:

  • After the check_availability_cal function executes, you need a conversation node to process and communicate the function result(3)
  • The agent needs to explicitly tell the user the available times before proceeding to book(3)
  • Only after the user confirms a specific time should the flow transition to the book_appointment function(3)

Recommended Flow Structure

The conversation flow should follow this pattern(3):

  1. Execute check_availability_cal function
  2. Add a conversation node after the function to verbalize available times to the user
  3. Wait for user confirmation of a specific time
  4. Only then trigger the book_appointment function with the confirmed time

Component-Specific Considerations

Since you’re using a local component, note that(4):

  • Tools need to be defined within the component and will not be visible outside at agent level(4)
  • Make sure the Begin node is properly linked(4)
  • Ensure the Exit node is properly connected so the flow doesn’t get stuck inside the component(4)

Testing

To properly test the component(4):

  • The component needs to be added to the main Conversation Flow to be initialized properly(4)
  • The global prompt of the main Conversation Flow will be applied to all component nodes implicitly(4)

If these steps don’t resolve your issue, I’d recommend checking your conversation flow structure to ensure there’s a conversation node between checking availability and booking the appointment.

3

This is the component itself, as the forum allows only one media at a time:

retell1
retell1910×203 23.1 KB

4

Looking at your component structure, I can see a potential issue based on similar problems reported in the community.

The Core Problem

From the error pattern you’re experiencing, this appears to match a known issue where the book_appointment function fails to receive the necessary date/time arguments(1). The error typically looks like:

Arguments: {}
error: Error calling Cal Book Appointment API: Date time reference does not exist, ask user to explicitly say a date time.

(1)

Your Component Flow Issue

Based on your component screenshot, I notice you’re going directly from the check availability function to the book appointment function. This is likely causing the problem(2).

The Solution

According to a resolved case in the community, you need to add a conversation node between the two functions(2). Here’s why:

  1. After check_availability_cal executes, the agent needs a conversation node to process and verbalize the function result to the user(2)
  2. The agent must explicitly tell the user the available times found in the result(2)
  3. Only after the user confirms a specific time slot should the flow proceed to book_appointment(2)

Recommended Fix

Restructure your component flow like this(2):

  1. Check Availability Node → Execute check_availability_cal
  2. NEW: Conversation Node → Prompt the agent to tell the user all available times from the function result
  3. User Confirmation → Wait for user to select a specific time
  4. Book Appointment Node → Execute book_appointment with confirmed time

Prompt Suggestion for the Conversation Node

In the new conversation node between your functions, add a prompt like(2):

“Tell the user all the available times found in the check_availability_cal function result. Wait for them to confirm which specific time they want before proceeding.”

Additional Consideration

The community has reported that this issue can be intermittent - “sometimes it works and another it doesn’t”(1). Adding the conversation node creates a more reliable flow by ensuring the date/time context is properly established before the booking attempt.

Try adding that conversation node between your two function nodes and let me know if that resolves the payload issue.

**

5

And the function setup:

retell2
retell2520×663 38.9 KB

6

Looking at your function setup, I can see you have the Cal.com API Key and Event Type ID configured. Here are the key setup requirements from the documentation:

Required Cal.com Credentials(1)

To properly configure the Book Appointment function, you need(1):

  1. Event Type ID - The number from your Cal.com event type URL (e.g., if the URL is https://app.cal.com/your-username/event-type/1427703, then 1427703 is your event type ID)(1)
  2. API Key - Retrieved from Settings → Developer → API Keys in your Cal.com dashboard(1)
  3. Timezone (optional) - Can be added to the function configuration(1)

Tool Description Best Practice(1)

The documentation recommends explicitly including in your tool description when to invoke the function(1). For example:

When user selected a slot, please book the appointment by calling the `book_appointment` function.

(1)

Critical Setup Step(2)

From the step-by-step guide, after adding the function, you must(2):

  1. Enter the Tool name (must be unique within that agent)(2)
  2. Add the API Key from Cal.com(2)
  3. Add the Event Type ID(2)
  4. Add the Tool description(2)
  5. Optionally add a timezone(2)
  6. Click “Save” to complete the setup(2)

Timezone Configuration(3)

Retell AI ensures all bookings are time zone-aware(3). You need to configure the time zone settings in both the Cal.com account and the Retell AI dashboard for accurate scheduling(3).

Common Issue

Based on your screenshot, I notice your tool description is quite brief. The documentation emphasizes updating the prompt to explicitly state when the function should be called(1). Try adding more specific guidance about when to invoke the booking function, particularly after the user has confirmed a specific time slot.

If the check_availability_cal function works correctly with the same credentials, the issue is likely in how the conversation flow is structured or how the booking function is being triggered, rather than the credentials themselves.

7

Hello @Roman_Ongo
To fix this go to your cal.com event → advanced and make the event book with the email instead of the phone number

image
image1902×488 23.1 KB

8

To configure Cal.com booking with email instead of phone number for your Retell AI agent, you’ll need to adjust the booking questions in Cal.com’s advanced settings(1).

In Cal.com, navigate to your event type’s advanced page where you can set up booking questions(1). The system allows you to add custom fields like phone number or email as input fields on the booking page(1).

When setting up the Retell AI integration, you’ll configure the book_appointment_cal tool with your Cal.com credentials(2):

{
  "type": "book_appointment_cal",
  "name": "book_appointment",
  "description": "Book an annual check up.",
  "cal_api_key": "cal_live_xxxxxxxxxxxx",
  "event_type_id": 60444,
  "timezone": "America/Los_Angeles"
}

(2)

To ensure your agent collects the correct information, update your prompt to explicitly instruct when to invoke the booking function(3):

When user selected a slot, please book the appointment by calling the `book_appointment` function.

(3)

The agent can collect name, email address, and phone number before booking the appointment(1).

9

It works, thank you @Omar_Ashraf :folded_hands: