Appointment Booking Skill for Voice Agents

User level: Admin

---

​

What the Appointment Booking skill does

When a caller asks for an appointment, your Voice Agent checks your connected calendar or scheduling platform for open slots, proposes available times, confirms the caller’s choice, and creates the booking, all during the call. The agent tells the caller the appointment is booked only after the booking has actually been created. This skill is built for teams that book time with customers over the phone:

• AI Receptionists scheduling consultations and callbacks
• Service businesses booking in-person visits (car service, repairs, clinics)
• Field service teams scheduling technician visits at the customer’s location
• Consultants and sales teams booking discovery or follow-up calls

​

Before you start

You need:

• A CloudTalk account with Voice Agents enabled
• Admin access to edit the Voice Agent
• One of these to book into:
  • A Google Calendar or Microsoft Outlook account with permission to grant third-party app access (see Troubleshooting if your company restricts this)
  • A Calendly account on any plan, with the event type you want the agent to book already set up
  • A Cal.com cloud account with the event type already set up (self-hosted Cal.com isn’t supported)

​

Set up the skill

1. Open your Voice Agent and go to Skills.
2. Click Add next to Appointment Booking, or Edit if the skill is already added.
   
3. Connect your calendar or scheduling platform.
   • Google Calendar or Microsoft Outlook: complete the OAuth consent flow.
   • Calendly: paste a personal access token. We recommend creating it as a dedicated, non-admin Calendly user. Click Open Personal access tokens in Calendly in the dialog, then click Generate new token. Give the token the scopes users:read, event_types:read and scheduled_events:write. Calendly shows the token only once.
   • Cal.com: paste an API key created by a team admin or owner. In Cal.com, go to Settings > Developer > API keys, click New, and turn on Never expires so the connection doesn’t break when the key expires. Cal.com shows the key only once.
   If your company already has a connected integration, you can select it here instead of creating a new one.
   
4. Select a calendar. The dropdown lists all calendars under the connected account: the account’s own calendars plus any shared calendars it has access to, with permission to add events to that calendar, such as a team or company booking calendar. Choose the specific calendar the agent will read availability from and write bookings to. Each Voice Agent uses one calendar. Calendly or Cal.com: select an event type instead. The agent books into that event type, and Calendly or Cal.com assigns the host. Each Voice Agent uses one event type. Event types the agent can’t book are greyed out with the reason: event types with required custom questions, event types that require confirmation, Calendly collective and multi-pool event types, and the Cal.com managed event type template. Each team member’s copy of a managed event type can be booked.
   💡 Booking for a team: with Google Calendar or Outlook, the skill books into exactly one calendar. It does not distribute bookings across team members, pick an available person from a group, or handle shift-based working hours. If your team manages all bookable time in a single shared calendar, you can connect an account with permission to add events to that calendar and select it here. For advanced team scheduling (round-robin assignment, load balancing, or multiple shift schedules), connect Calendly or Cal.com in step 3 and select a round-robin event type.
5. Configure the booking settings:
   • Event name: the title written to the calendar event (e.g. “Sales Meeting”, “New Patient Consultation”).
   • Meeting duration: 15, 30, or 60 minutes, or a custom length.
   • Meeting type: how the appointment happens (see below).
   • What to include in the calendar event: what the agent should extract from the conversation and write into the event description.
   With Calendly or Cal.com, the duration and meeting location come from the event type, and the event name defaults to the event type’s name. You also choose which variable the calendar invite takes the caller’s email from. See The caller’s email address.
   
6. Click Save. Your agent can now book appointments.

​

Availability, working hours, and buffers

The agent only offers slots that are free in your connected calendar. Working hours, buffers between meetings, and blocked time are all controlled in your calendar provider, not in CloudTalk. This means your existing calendar setup is the single source of truth. To control when the agent can book:

• Google Calendar: set your working hours in Calendar settings. Follow Google’s guide: Set your working hours & location. Note that working hours require a Google Workspace account. To block specific time, create events or out-of-office entries directly in the calendar.
• Microsoft Outlook: set your work hours in Outlook settings. Follow Microsoft’s guide: Set your work hours and location in Outlook. Work hours require a work or school Microsoft 365 account.
• Calendly or Cal.com: set availability, buffers and booking limits on the event type. Availability comes from the event type; the agent proposes a few of those slots and does not calculate availability itself.

Any event already on the calendar is treated as busy, so the agent won’t offer that slot.

​

What gets written to the calendar

Each booking creates an event on your selected calendar:

• Title: your configured event name
• Time: the confirmed slot, with your configured duration
• Description: caller’s name, phone number, reason for the appointment, and any custom fields you configured
• Location: your company address (in-person) or the caller’s address (service visit)

With Calendly or Cal.com, the booking is created on your event type in the platform instead. Calendly or Cal.com assigns the host and, when the booking has an email address, sends the caller the invite. The agent names the host only when the platform returns one. Otherwise it tells the caller they’ll meet someone from your team.

​

SMS confirmation

