How booking works
A Finn books appointments during a call through Cal.com. Two built-in tools do the work:
| Tool | What it does |
|---|---|
| Check Calendar | Reads open slots on a Cal.com event type, starting from the date the caller asks for. |
| Book Calendar | Books the slot the caller chose on that event type. |
Both tools are attached to a Conversation step in the workflow editor. A Finn without a workflow has no calendar tools. See tools-builtin.
Set up the tools
- In Cal.com, create an API key (Settings → Developer) and note the ID of the event type you want booked.
- In the workflow editor, select the Conversation step that handles scheduling and attach Check Calendar and Book Calendar.
- Fill in each tool:
| Field | Required | Notes |
|---|---|---|
| Cal.com API key | yes | For example cal_live_…. Finn sends it to Cal.com from its servers; the caller never hears or sees it. |
| Event type ID | yes | The Cal.com event type to read and book. |
| Timezone | no | An IANA name, for example Asia/Kolkata. Defaults to UTC. |
| Filler | no | What the Finn says while the tool runs, for example "Let me check what's available…" |
- In the step's instructions, tell the Finn to check availability first, offer a few slots, and collect the caller's name and email before booking.
The tools use the API key you enter on them. They do not use a Cal.com account connected under Settings → Integrations → Calendar.
What the tools send
Check Calendar asks Cal.com for slots on the event type from the requested date onwards and returns a window of open slots. The Finn offers the caller the earliest two or three, not the full list.
Book Calendar needs three values from the conversation:
| Value | Source |
|---|---|
| Slot start | The slot the caller picked, as an ISO 8601 time. |
| Attendee name | Asked from the caller. |
| Attendee email | Asked from the caller. |
Finn adds the caller's phone number to the booking: the dialed number on outbound calls, the caller's number on inbound calls.
If the Finn can't get an email, the booking can't be made. Make collecting it part of the step.
Calendar accounts in Settings
Settings → Integrations → Calendar lets you connect:
| Card | How it connects |
|---|---|
| Google Calendar | OAuth. Add another connects more Google accounts. |
| Cal.com (OAuth) | OAuth through Cal.com. |
| Cal.com (API key) | Use API key, then paste a key from Cal.com → Settings → Developer. |
Connected accounts are listed with their email and a Disconnect button. In-call booking still needs the key and event type ID on the tools, as above.
Recording bookings
Neither tool writes a result into Finn's call data on its own. To track bookings, add a post-call analysis field such as appointment_booked and read it from the call.completed webhook or the call record. See analysis-fields and webhook-post-call. Cal.com is the source of truth for the booking itself.
What goes wrong
| Symptom | Cause |
|---|---|
| The Finn talks about times but never books | The tools aren't attached to the step, or the API key or event type ID is missing. |
| No slots are offered | Wrong event type ID, or the event type has no availability in the window checked. |
| Slots are offered at the wrong hour | The tool's timezone doesn't match the event type or the caller. Set Timezone. |
| Booking fails after the caller picks a slot | The Finn didn't collect an email. |
Test with Test → Phone call and confirm the booking appears in Cal.com before you deploy. See agents-testing.