Can't add function Book Appointment with Cal.com

Support Help
1

Hi everyone,

I am building an inbound cales agent. I am able to add the function ‘check_availability’ from cal.com with the API key and eventid but can’t do it for the ‘book_appointment’ function. The requirements for both are exactly the same, the API key and event id. But for some reason ‘book_appointment’ doesn’t work. It throws off an error saying:

Error validating cal.com tools.

I could maybe do it via a custom POST function to cal but it is strange that ‘check’ is working but not the ‘book’. I would like to get to the bottom of it, to avoid any calendar issues in the future.

Inbound Call Issue: number busy and registration failure with Messagenet trunk
2

Based on the available information, there are only a few things that are explicitly documented and they all assume that, if configured correctly, both tools should work the same way with Cal.com.(1)(2)

Here is what is clearly documented and what you can double‑check:

  1. Both tools require the same Cal.com credentials
    For both “Check Calendar Availability” and “Book Calendar”, you must:

    • Create a Cal.com account.(1)(2)
    • Configure an Event Type in Cal.com.(1)(2)
    • Get the Event Type ID from the URL of that event type (e.g. https://app.cal.com/your-username/event-type/1427703 → 1427703).(1)(2)
    • Get the API Key from Cal.com under Settings → Developer → API Keys.(1)(2)

  2. Retell tool configuration fields for both integrations
    When adding the tools in Retell, both flows require you to fill in:

    • A unique Tool name within the agent.(1)(2)
    • The Cal.com API Key.(1)(2)
    • The Event Type ID.(1)(2)
    • A Tool description (e.g. “Book the appointment for 30-minute consultation calls” or “Checks availability for 30-minute consultation calls”).(1)(2)
    • Optional: timezone.(1)(2)

    The docs do not list any additional required fields that differ between the two tools; they show the same credential requirements for both.(1)(2)

  3. Known pitfall from community discussion: wrong Event Type ID
    There is a Discord thread where a “check availability” tool was failing with an error from the Cal Event Type API until the user corrected the Event Type ID taken from the Cal.com URL; once they used the correct ID, it worked.(3)

    • This shows that if the Event Type ID is wrong, Cal.com calls can fail even if the API key is valid.(3)

Given that, here are the concrete checks you can do for the book_appointment tool specifically, staying within what’s documented:

  • Confirm that the Event Type ID you’re using for book_appointment is exactly the numeric ID from the Cal.com event URL (and not e.g. a slug or a different event type than the one used for check_availability).(1)(2)(3)
  • Confirm that the API key you pasted for book_appointment is the same valid Cal.com API key that works for check_availability (no extra spaces, no different key, etc.).(1)(2)
  • Confirm that the tool name for book_appointment is unique within that agent (no duplicate tool names between tools).(1)

The documentation does not provide more detailed error semantics for “Error validating cal.com tools” nor any special extra requirement that applies only to book_appointment and not to check_availability, so I cannot say more precisely why your specific tool is failing based on the available sources.(1)(2)

If, after verifying API key, Event Type ID, and unique tool name, the book_appointment function still fails validation, the next step is to contact support or share your exact tool configuration with the Retell team so they can inspect it. You can reach them here:

If you’d like, I can also give you a more general (non‑docs‑based) explanation of common causes for this kind of mismatch between “check” and “book”; just say so.

3

Hello Codeflo
Can you share your agent id so I can take a look at
Thank you.