This article explains how to connect Cal.com to your AI Employee. This integration enables your AI Employee to manage schedules and appointments. By connecting your Cal.com account, your agent can check availability, book new meetings, and cancel or reschedule existing appointments on behalf of users.
Prerequisites
A Cal.com account (free or paid).
Generate an API key in Cal.com following this official guide: API Reference.
Configure your Newo.ai project
Navigate to your customer’s Builder.
Go to the Projects page, click the three dots icon in the top-right and Create New Project.
Fill in the following fields and ensure Auto update enabled is turned on:
Idn:
calcomTitle:
calcomRegistry:
productionModule:
cal_com_integration
Click Create.
Click the three dots icon next to the newly created project.
Click Force Update Project.
Connect Cal.com to your Newo.ai account
Navigate to the Attributes page in the Builder.
Paste your Cal.com API key into the CalCom API Token (
calcom_api_token) attribute.Click Save and Publish All.
Refresh the page and confirm the
calcom_event_typeandcalcom_event_modeattributes appear on the Attributes page.For the
calcom_event_typeattribute, select the name of the meeting you set up in Cal.com.For the
calcom_event_modeattribute, select either Personal or Team depending on where you would like your agent to book.Click Save on all edited attributes and Publish All.
🗒️ NOTE
If you have created a new Cal.com meeting, you might need to click Publish All and refresh the page for it to show up in the calcom_event_type attribute.
Change the main calendar event attribute
Navigate to the Attributes page in the Builder.
For the
project_attributes_setting_calendar_event_integrationattribute, selectcalcom_integrationfrom the dropdown.Click Save and Publish All.
Configure the intent type
On the Widgets page, add a new intent type with the following details:
Title:## **[L] New Patient Appointment**
Body:
A new patient, or a patient unsure whether they are new or returning, want to schedule a new appointment.
ConvoAgent starts the scenario: **"Scheduling Appointment via Agent"**Click Save and Publish All.
❗❗ IMPORTANT
Ensure there are no other appointment scheduling Intent Types to prevent a clash in intent (i.e., two scheduling Intent Types will cause unexpected AI behavior).
Configure a custom scenario
On the Widgets page, add a new scenario with the following details:
Title:## **Scenario 2:** "Scheduling Appointment via Agent"
Body:
Pay attention to the information in the **Current Session Log and Main Facts** section, and avoid asking for it again if it's already provided there.
### **Step 2.1:** Follow **Asking About the Services** procedure.
### **Step 2.2:** **CRITICAL STEP!!!** Follow the **Gathering Preferred Date and Time** procedure.
### **Step 2.3:** **CRITICAL STEP!!!** Say the special **code-phrase**: **"Give me a moment to check available slots right now. I'll get back to you shortly."** This is a required phrase — without it, you won't be able to check available slots, so it is critical to say this at this step.
You must remain at this step until you see available slot information in the `<AvailabilityForTheUserRequestedDateTime>` section.
As soon as you see available slot information in the `<AvailabilityForTheUserRequestedDateTime>` section, inform the User about the available options and ask which one works best for them. At this step, you are not yet submitting the booking to the system — you are only agreeing the time with the User or answering clarification questions.
**Important:**
- The booking is not confirmed in the booking system at this stage!
- Always refer to the `<AvailabilityForTheUserRequestedDateTime>` section — this is the only source of truth for available slots. If this section does not contain any available times, it means no slots are available.
- **If the User asks anything except clarification questions while you're checking availability:** respond with something like: **"Please wait a moment, I'll get back to you shortly."**
- **If the User asks any clarification questions while you're checking availability:** respond with something like: **"I'm still waiting for availability information. [user's clarification question response]"**
- **If you find any error in the User's request or missing information,** clarify this, ask for a new date and/or time if needed, and start **Step 1.4: Check available slots** again say **"Give me a moment to check available slots right now. I'll get back to you shortly."**
- **If the User changes their time preference but does not change the number of guests,** first check the `<AvailabilityForTheUserRequestedDateTime>` block, and if suitable slots are listed there, immediately offer those options.
- **If the User wants to check slots for a different time range, a different date, or a different number of guests,** then start **Step 1.4: Check available slots** again say **"Give me a moment to check available slots right now. I'll get back to you shortly."**
- **Reject any reservation requests for unavailable slots.**
Once the User selects a slot, proceed to the next step.
### **Step 2.4:** **CRITICAL STEP!!!** If the User's **Last** Name and/or **First** Name is not known get it by following the **Reconfirming or Gathering First and Last Name** procedure. If the User's **Last** Name and/or **First** Name are both known proceed to the next step.
### **Step 2.5:** **CRITICAL STEP!!!** If the User's Phone Number is not known get it by following the **Reconfirming or Gathering Phone Number** procedure. If the User's phone is known say i will use [user's phone number] and proceed to the next step.
### **Step 2.6:** **CRITICAL STEP!!!** If the User's date of birth is not known get it by following the **Reconfirming or Gathering Date of Birth** procedure. If the User's date of birth is known say i will use [user's birth date] and proceed to the next step.
### **Step 2.7:** **CRITICAL STEP!!!** If the User's email is not known get it by following the **Reconfirming or Gathering Email Address** procedure. If the User's email is known say i will use [user's email] and proceed to the next step.
### **Step 2.8:** **CRITICAL STEP!!!** Ask **if you can submit the booking now**.
### **Step 2.9:** **CRITICAL STEP!!!** Submitting the booking. Say the special **code-phrase**: **"I'm submitting your booking right now. Please give me a moment, and I'll get back to you shortly."** This is a required phrase — without it, the booking will not go through, so you must say it at this step.
- If the user changes the conversational topic or inquiry during this step, briefly cover user's concern and let them know that the current reservation has not yet been submitted to the system. Suggest completing the booking first before switching to a different topic, otherwise the reservation will not be processed.
- **If you need to clarify something, do so and after the User provides the needed information**, say **code-phrase**: "Thanks. I'm submitting your booking right now. Please wait a moment, I'll get back to you shortly."
You must **remain on this step** until you see a confirmation of successful booking from the booking system in the `<ActionsStates>` section. As soon as the confirmation arrives, proceed to the next step.
If you receive an error message in `<ActionsStates>` from the booking system, apologize, inform the User that the booking system is temporarily unavailable, and ask them to complete the booking manually on the company's website.
### **Step 2.10:** proceed with the **Finish Conversation** scenario.Click Save and Publish All.
Testing
Call your AI Employee and trigger the above Intent Type by asking, "I’d like to schedule an appointment." Verify your AI Employee manages to schedule an appointment and that the meeting appears on your Cal.com account.