Skip to main content
A Booking action connects the agent to one of your Cal.com event types. When someone wants to meet, the agent looks up real open times, offers them, and books the one they confirm — on a call, in chat or by email. It never invents a time or promises one it has not checked.

​
What you need

  • A Cal.com API key for the account that owns the event type.
  • The Cal.com event type ID — the number that identifies the event type you want booked, such as a 30-minute intro call.
  • The time zone your availability should be read in, as an IANA name like America/New_York or Europe/London.

​
Set it up

1

Open Actions

Go to Agents → your agent → Actions and choose Add action → Booking.
2

Enter the event type

Type the number into Cal.com event type ID. It must be a positive whole number.
3

Check the time zone

Time zone is filled in from your browser. Change it if your calendar runs in a different zone. If you leave it empty, UTC is used.
4

Add your API key

Under API key, choose a saved key, or choose Add a new key… and enter a label (for example “Cal.com”) and the secret. The key is encrypted when you save and never shown again.
5

Pick channels and save

Choose Voice, Chat and Email as needed, then click Add.
There is no tool name to choose. A booking action always gives the agent two tools, get_booking_slots and book_meeting, so each agent can have only one booking action. To change the event type or key later, edit the existing one.

​
How it works in a conversation

  1. Finding times. When someone wants to book, the agent asks Cal.com for open slots on your event type. By default it searches from today to a week out; if the person asks about specific dates, it searches that range instead. It gets up to 20 open slots back.
  2. Offering times. The agent only offers slots Cal.com returned, and says them in plain words rather than reading out timestamps. If there are no open slots in the range, it says so.
  3. Booking. Once the person picks a specific time and confirms it, the agent books it with their name and email — both are required, so it asks for them if it does not have them yet. Anything else they want you to know goes in as a note on the booking, up to 500 characters.
  4. If the slot is gone. If Cal.com rejects the booking — for example, someone else took the slot — the agent is told and offers another time from a fresh lookup.
The booking is made in your Cal.com account against the event type you chose. The attendee’s time zone is recorded as the time zone set on the action.

​
Limits

  • Timeout: each request to Cal.com gets 5 seconds on a phone call and 15 seconds on chat and email. If it takes longer, the agent offers to follow up instead.
  • One booking action per agent.
  • Up to 20 slots per lookup.

​
When something is wrong

  • No API key attached. A booking action without a key is not offered to the agent at all. This happens if you delete the key under API credentials — attach a new one by editing the action.
  • Cal.com returns an error. The agent is told it could not fetch the calendar, and the lookup shows as failed in the action log. A wrong event type ID or a revoked key usually shows up this way.
Each lookup and each booking appears in the Action log under Inbox → Extra fields, as get_booking_slots or book_meeting, with whether it succeeded and how long it took. That is the quickest way to check the setup works: book a test meeting in chat, then look there and in Cal.com.