When you enable the Appointment Booking skill, CloudTalk adds a scenario with the trigger Booking is confirmed and a Send SMS action. After the call ends, the caller gets a text with the appointment details. The scenario is only created if your account has an SMS-capable number. You can change the wording, pick a different sender number, or delete the scenario. The default message is: Your {{appointment.event_name}} is confirmed for {{appointment.start_pretty}}. Type {{ in the Message field to insert a variable. These are available:

​

The caller’s email address (Calendly and Cal.com)

Calendly and Cal.com need the caller’s email address for most event types, and they send the calendar invite to it as soon as the booking is made. The agent never asks the caller for an email address or reads one out. Instead, the booking skill’s invite e-mail setting names the variable the address comes from:

• contact.emails (the starting value): the emails on the CloudTalk contact the call is about. If there are several, the invite goes to the first valid one.
• Your own variable, for example {{customer_email}}: for outbound calls started through the API, send the address in call_properties.system_prompt.variables of Initiate VoiceAgent call. Outbound calls can then book without a CloudTalk contact. Inbound calls carry only contact fields, so your own variable is always empty there.

If the variable is empty or holds no valid address, the agent doesn’t offer times for an event type that needs an email. If the failed-booking SMS is set up, the agent tells the caller they’ll get a text with a link to pick a time, and the SMS sends your event type’s scheduling link. Cal.com event types that only ask for a phone number book without an email.

​

If a booking can’t be completed

The agent tells the caller an appointment is booked only after the booking exists. With Calendly and Cal.com, if the booking can’t be made, the agent tells the caller it couldn’t finish the booking, and CloudTalk texts them your event type’s scheduling link so they can book online. This happens when there’s no usable email address (see above) or when the platform returns an error. If the time the caller picked is taken during the call, the agent offers another time before falling back to the link. The text comes from an SMS scenario with the trigger When appointment booking fails (error or insufficient information). It’s pre-filled when you add the skill with Calendly or Cal.com, and you can edit or remove it. No text is sent if you remove the scenario, or while the connection needs a new API key or token.

​

Limits with Calendly and Cal.com

• Each Voice Agent books into one event type.
• The agent can’t reschedule or cancel bookings. Callers can use the links in their invite.
• Changes made later in Calendly or Cal.com aren’t synced back to CloudTalk.
• Calendly caps how many bookings a token owner can create per minute, hour and day, and the cap depends on the Calendly plan. Agents that share a token share that budget. See Calendly’s rate limits for current numbers.
• Self-hosted Cal.com isn’t supported.

​

Managing the calendar integration

Connected calendar accounts live under Settings > Integrations. The integration detail page shows the connected account email, its status, and the list of Voice Agents using it. A few things to know:

• Multiple Google, Outlook, Calendly or Cal.com accounts can be connected in one company, for example different team members connecting their own calendars.
• The same integration can be used by multiple Voice Agents, but each agent books into exactly one calendar.
• The specific calendar is chosen per agent in the skill settings, not on the integration page.
• Calendly and Cal.com connect with a token you paste instead of OAuth. The event type is chosen per agent in the skill settings.
• A booking skill on Calendly or Cal.com is set up in the dashboard. The Voice Agent API reads it, but a create or replace that names a Calendly or Cal.com integration is refused.

​

Troubleshooting

• The calendar connection shows an error. This happens when the OAuth token stops working, for example the connecting admin left the company, the account was disabled, or permissions were revoked. Your Voice Agents stay active, but the booking skill is paused and won’t be offered to callers until the connection is restored. Open Settings > Integrations, check which agents are affected, and click Reconnect.
• I can’t complete the OAuth consent. Some companies restrict which third-party apps can access Google Workspace or Microsoft 365. If the consent screen shows an approval or permission error, ask your IT admin to allow CloudTalk:
  • Google Workspace: the admin manages third-party app access in the Google Admin console (Security > API controls > App access control).
  • Microsoft 365: the admin manages app consent in the Microsoft Entra admin center (Enterprise applications > Consent and permissions), or approves the request via admin consent workflow.
• The agent offers times we’re not available. Check the working hours and blocked time in the connected calendar, since the agent mirrors exactly what the calendar shows as free. Also verify the correct calendar is selected in the skill settings.
• The Calendly or Cal.com connection asks for a new API key. The token stopped working, so the agent stops booking and no failed-booking text is sent until you fix it. Common causes: the Cal.com key was deleted or expired, or the Calendly token was revoked. Calendly revokes a token when its owner changes their login email, password or login method. Create a new key or token and enter it with Re-enter API key.
• An event type is greyed out. The list shows the reason. The agent can’t book event types with required custom questions, event types that require confirmation, Calendly collective and multi-pool event types, or the Cal.com managed event type template. Each team member’s copy of a managed event type can be booked.
• Calendly or Cal.com isn’t offered, or the skill says booking isn’t enabled for your company. Calendly and Cal.com booking may not be enabled for your company or plan. Contact your Customer Success manager.
• Calendly or Cal.com calls end with a scheduling link instead of a booking. Check that the invite e-mail variable holds an address for those calls: the contact needs an email, or your API call needs to send your own variable. On inbound calls, only contact emails work. For Calendly, also check that the token owner hasn’t hit Calendly’s booking limit.
• Callers hear the wrong timezone. With Google Calendar or Outlook, update the calendar’s default timezone in its settings. With Calendly or Cal.com, update the event type’s timezone.
• We already built a calendar integration with custom Tools. Existing custom tools keep working. We recommend migrating to the native skill for simpler setup and built-in error handling. Your Customer Success manager can help. If you connected Calendly or Cal.com through custom Tools or an automation platform such as Zapier, Make or n8n, you can now connect them directly in step 3.

---

Need help or have a question? Just reach out through our Support portal — we’re here for you.