Skip to main content

Calendly integration

Updated today

This article explains how to connect Calendly to your AI Employee. This integration enables your AI Employee to manage schedules and appointments. By connecting your Calendly account, your agent can check availability, book new meetings, and cancel existing appointments on behalf of users.

Prerequisites

  • A Calendly account (Professional plan or higher).

  • A registered OAuth application in the Calendly Developer Portal.

  • At least one event type configured in Calendly with the location set to Phone Call (outbound).

Configure your Newo.ai project

  1. Navigate to your customer's Builder.

  2. Go to the Projects page, click the three dots icon in the top-right and Create New Project.

  3. Fill in the following fields and ensure Auto update enabled is turned on:

    • Idn:calendly

    • Title:calendly

    • Registry:production

    • Module:calendly_integration

  4. Click Create.

  5. Click the three dots icon next to the newly created project.

  6. Click Force Update Project.

Set up your Calendly OAuth application

  1. Go to the Calendly Developer Portal and register a new web application.

  2. Set the redirect URI to https://static.newo.ai/auth.html.

  3. Enable all scopes across the scheduling, user management, security, and webhooks categories.

  4. Save the application and copy the Client ID and Client Secret — you will need these in the next section.

Configure your Calendly event type

In your Calendly account, open the event type you want the agent to use and set its location to Phone Call (outbound). This tells Calendly to initiate calls to invitees when a booking is created.

Connect Calendly to your Newo.ai account

  1. Navigate to the Attributes page in the Builder.

  2. Paste the Client ID from Calendly into the calendly_client_id attribute.

  3. Paste the Client Secret from Calendly into the calendly_client_secret attribute.

  4. Click Save and Publish All.

  5. A calendly_oauth_link attribute will appear on the page — click the link to open the Calendly authorization page.

  6. Approve access in Calendly.

  7. Copy the verification code provided by Calendly and paste it into the calendly_oauth_code attribute.

  8. Click Save and Publish All.

  9. The calendly_event_type_uri dropdown will populate with your Calendly event types — select the event type you want the agent to use.

  10. Click Save and Publish All.

  11. Search for the Booking - Enabled (project_attributes_setting_booking_enabled) attribute, set it to True, and click Save.

  12. Click Publish All.

Change the main calendar event attribute

  1. Navigate to the Attributes page in the Builder.

  2. For the project_attributes_setting_calendar_event_integration attribute, select calendly_integration from the dropdown.

  3. Click Save and Publish All.

Optional attribute settings

The following attributes can be adjusted if needed (available in the Builder only; toggle Show Hidden on the Attributes page):

  • Calendly - Slot Window Duration: How far ahead the agent checks for available slots, in days. Default is 5 days; maximum is 7.

  • Calendly - Slot Duration: Duration of each bookable slot in minutes. Default is 30.

  • Feature toggles for availability checking, booking, and cancellation can each be enabled or disabled independently.

Configure the intent type

🗒️ NOTE

The intent type and scenario templates below are dental industry examples. Adapt the language, step content, and any industry-specific steps to match your specific use case.

  1. On the Widgets page, add a new intent type with the Title and Body values shown below.

  2. Click Save and Publish All.

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"**

❗❗ 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

  1. On the Widgets page, add a new scenario with the Title and Body values shown below.

  2. Click Save and Publish All.

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 2.3: 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 2.3: 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 — ask the User to include their country code. 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 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.7:** **CRITICAL STEP!!!** Ask **if you can submit the booking now**.
 
### **Step 2.8:** **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.9:** proceed with the **Finish Conversation** scenario.

Testing

Call your AI Employee and trigger the above intent type by asking, "I'd like to schedule an appointment." Verify your AI Employee checks availability, manages to schedule an appointment, and that the meeting appears on your Calendly account.

Related Articles
Use code phrases and critical steps to trigger tools
Troubleshoot issues with code-phrases (action triggers)
Cal.com integration
Housecall Pro integration
GoHighLevel use cases and scenarios
Did this answer your question?