AI agents

How AI agents can use the Cal.com API v2 to manage scheduling

To connect an agent with one prompt, paste this into it: Use curl to read https://cal.com/docs/agent-quickstart.md, then follow it to connect Cal.com to this agent, signing me up if I don't have an account, and check it works by listing my event types. See the agent quickstart.

This guide explains how to build AI agents that interact with Cal.com’s scheduling infrastructure.

​

Recommended: Use the Cal.com CLI

For agents that can execute commands on a machine, use the official Cal.com CLI instead of calling the API directly. The CLI handles authentication, versioning, and common workflows automatically.

npm

npm install -g @calcom/cli

curl

curl -fsSL https://cal.com/install.sh | bash

The CLI includes --help flags on all commands to learn about available options:

calcom --help
calcom bookings --help
calcom slots --help

Only fall back to the API approach below if your agent cannot install or execute the CLI on its machine.

For hosted MCP OAuth or headless API v2 device authorization, see the agent quickstart.

​

Overview

Cal.com API v2 enables AI agents to:

• Check availability - Query available time slots for any user or team
• Create bookings - Schedule meetings on behalf of users
• Manage event types - Create and configure different meeting types
• Handle rescheduling and cancellations - Modify existing bookings
• Manage schedules - Set and update user availability
• Track credit usage - Check balances and charge credits for agent interactions

​

Authentication

AI agents should authenticate using an API key. Generate one in Settings → Developer → API Keys.

curl -X GET "https://api.cal.com/v2/me" \
  -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \
  -H "cal-api-version: 2024-08-13"

The cal-api-version header is required for all v2 endpoints. If you omit it, requests will return a 404. Always include cal-api-version: 2024-08-13.

​

Common workflows

​

1. Check availability

Query available slots using username and event slug—no need to look up IDs first:

curl -X GET "https://api.cal.com/v2/slots?username=bailey&eventSlug=15min&startTime=2024-01-15T00:00:00Z&endTime=2024-01-16T23:59:59Z" \
  -H "cal-api-version: 2024-08-13"

Response includes available time slots:

{
  "status": "success",
  "data": {
    "slots": {
      "2024-01-15": [
        { "time": "2024-01-15T09:00:00Z" },
        { "time": "2024-01-15T10:00:00Z" },
        { "time": "2024-01-15T14:00:00Z" }
      ]
    }
  }
}

​

2. Create a booking

Schedule a meeting using username and event slug. This is the most common pattern for AI agents that extract scheduling intent from natural language (e.g., “book 15min with bailey”):

curl -X POST "https://api.cal.com/v2/bookings" \
  -H "Content-Type: application/json" \
  -H "cal-api-version: 2024-08-13" \
  -d '{
    "eventTypeSlug": "15min",
    "username": "bailey",
    "start": "2024-01-15T09:00:00Z",
    "attendee": {
      "name": "John Doe",
      "email": "[e-mail]",
      "timeZone": "America/New_York"
    }
  }'

The booking creation endpoint is public and does not require authentication. This allows agents to book on behalf of external users.

​

3. Handle custom booking questions

Most Cal.com users have required questions on their booking pages (e.g., “What is this meeting about?”). If you omit required fields, the API returns a 400 error.

Include responses in bookingFieldsResponses:

curl -X POST "https://api.cal.com/v2/bookings" \
  -H "Content-Type: application/json" \
  -H "cal-api-version: 2024-08-13" \
  -d '{
    "eventTypeSlug": "consultation",
    "username": "bailey",
    "start": "2024-01-15T09:00:00Z",
    "attendee": {
      "name": "John Doe",
      "email": "[e-mail]",
      "timeZone": "America/New_York"
    },
    "bookingFieldsResponses": {
      "notes": "Discussing the new AI integration",
      "company_size": "10-50"
    }
  }'

To discover which fields are required, fetch the event type details first. The bookingFields array shows all custom questions and their requirements.

​

4. Instant bookings for urgent requests

For teams handling urgent requests, use the instant flag to bypass normal scheduling and immediately ring available team members:

curl -X POST "https://api.cal.com/v2/bookings" \
  -H "Content-Type: application/json" \
  -H "cal-api-version: 2024-08-13" \
  -d '{
    "eventTypeSlug": "urgent-support",
    "username": "support-team",
    "start": "2024-01-15T09:00:00Z",
    "instant": true,
    "attendee": {
      "name": "John Doe",
      "email": "[e-mail]",
      "timeZone": "America/New_York"
    }
  }'

Instant bookings require the event type to be configured for instant meetings. This is ideal for AI agents routing urgent customer requests.

​

5. Get user’s event types

Retrieve available event types to offer booking options:

curl -X GET "https://api.cal.com/v2/event-types?username=bailey" \
  -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \
  -H "cal-api-version: 2024-08-13"

​

6. Reschedule a booking

Move an existing booking to a new time:

curl -X POST "https://api.cal.com/v2/bookings/{bookingUid}/reschedule" \
  -H "Content-Type: application/json" \
  -H "cal-api-version: 2024-08-13" \
  -d '{
    "start": "2024-01-16T10:00:00Z",
    "rescheduleReason": "Attendee requested different time"
  }'

​

7. Cancel a booking

curl -X POST "https://api.cal.com/v2/bookings/{bookingUid}/cancel" \
  -H "Content-Type: application/json" \
  -H "cal-api-version: 2024-08-13" \
  -d '{
    "cancellationReason": "Meeting no longer needed"
  }'

​

Credit management

If your AI agent runs on the Cal.com platform, you can track usage by checking and charging credits through the API. This is useful for metering agent interactions against your account’s credit balance.

​

Check available credits

Before performing a billable action, verify that the user or team has sufficient credits:

curl -X GET "https://api.cal.com/v2/credits/available" \
  -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \
  -H "cal-api-version: 2024-08-13"

Response:

{
  "status": "success",
  "data": {
    "hasCredits": true,
    "balance": {
      "monthlyRemaining": 450,
      "additional": 200
    }
  }
}

The balance object breaks down your remaining credits:

• monthlyRemaining — credits included in your current billing cycle
• additional — purchased credits outside the monthly allowance

​

Charge credits

After a completed agent interaction, charge the appropriate number of credits:

Personal accounts charge their own credits. Charging a team or organization balance requires accepted membership and manageBilling permission on it; otherwise the API returns 403 Forbidden. A team or organization with credits is charged before personal credits, so a member without manageBilling gets 403 even if they have personal credits. If the balance does not cover the requested amount, the API returns 402 Payment Required without charging.

curl -X POST "https://api.cal.com/v2/credits/charge" \
  -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "cal-api-version: 2024-08-13" \
  -d '{
    "credits": 5,
    "creditFor": "AI_AGENT",
    "externalRef": "agent-thread-abc-1711432800000"
  }'

Response:

{
  "status": "success",
  "data": {
    "charged": true,
    "remainingBalance": {
      "monthlyRemaining": 445,
      "additional": 200
    }
  }
}

Parameter	Required	Description
credits	Yes	Number of credits to charge (1–10,000)
creditFor	Yes	Usage type — use AI_AGENT for agent interactions
externalRef	No	Reference string of 1–255 characters, scoped to the caller for idempotency. Prevents double-charging if the same request is retried.

A replay returns charged: false, duplicate: true without another charge. References are stored as api:<userId>:<externalRef>, separate from system references and other callers’ references.

Always include an externalRef tied to your agent’s conversation or thread ID. This prevents duplicate charges if a network retry sends the same request twice.

​

Example: check-then-charge pattern

Checking availability does not reserve credits or grant billing permission. The charge can still return 403 or 402 after the interaction completes. Reuse the same reference when retrying a completed interaction.

const headers = {
  "Authorization": "Bearer cal_live_xxxxxxxxxxxx",
  "Content-Type": "application/json",
  "cal-api-version": "2024-08-13"
};

// 1. Check credits before starting work
const available = await fetch("https://api.cal.com/v2/credits/available", { headers });
const { data } = await available.json();

if (!data.hasCredits) {
  throw new Error("No credits available");
}

// 2. Perform the agent interaction
const externalRef = `thread-${threadId}-${interactionId}`;
const result = await runAgentTask();

// 3. Charge credits after completion
const charge = await fetch("https://api.cal.com/v2/credits/charge", {
  method: "POST",
  headers,
  body: JSON.stringify({
    credits: 5,
    creditFor: "AI_AGENT",
    externalRef
  })
});

if (charge.status === 403) {
  throw new Error("Team or organization manageBilling permission required");
}
if (charge.status === 402) {
  throw new Error("Insufficient credits to cover the charge");
}
if (!charge.ok) {
  throw new Error(`Charge failed: ${charge.status}`);
}

const { data: charged } = await charge.json();
if (charged.duplicate) {
  console.log("Already charged; no additional credits deducted");
}

​

Best practices for AI agents

​

Handle time zones correctly

Always specify time zones explicitly. Store user preferences and pass them in requests:

{
  "attendee": {
    "timeZone": "Europe/London"
  }
}

​

Implement retry logic

API requests may occasionally fail. Implement exponential backoff:

async function callWithRetry(fn: () => Promise<Response>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fn();
      if (response.ok) return response;
      if (response.status === 429) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw new Error(`API error: ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

​

Validate availability before booking

Always check slots before attempting to create a booking to avoid conflicts:

// 1. Get available slots
const slots = await getAvailableSlots("bailey", "15min", startDate, endDate);

// 2. Verify the desired slot is available
const isAvailable = slots.some(slot => slot.time === desiredTime);

// 3. Create booking only if slot is available
if (isAvailable) {
  await createBooking("bailey", "15min", desiredTime, attendee);
}

​

Use webhooks for real-time updates

Configure webhooks to receive notifications when bookings are created, rescheduled, or cancelled:

curl -X POST "https://api.cal.com/v2/webhooks" \
  -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "cal-api-version: 2024-08-13" \
  -d '{
    "subscriberUrl": "https://your-agent.com/webhooks/cal",
    "eventTriggers": ["BOOKING_CREATED", "BOOKING_RESCHEDULED", "BOOKING_CANCELLED"],
    "active": true
  }'

​

Discover the API from a booking page

Cal.com web app pages, including personal, team and organization booking pages, send a Link header that points agents to the API:

curl -sI "https://cal.com/bailey/15min" | grep -i "^link"

Relation	Points to
api-catalog	/.well-known/api-catalog on the same host, which lists the API v2 and the hosted MCP server
service-desc	The API v2 OpenAPI description (JSON)
service-doc	The API v2 reference

Discovery documents under /.well-known/ also work on organization domains such as acme.cal.com. They are served as discovery documents, not treated as organization booking pages.

​

OAuth protected-resource metadata

Each origin serves OAuth protected-resource metadata (RFC 9728) for the page you are on. /.well-known/oauth-protected-resource names the origin itself as the resource. To get metadata for a specific page, add its path after the metadata path:

curl "https://acme.cal.com/.well-known/oauth-protected-resource/bailey/15min"

{
  "resource": "https://acme.cal.com/bailey/15min",
  "authorization_servers": ["https://cal.com"],
  "scopes_supported": ["EVENT_TYPE_READ", "EVENT_TYPE_WRITE", "BOOKING_READ", "..."],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://cal.com/docs/api-reference/v2/introduction"
}

The response lists the Cal.com OAuth authorization server, the supported scopes and the API documentation. The API keeps its own metadata at https://api.cal.com/.well-known/oauth-protected-resource, which the API catalog links to.

​

Read a booking page without JavaScript

Personal booking pages and profile pages also describe themselves to agents that only read HTML or Markdown, so an agent can check availability and book without running the page’s JavaScript.

​

Markdown documents

Add .md to an event’s booking link, or /llms.txt to a profile link, to get a Markdown document for agents:

URL	Contains
/<user>/llms.txt	The user’s public event types, each with its duration, confirmation policy, whether it’s paid, its event type ID and a link to its .md document, plus the slots request and a link to the API docs
/<user>/<event>.md	One event type: host, duration, location, host time zone, confirmation policy and event type ID, a ready-to-use slots request, a POST /v2/bookings request body, and the required and optional booking fields

curl "https://cal.com/bailey/llms.txt"
curl "https://cal.com/bailey/15min.md"

The documents use the same host as the booking page, including organization domains such as acme.cal.com, and are returned as text/markdown. No API key is needed to read them, or to send the slots request (cal-api-version: 2024-09-04) and bookings request (cal-api-version: 2026-02-25) they describe.

In an event’s .md document:

• Hidden booking questions aren’t listed.
• When the event’s first location asks the attendee for their phone number, address or own location, the booking body includes location and the document says it’s required. When the event has several locations, location is optional and the booking uses the first one.
• When the event offers several durations, the body includes lengthInMinutes, and the same value goes in the slots request as duration.
• When the host confirms each booking, a successful response is a pending booking request.

If the user or event doesn’t exist, the response is a short text/plain 404. If the booking page redirects to the same page on another host, the request is redirected to that host’s document. Documents for hidden event types and pages that aren’t indexed by search engines are sent with X-Robots-Tag: noindex.

​

Structured data in the page

The HTML of a personal event’s booking page also includes:

• A <noscript> summary with the host, duration, location, host time zone, confirmation policy and required booking fields, and links to the slots API and the event’s .md document.
• schema.org Service JSON-LD with a ReserveAction that targets POST /v2/bookings. Its result is ReservationPending when the host confirms each booking and ReservationConfirmed otherwise.
• <link rel="alternate"> tags pointing to the .md document (text/markdown) and to /v2/slots?eventTypeId=… (application/json).
• A meta description that states the duration, host, location and confirmation policy.

Profile pages include schema.org Person JSON-LD listing the user’s public event types, and a <link rel="alternate" type="text/markdown"> to their llms.txt.

Team event pages, dynamic group links and unpublished pages don’t have these documents or this markup yet. Self-hosted instances only serve them when NEXT_PUBLIC_API_V2_URL points to the instance’s own API v2.

​

Booking page tools for in-browser agents

Cal.com booking pages register WebMCP tools when the visitor’s browser supports WebMCP (document.modelContext). An agent running in the browser can use them to read the event and pick a time without scraping the page.

Tool	Input	Description
get_event_details	None	Returns the event title, duration in minutes and the visitor’s time zone
list_available_times	date (optional, YYYY-MM-DD)	Lists available start times for the dates currently loaded in the calendar, in the visitor’s time zone. With a date, returns that date only; without one, returns up to the first seven loaded dates that have availability. Out-of-office times are excluded.
select_time	time (required, ISO start time)	Selects one of the currently loaded available times and opens the booking form, just like clicking the time on the page

Each tool returns its result as JSON text.

select_time never creates a booking. The visitor still has to fill in the booking form and confirm. It declines, and asks for the time to be picked on the page, when the event asks the booker to propose several times or when picking a time would book straight away (for example, because every required booking question is already prefilled).

​

Who can use the Cal.com assistant

The Cal.com assistant is available to every signed-in Cal.com user, including personal accounts that don’t belong to an organization. There’s nothing to turn on.

• Web: select Home in the sidebar, or open the assistant from any app page.
• Slack, Telegram and iMessage: link the app to your Cal.com account through the Cal.com assistant, then message it there.

​

Dock the assistant to the right side

On the web, when your browser window is at least 1,024 pixels wide, you can dock the assistant panel to the right side of the window, so a conversation stays open beside the page you’re working on.

• To dock it, open the assistant from the floating toolbar on any app page and select Dock to the right in the panel’s header. The panel fills the right side of the window, and the page narrows to make room for it instead of being covered.
• The panel stays docked, with the same conversation, as you move between pages in Cal.com.
• To resize it, drag its left edge, or focus the edge and use the arrow keys. It can be 320 to 640 pixels wide, and starts at 416. The width is kept for that browser tab, including after you reload the page.
• To go back to the floating panel, select Undock. Selecting close or pressing Escape closes the panel and gives the page its full width back. The next time you open the assistant in that tab, it opens docked again.

While docked, the panel has no minimize or full-page buttons. Docking isn’t available in narrower windows or on mobile: if the window becomes narrower than 1,024 pixels, the panel goes back to floating and stays floating when you widen the window again. After a reload, the assistant opens as a floating panel until you dock it again.

​

Open the assistant with a prompt already typed

You can link someone to the Cal.com assistant with a request already written for them by adding q with a URL-encoded prompt to the Home page address, for example https://app.cal.com/home?q=book%20pro%2F30min.

When a signed-in user opens the link, the prompt appears in the chat box but isn’t sent. They can edit it, then press Enter to send it, so opening a link never uses AI credits or starts work on its own. Once the prompt is in the chat box, q is removed from the address, so reloading the page doesn’t add it again.

q is ignored when the link also opens an existing chat with session. If the user has to sign in first, they come back to the chat box with the prompt after signing in.

​

Continue a chat in iMessage, Slack, ChatGPT or Claude

On the Home page, select the arrow button (Continue in another assistant) in the top-right of the header to take your conversation somewhere else. Under Continue in…, pick one of:

Option	What happens
iMessage	Opens Messages with a new message to the Cal.com assistant’s iMessage number, prefilled with your last request. If you haven’t asked anything yet, the message is empty. If your phone number isn’t linked to Cal.com yet, the assistant replies with a link to connect your account.
Slack	Opens the Cal.com Slack app page in a new tab, where you install or connect the app and then message the assistant in Slack. Nothing from your chat is carried over.
ChatGPT or Claude	Opens a new chat in a new tab with a prompt that asks it to use the Cal.com MCP server for your account, explain how to connect it if it isn’t connected yet, and then continue your last request. If you haven’t asked anything yet, the prompt only asks it to use the MCP server.

Only your last message is handed over, cut to 2,000 characters. The assistant’s replies and anything it looked up stay in Cal.com.

The same menu has two more options for connecting ChatGPT, Claude or another AI client to your Cal.com account: Copy MCP server URL copies https://mcp.cal.com/mcp, and How to connect the MCP server opens the MCP server guide.

The menu is only on the Home page, not in the floating assistant toolbar. The iMessage option opens Messages on a Mac, iPhone or iPad. On other devices it may open your text messaging app or nothing at all.

​

Free questions without AI credits

If you have no AI credits, you can still ask the Cal.com assistant 30 questions a month for free, as long as your email address is verified. Free questions work on the web and in Slack, Telegram and iMessage, and they don’t use or add credits.

• The 30 questions reset at the start of each calendar month (UTC).
• Each new message counts as one question, including a follow-up sent while the assistant is still answering. Retrying the same message, or answering an approval the assistant asked for, doesn’t use another question.
• From your second free question, the Home page shows how much of this month’s free usage you’ve reached: a progress bar at the bottom of the page on desktop (hover it to see the percentage) and above the chat box on mobile.
• After the thirtieth question, the assistant replies that you’re out of AI credits and points you to Settings → Billing to buy more. Your free questions come back at the start of the next month (UTC). When you have AI credits, the assistant uses them as usual and free questions aren’t counted.

​

When you’re out of AI credits

When you have no AI credits, the Cal.com assistant on the web stops you before you send a message, so you don’t type a request that can’t run. The chat box is disabled and the assistant checks your balance again each time you come back to the window.

• New chat: instead of the suggested questions, the assistant shows Add credits to start a conversation.
• Existing conversation: an alert, You’re out of credits, appears above the chat box. Your earlier messages stay visible, and your event types, bookings and workflows aren’t affected. If a reply is still in progress, you can still stop it.

Both show a way to add credits, depending on what you can manage:

You are	What you see
On a personal account, not in any team	Buy credits, which opens Settings → Billing
A member of a team with permission to manage its billing	Open billing, which opens that team’s billing settings
A member of an organization with permission to manage its billing	Open billing, which opens the organization’s billing settings
In a team or organization without billing access	”Ask an owner or admin to add credits.” and no button

Once credits are added, return to the chat and the chat box works again.

In Slack, Telegram and iMessage, the assistant replies that you’re out of AI credits and points you to Settings → Billing instead of answering.

​

Rename a chat

On the web, you can rename a Cal.com assistant chat, so you can still find it in your history after the conversation has moved on from its first topic.

1. Open your chat history

   On the Home page, select the chat title in the header. In the floating assistant toolbar on other pages, select the history icon (Chat history).

2. Edit the title

   Select the pencil next to the chat you want to rename. The chat doesn’t open.

3. Save the new name

   Type the new name and press Enter, or click outside the field. Press Escape to keep the old name.

• A name can be up to 120 characters. If you clear the field, the chat keeps its old name. A name that contains HTML isn’t saved: you see Couldn’t rename this chat and the old name stays.
• The new name shows in the header and in the history on both the Home page and the floating toolbar. The assistant doesn’t replace it with a generated title when you send more messages.
• A rename counts as activity, so after you reload the page the renamed chat is listed with your most recent chats.
• You can only rename your own chats.

​

See the assistant’s reasoning

On the web, the Cal.com assistant sometimes writes short progress updates while it works on a request, for example “Looking through your upcoming bookings for tomorrow afternoon.” These updates appear in a collapsed Reasoning row where they were written in the reply, so the reply itself stays the answer. Select Reasoning to read the updates, and select it again to close them.

• Updates written one after another share one Reasoning row. A reply without updates has no row.
• An update appears once it’s finished. While the assistant is still writing, you see Thinking… instead.
• The sentence that introduces an approval card stays part of the reply, above the card, not under Reasoning.
• The Reasoning row only appears in the conversation as it happens. When you reopen a chat from your history, the replies show without it.

In Slack, when a reply has progress updates, the assistant posts a Why? button under it. Select Why? to open the updates in a Reasoning window, and select Done or Close to close it.

• Only the person who asked can open the window. Anyone else who selects Why? sees “Only the person who asked can see this reasoning.” and nothing opens.
• The button works for 24 hours. After that, selecting it shows “That reasoning is no longer available.”
• A reply without progress updates, or one that ran into an error, has no Why? button. The sentence that introduces an approval card isn’t included, as it’s already in the reply.

In Telegram and iMessage, the assistant posts only its reply, without the progress updates.

​

iMessage RSVPs from a linked phone number

When a Cal Event offers Register with iMessage, a guest can RSVP by texting from their phone instead of filling in the form. If the guest’s phone number is linked to a Cal.com account through the Cal.com assistant on iMessage, an RSVP made while signed out of Cal.com is saved to that account, the same as an RSVP made while signed in. It shows on the event page when they sign in.

To link a number, message the Cal.com assistant on iMessage, open the link it replies with, and select Connect account while signed in to Cal.com.

If the RSVP is started from the event page while signed in, it’s saved to the signed-in account, even when the phone number is linked to a different account. An RSVP from a number that no account has linked or verified on its profile stays anonymous. A number verified on a profile takes priority over an iMessage link.

​

Booking messages in Slack, Telegram and iMessage

When you link Slack, Telegram or iMessage to your Cal.com account through the Cal.com assistant, booking notifications arrive there as direct messages. You can get a message for every booking notification on the Notifications settings page:

• Bookings: booking requested, booking request reminder, booking confirmed, booking rejected, booking rescheduled, reschedule requested, booking cancelled, booking location changed and booking reassigned to you
• Attendees & seats: attendee added, guests added and attendee cancelled their seat
• Payments: payment received
• Booking proposals: booking proposal received
• Cal Video: recording ready and transcript ready
• Cal Events: new registration, including guests who join the waitlist, and registration pending approval

Each event has its own Agent toggle there, separate from Email, so turning off an event’s email doesn’t stop its messages. Agent and In-App are on by default for every event.

Booking proposal and Cal Event registration messages go to the event’s hosts. They say who proposed times or registered, for example “Sam Lee proposed times for Intro call” or “Sam Lee joined the waitlist for Product meetup”, and have no meeting time. A proposal message links to the page where you review the proposed times, and a registration message links to the Cal Event’s Guests tab.

Booking messages list the attendees’ email addresses on an Email: line (Emails: when there are several), so you can contact them without opening the booking.

The reminder sent one minute before a meeting starts doesn’t include email addresses. Seated events that hide attendees from each other don’t show attendee names or email addresses.

​

Confirm or decline a booking request in Slack

If you’re a host, a Slack DM for a pending booking request includes Confirm and Decline alongside View booking, unless the event has seats.

• Select Confirm to accept the request immediately.
• Select Decline to open a dialog where you can enter an optional reason, then submit it to decline the request.

After a successful decision, the message replaces the decision buttons with Confirmed by you or Declined by you, and keeps View booking. For a recurring booking request, either action applies to every occurrence in the series still waiting for confirmation.

These buttons are only available in Slack, not Telegram or iMessage. To decline a request with a payment, use the Bookings page.

​

Pick a meeting length when the assistant books

When a personal or team booking link offers several durations, the Cal.com assistant can book any of them. Ask for the one you want, for example “book the 60-minute version of Sam’s intro call”. The assistant checks times for that length, and the approval card shows the duration it will book. If you don’t say which length you want, the assistant asks before looking for times.

The assistant only books lengths the link offers. A length the link doesn’t list, or any other length on a link with one duration, is refused before approval, and the assistant tells you which lengths the link offers. If the length changes after you approve, the approval no longer applies and the assistant asks again.

​

Answer booking questions and give your phone number when the assistant books

When a personal or team booking link has booking questions, the Cal.com assistant asks you the required ones before it shows the approval card. Optional questions, such as Additional notes or a Company question, can be left blank, as on the booking page: the assistant never asks them, and answers one only when you’ve already said what belongs in it, for example “book Sam’s intro call tomorrow at 10, I’m from Acme”. The approval card shows each answer, such as Company: Acme.

You can also give your own phone number when you ask for a booking, for example “my number is [phone]”, on any booking link, including a group meeting. When the link texts reminders to attendees, because it has an SMS reminder number question or a workflow that sends SMS or WhatsApp messages to attendees, the assistant asks for your number before it shows the approval card if you haven’t given it. Your number is saved as the attendee phone number on the booking and receives the link’s text reminders. The approval card shows it as Phone number.

The assistant never guesses an answer or a phone number, or reuses a number you didn’t give for this booking. A phone number the booking page wouldn’t accept is refused before approval. Group meetings take a phone number but no answers to booking questions.

​

Book a teammate who has no booking link

When you ask the Cal.com assistant to meet a teammate who has no booking links of their own, for example “book 30 minutes with Sam on Thursday when we’re both free”, it books the two of you as a dynamic group meeting, the same way your own you+sam group link would. The assistant checks when you’re both free, and the approval card reads Book a meeting for you and Sam? with Hosts: you and Sam. After you approve, one meeting is booked with both of you as hosts.

You can also check when a larger group is free and book them all into one meeting, for example “when are Sam, Priya, Ben and Dana all free for 30 minutes on Tuesday?”. A group meeting can have up to 20 hosts, and when you’re one of them, you count toward the 20. When there are more than five other hosts, the approval card names the first five and counts the rest, for example Hosts: you and Sam, Priya, Ben, Dana, Lee and 2 more.

This needs Dynamic group links turned on in your general settings. If it’s off, or your account is locked, the assistant tells you that you can’t be booked on a group link yourself, without showing an approval card. Your teammate must also be bookable on group links. If the group can’t be booked, the assistant looks for team booking links your teammate is part of instead.

​

Where the meeting is, after the assistant books it

When the Cal.com assistant books a meeting for you, its reply says where the meeting takes place, for a confirmed booking or one waiting for the host’s confirmation:

• A video app’s name, such as Cal Video or Zoom
• Online meeting for a fixed meeting link, or a video app it can’t name
• Phone call for any phone location. Phone numbers aren’t shown.
• The address or place, for an in-person meeting

For a confirmed booking, the reply also gives the join link when the booking alone determines it: the booking’s Cal Video room, or a fixed meeting link set on the event type. For other video apps, such as Zoom, Google Meet and Microsoft Teams, the reply names the app and says the join link is in the confirmation email. For a booking waiting for the host’s confirmation, the reply says the link comes when the host confirms.

A fixed meeting link that contains a username or password isn’t shared in the reply. For a recurring booking, the reply gives the first meeting’s location and link.

​

Get add-to-calendar links through the assistant

You can ask the Cal.com assistant for links to add one of your bookings to a calendar, for example “give me a Google Calendar link for my 3pm tomorrow”. The assistant returns links for Google Calendar, Outlook, Office 365 and an ICS file. If you name a calendar, it gives you that link; otherwise it gives all four.

• If more than one booking matches what you asked for, the assistant asks which one you mean.
• The links carry the same location and meeting link the assistant would show you for that booking.
• The assistant only gives you the links. It doesn’t email them, add the event to a calendar for you or change the booking.

This works for bookings you can see. A booking you can’t see is answered as if it doesn’t exist, and no links are returned.

​

Check conferencing apps through the assistant

You can ask the Cal.com assistant which video conferencing apps are connected to your account, for example “which video apps do I have, and which one is my default?”. The assistant lists your apps, such as Zoom, Google Meet and Cal Video, says which one is your default and whether any app needs reconnecting. If you never chose a default, Cal Video is your default.

In an organization, you can also ask about the apps your organization or one of its teams installed, for example “which conferencing apps does the Sales team have?”. The assistant lists that team’s or organization’s installed apps and its default app. Apps that members connected to their own accounts aren’t included, and Cal Video isn’t listed for a team because it needs no install.

The assistant never shares meeting links or credentials.

Checking a team’s or organization’s apps needs permission to view the team’s conferencing settings. With that permission on your organization, you can check any of its teams, including ones you haven’t joined. A team you can’t view, or one outside your organization, is answered the same way as one that doesn’t exist.

​

Change your default conferencing app through the assistant

You can ask the Cal.com assistant to make one of your connected video apps your default instead of opening Settings → Conferencing, for example “make Zoom my default video app”. The approval card reads Change your default conferencing app? and names the app, for example App: Zoom Video. Choose Set as default to save it, or Keep current default to leave it as it is.

Some apps, such as FaceTime and Whereby, use one fixed meeting link of your own. For these, the assistant asks for your link before it shows the approval card, and the card shows it, for example Link: https://whereby.com/your-room.

After the change, booking links that use your default app or have no location, and new booking links, use the new app. Booking links with their own location keep it.

The assistant can only make an app your default if it’s already connected to your account. If it isn’t, the assistant says so and points you to Settings → Conferencing to connect it. A fixed meeting link must match that app’s link format, the same check as on the settings page, or nothing is saved. The assistant can’t change a team’s or another member’s default, or connect, reconnect or remove apps.

​

Change a booking’s length when the assistant moves it

When you ask the Cal.com assistant to move a booking to a new time, you can change its length in the same request, for example “move my call with Dana to Thursday 3pm and make it 60 minutes”. The new length must be one of the durations the booking’s event type offers. If you don’t ask for a different length, the assistant doesn’t change it.

The approval card shows the new length, for example Length: 60 minutes, and its check for overlaps and working hours covers the whole new time.

This also works when you move several bookings in one request, for example “move all my Thursday calls to Friday and make them 15 minutes”. Each booking can get its own length, and the approval card lists the new length under each booking it changes, for example Intro call: 15 minutes. If a booking’s event type doesn’t offer the length you asked for, that booking isn’t moved and the assistant tells you why, while the other bookings still move.

A booking’s length can’t be changed when its event type offers only one duration, or when it’s a seated event. The assistant tells you instead of moving the booking.

​

Move one attendee’s seat or book over conflicts

When you ask the Cal.com assistant to move bookings, you can ask it to move only one attendee’s seat on a seated event, or to book over conflicts at the new time. Both work when you move one booking or several bookings in one request, and each booking gets its own options, for example “move just Priya’s seat on Friday’s workshop to Monday 10am, and move tomorrow’s meetings to Friday morning even if they overlap”. This works the same way as seatUid and allowConflicts on POST /v2/bookings/{bookingUid}/reschedule, called once per booking.

• One attendee’s seat: the organizer, a host or a team admin can move a single seat. Only that attendee moves to the new time, and everyone else stays on the original session. The approval card names whose seat moves, for example Workshop: moves only Priya’s seat; everyone else stays at the current time.
• Book over conflicts: the move skips the availability check, so it can land on a time that’s already busy. This applies when you’re the owner, a host or an admin of the booking’s event type. Otherwise the card says conflicts are still checked, and the booking moves only if the new time is free. The card says per booking whether it books over conflicts.

When you move several bookings, a seat that can’t be moved or a conflict override that doesn’t apply affects only that booking. The other bookings still move, and the assistant tells you which ones didn’t and why.

Attendees can’t move another attendee’s seat, and a seat can only be named on a seated event. If the seat now belongs to someone other than the attendee you named, that booking isn’t moved.

​

Mark or clear no-shows through the assistant

You can ask the Cal.com assistant to mark the host or attendees of a booking as no-shows, or to clear a no-show you marked by mistake, for example “mark Sam as a no-show for this morning’s demo” or “I marked Sam as a no-show by mistake, undo that”. Here, the host means the booking’s organizer. One request can mark some people and clear others, for up to 50 attendees of a booking. The assistant works the same way as POST /v2/bookings/{bookingUid}/mark-absent, with absent: false for an attendee or host: false to clear.

Before saving, the approval card names the booking and its time, and lists who will be marked absent and whose absence will be cleared, such as Clear absence for 1 selected attendee: Sam ([e-mail]). Clearing a no-show runs the same no-show workflows and webhooks as marking one, and the card says so.

No-shows can only be marked or cleared after the booking has started, and for one occurrence of a recurring booking at a time. To change the rest of the series, use the Bookings page. Attendance for Cal Event attendees is managed on the event page.

​

Invite guests when the assistant books

When the Cal.com assistant books a meeting on a personal or team booking link, or as a group meeting, you can invite other people in the same request, for example “book Sam’s intro call on Thursday at 2pm and invite [e-mail] and [e-mail]”. The assistant invites each guest by the email address you give, the same as guests on POST /v2/bookings. It never guesses an email from a name.

The approval card lists the guests, for example Guests: [e-mail], [e-mail]. After you approve, the booking is created with them as guests. If the guests change after you approve, the assistant asks for approval again.

A booking can invite up to 100 guests. An email listed twice, in any letter case, is invited once. An email that isn’t valid or can’t receive email is refused before approval, with the same check the booking page uses. Seated events don’t take guests. To add guests to a booking that already exists, see Add guests to a booking through the assistant.

​

Add guests to a booking through the assistant

You can ask the Cal.com assistant to add guests to one of your bookings, for example “add Marco Rossi ([e-mail]) to my 3pm call. He’s in Rome, so send his invite in Italian.” For each guest you give an email address and, optionally, their name, time zone and language. The guest’s name, time zone and language are saved with the booking and used for their invite. If you don’t give a time zone or language, the guest gets the organizer’s.

The approval card lists each guest by name and email, with the time zone and invite language you asked for. After you approve, the guests are added. Adding them may update calendars and send them notifications, and guests already on the booking are skipped. If a guest’s details change after you approve, the assistant asks for approval again.

A request can add up to 100 guests to one booking. Names must be plain text of up to 255 characters, without markup. An unknown time zone or an unsupported language is refused before approval. For a recurring booking, guests are added only to the occurrence you name, not the rest of the series. Guests can’t be added this way to a seated event, a Cal Event, or a booking that has ended or isn’t accepted or waiting for confirmation.

​

Accept a recurring booking request through the assistant

When a booking request that needs your confirmation is part of a recurring series, you can ask the Cal.com assistant to accept the whole series, for example “accept Dana’s weekly coaching request, the whole series”. The assistant accepts every occurrence of the series that is still waiting for confirmation, the same way POST /v2/bookings/{bookingUid}/confirm does, and tells you how many occurrences it accepted.

If you ask to accept only one occurrence, the assistant accepts that one and tells you the series’ other occurrences are still waiting for confirmation. If you don’t say which you mean, it asks.

When you ask the assistant to accept several requests at once, it accepts each recurring series separately from the other requests. To decline a whole series, use the Bookings page.

​

Ask why a booking was cancelled or moved

You can ask the Cal.com assistant about a booking’s history, for example “why did Bob cancel tomorrow’s demo?”, “where did the 10am move to?”, “how did they rate it?”, “was I marked a no-show?” or “when did Sam book this?”. When it reads a booking, the assistant gets the same history details that GET /v2/bookings/{bookingUid} returns:

• Cancellation and rescheduling reasons: the reason given by whoever cancelled or rescheduled, which the assistant quotes as their own words. A rescheduling reason is stored on the new booking, so when you name the old one, the assistant first follows it to the booking it moved to. If no reason was given, the assistant says so instead of guessing one.
• Rescheduled from and to: the booking this one was moved from, and the booking it was moved to.
• No-show: whether the host was marked as a no-show.
• Rating: the attendee’s rating.
• Timestamps: when the booking was made, shown in your time zone, and when it last changed.

Reasons and the rating are only shown when you can change the booking, the same as the booker’s additional notes. Otherwise the assistant tells you that you can’t see them. Reasons have markup removed and are cut to 500 characters. The assistant only opens the booking something was moved from or to if you can see that booking too, and it never shares the email address of whoever cancelled or rescheduled.

​

Ask about booking numbers through the assistant

You can ask the Cal.com assistant for booking numbers over a date range, for yourself, a team or your organization, as the Insights page counts them, for example “how many bookings did Alex on the Sales team have last month?” or “what was our CSAT in September for paid bookings?”. The assistant reports:

• Totals: total, scheduled, completed, cancelled and rescheduled bookings, and host and guest no-shows. Scheduled counts every accepted booking in the range, past or future, except rescheduled ones, and includes completed bookings.
• Ratings: the number of ratings, the average rating and CSAT, the share of ratings above 3 as a percentage.
• Previous period: the same numbers for the same number of days just before the range, so you can ask whether they went up or down.

You can narrow the numbers to:

• One member of a team or your organization, instead of the whole team.
• Event types, for example “how many 30 minute meetings?”.
• Paid or unpaid bookings.
• A rating range from 1 to 5, for example “bookings rated 4 or higher”.

Team and organization numbers, including one member’s, need the View team insights permission on that team or organization, and the member must have accepted their invitation to it. Otherwise the assistant tells you it couldn’t find insights you can access, instead of reporting zeros. A member’s numbers are totals for the range only, not a trend over time.

​

Rank team members through the assistant

You can ask the Cal.com assistant to rank the members of a team or your organization over a date range, as the Insights page does, for example “who on the Sales team had the most no-shows last month?”, “who completed the fewest meetings in Q3?” or “which rep has the best ratings?”. It lists up to ten members, ranked by:

• Bookings they host, most or fewest first.
• Cancelled bookings, most first.
• Completed bookings, most or fewest first.
• Host no-shows, most first.
• Average rating, highest or lowest first.

You can also narrow the ranking to event types, for example “who took the most Discovery Calls?”.

Ranking members needs the View team insights permission on that team or organization. Otherwise the assistant tells you it couldn’t find insights you can access. Members with none of the counted bookings in the range aren’t listed, and a count smaller than 5 is shown as “fewer than 5”. The rating ranking leaves out members with fewer than 5 ratings, so it can list fewer than ten members, or nobody. Cancellations and no-shows can’t be ranked fewest first.

​

Check busy times on a specific calendar through the assistant

When you ask the Cal.com assistant when you’re busy, it reads your Cal.com bookings, your out of office days and the connected calendars checked for conflicts in Settings → Calendars. You can also ask about specific connected calendars, including ones that aren’t checked for conflicts, for example “is my personal Google calendar busy Thursday afternoon? It isn’t checked for conflicts”. The assistant then reads those calendars instead of the ones checked for conflicts, along with your Cal.com bookings and out of office days.

This is a one-off read. It doesn’t change which calendars are checked for conflicts, so the calendar still doesn’t block times on your booking links until you check it in Settings → Calendars. The assistant can read up to 10 calendars and up to 31 days at a time. Calendars connected through a delegation credential can’t be read this way. Busy times never include what fills them, such as event titles or attendees.

​

Find routing forms through the assistant

You can ask the Cal.com assistant about a routing form by its name, for example “what does the Sales intake form do?”, without saying which team it belongs to. The assistant looks through your personal routing forms and the forms of every team where you have permission to view routing forms. You can still name a team to list only that team’s forms.

A form on a team where you can’t view routing forms isn’t listed, even if you created it.

If you belong to an organization, you can also ask for every routing form in it, for example “list all routing forms in my organization”. The assistant lists the forms of every team in your organization, including teams you haven’t joined, grouped team by team with each team’s name. Personal forms aren’t included. You can narrow the list to some of the organization’s teams, up to 50 at a time, or ask for the most recently created or changed forms across the whole organization.

Listing your organization’s routing forms needs the View organization routing forms permission on your organization. Without it, the assistant finds no forms. Opening one of these forms to see what it does still needs permission to view routing forms on its team.

​

Read routing form change history through the assistant

You can ask the Cal.com assistant who changed a routing form and what they changed, for example “who last changed the Sales intake form?” or “what changed on it last week?”. The assistant reads the history newest first, including when each change happened, who made it when a name is available, and before and after values for questions, routes, route conditions and settings.

This is only available to organization members with permission to read routing form audit logs on the form’s team or across the organization. If the history isn’t available to you, the assistant says so and suggests asking an organization admin for access.

​

Check routing form times through the assistant

You can ask the Cal.com assistant which times a booker would be offered after answering one of your team’s routing forms, for example “what times would someone who picks Enterprise on our Sales form get next week?”. The assistant runs the answers through the form’s routes without saving a response, and lists the open times for the event type they reach, in your time zone.

This works on any team routing form you have permission to view, whether or not the team belongs to an organization. A form you can’t view is answered the same way as one that doesn’t exist.

When you check times for rescheduling a booking, the booking’s current time stays open. If the booking’s event type is round robin and lets the booker choose a host when rescheduling, you can ask for the original host’s times only, or for any available host.

Personal routing forms aren’t supported. A route that ends in a custom message or an external URL has no times to show.

​

Draft a routing form through the assistant

You can ask the Cal.com assistant to draft a new routing form, describing its questions and where each answer should go. Nothing is saved while it drafts: the assistant reads the form back to you and shows an approval card with what the form does and any warnings, and the form is created only when you approve. A draft expires after an hour, and the assistant creates new forms only. To change a form you already have, use the routing form editor.

In a team that belongs to an organization, a route to a round-robin team event type can also narrow which hosts get the booking by your organization’s member attributes, for example “send EMEA leads to the Sales round robin, but only to reps whose Region is EMEA”. You can add a fallback filter for when no host matches, such as “otherwise, reps whose Region is Global”.

Drafting a team form needs permission to view the team’s routing forms or event types. If a member filter matches nobody on the team today, the assistant warns you before you save that bookings on that route go to every host. On a team outside an organization, member filters aren’t available: the draft is created without them, and the assistant tells you that route reaches every host. Routing to the CRM contact owner is set up in the routing form editor.

​

Find who holds an attribute through the assistant

In an organization, you can ask the Cal.com assistant which members hold an attribute option, for example “who is in Region EMEA?” or “who on the Sales team is in Region EMEA?”. The assistant looks up the attribute, then lists each matching option with the name and username of the members who hold it.

• You can narrow the answer to some of the attribute’s options, or to members of one or more teams in your organization.
• Only accepted members of the organization are listed. Pending invitees aren’t included.
• The assistant reads members in pages of up to 100, ordered by name, and tells you how many members hold a matching option in total. It fetches the next page when there are more.

This needs permission to read your organization’s attributes, even for attributes you hold yourself. To narrow the answer to a private team, you also need permission to see that team’s members. An attribute you can’t read, from another organization or with a team outside your organization is answered as if it doesn’t exist. Attributes whose value is another member of your organization can’t be listed this way.

​

Ask who someone is

You can ask the Cal.com assistant who someone is, such as a person who booked you or a name you mention, for example “who is Ugo?”. The assistant looks the person up in your own past, upcoming and unconfirmed bookings, searches the public web for their professional background, and answers with both:

• Their likely role or company, with links to the pages it used.
• Your history with them: how many past meetings you’ve had, the date and title of the latest one, the next upcoming one, and the booker’s notes from the latest past booking when you can see them.

If several different attendees match the name, the assistant asks which person you mean before searching the web. If your bookings can’t all be checked, it says “at least” for the number of meetings rather than an exact count.

To ask about someone who booked you without typing the question, go to Bookings, select an attendee’s name and choose Who? Whooo?. On a wide screen, the assistant opens a new chat and sends Who is <name>? straight away. On a narrow screen, such as a phone, you’re taken to the Home page with the question already in the chat box, ready for you to send.

The web search uses the person’s name, their email address when you typed it or it’s on one of your bookings, and a company, role, city or business email domain that narrows who they are. Results may be about someone else with the same name. The assistant only looks for professional background, never home addresses, phone numbers, family or health details. You can run up to 20 lookups an hour; after that, try again later. When public web search isn’t turned on for your Cal.com instance, the assistant answers from your booking history only and says so.

​

Ask about your own profile settings

You can ask the Cal.com assistant about your own account settings, for example “what does my bio say?” or “how many bookings a day do I allow?”. The assistant can read your name, username, bio, dashboard and booking-page themes, time zone, 12- or 24-hour clock, the day your week starts, your language, your default availability schedule, the ID of the organization you belong to, and your booking limits per day, week, month and year.

Booking limits are an organization feature, so the assistant only reads them for organization members. Outside an organization, it tells you they can’t be set rather than saying you have no limits. Booking limits on individual event types and team event types aren’t read here. The assistant never reads your email address, avatar, password, two-factor settings or billing.

​

Manage travel schedules through the assistant

You can ask the Cal.com assistant to list, create or remove your own travel time-zone schedules:

• List: “What travel schedules do I have?” shows your scheduled destinations and dates, including permanent moves.
• Create: “I’ll be in Tokyo from November 10 to November 20 next year” schedules a trip. Give a destination and start date without an end date for a permanent move.
• Remove: “Cancel my Tokyo travel schedule” removes the matching schedule. To change a schedule, remove it and add a new one.

The assistant asks for approval before creating or removing a schedule. Dates are interpreted in your current profile time zone, and the end date is inclusive. The start date can’t be in the past, the end date can’t be before the start, and schedules can’t overlap, including a permanent move that starts before an existing future trip. You can’t manage someone else’s travel schedules.

Removing an already-active travel schedule doesn’t restore your previous time zone. Ask the assistant to change your current time zone separately if needed.

​

Manage notification preferences through the assistant

You can ask the Cal.com assistant to show or change your booking notification preferences, the same ones on the Notifications settings page. For example, “turn off emails for cancelled bookings” or “stop sending booking notifications to Telegram”.

The assistant can change:

• Email, In-App and Agent for each booking notification event. Agent controls whether that event reaches your connected chats.
• The Slack, Telegram and iMessage toggles for each chat you’ve connected.

Before saving, the assistant lists each setting it will change with its current and new value, and waits for you to approve. After saving, it reports the preferences as they were stored.

The assistant doesn’t change anything when you change In-App without the Cal.com mobile app connected, when you change Agent without a connected chat, or when you change a chat you haven’t connected. Browser notifications are set per browser, so change them on the settings page.

​

Change your bio and booking limits through the assistant

You can ask the Cal.com assistant to change your own profile settings instead of opening Settings → My Account → General, for example “update my bio to …” or “don’t let anyone book me more than 4 times a day”. Along with your name, time zone, clock, week start and language, the assistant can change:

• Bio: the assistant replaces your whole bio with the new text, or clears it. Your bio is public on your booking page.
• Booking limits: the most bookings you accept per day, week, month and year across all your event types. Each limit is a whole number of at least 1. You can set or change one limit and keep the others, remove one limit, or remove them all.

Before saving, the assistant shows an approval card with each setting it will change, its current value and the new one, for example Limit booking frequency — Per day: none → 4, and waits for you to approve. If everything you asked for is already set, nothing is saved.

Booking limits can only be changed through the assistant if you belong to an organization. A shorter period’s limit can’t be higher than a longer one’s, for example a per-day limit above your per-week limit, and such a change is refused without saving anything. A new bio goes through the same checks as on the General settings page. Your email address, username, password, avatar and billing can’t be changed through the assistant.

​

Change your dashboard and booking-page themes through the assistant

You can ask the Cal.com assistant to change your dashboard or public booking-page theme, for example “switch my dashboard to dark mode” or “make my booking page follow the system theme”. Each can be light, dark or system, independently. System follows your device’s appearance for the dashboard and the visitor’s device for booking pages.

Before saving, the assistant shows an approval card with each theme’s current and new value and waits for you to approve. If the requested theme is already set, nothing changes. Reload the page after approving a dashboard theme change to see it.

​

Create a workflow through the assistant

You can ask the Cal.com assistant to create a workflow for your event types instead of building it on the Workflows page, for example “email my attendees a thank-you 1 hour after the meeting”, “email me when someone books” or “email [e-mail] on every new booking”. You choose:

• What starts it: before or after the event, a new booking, a cancellation, a reschedule, a booking that’s requested, rejected, paid or has a payment started, a no-show update, or a host or guest no-show on Cal Video
• How long before or after it runs, in minutes, hours or days, up to 365 days. A workflow that runs before the event defaults to 24 hours before. Triggers such as a new booking or a cancellation run straight away
• Up to 10 steps, in order, each one an email to the host, the attendees or an email address, or an SMS or WhatsApp message to the attendees or a phone number
• What each step sends: the standard reminder, a rating request, or the completed, cancelled or rescheduled template, or your own message. An email with your own message needs a subject. WhatsApp always sends a fixed template
• For each step, whether an email attaches the calendar invite, whether a text to attendees makes the phone number required, a sender name or SMS sender ID, whether an email to attendees skips attendees marked as no-shows, and, in an organization, whether the message is translated into each attendee’s language
• The event types it runs on: the ones you name, or all of them, including ones you create later. A workflow on no event types sends nothing until you turn it on for some

Before creating it, the assistant shows an approval card with when it runs, for example Runs: 1 hour after event ends, and each step’s recipient, subject and the start of its message, and waits for you to approve. After creating it, it reports the workflow’s trigger, timing, steps and the event types it’s on.

The assistant follows the same rules as the workflow editor. It refuses a workflow, without showing a card, when a step would send to an email address or phone number that isn’t verified in Cal.com, or use an email with your own text on the free plan. Steps that text attendees add a phone number field to the workflow’s booking links and can use SMS credits.

The assistant can create your own workflows and workflows for a team where you have permission to create and edit workflows. An organization admin can also create one for a team in their organization they haven’t joined. Workflows with path, filter, delay or Cal.ai phone call steps, and routing form workflows, are created in Cal.com, and the assistant links you to the Workflows page.

​

Change a workflow through the assistant

You can ask the Cal.com assistant to change one of your existing workflows instead of opening the workflow editor, for example “send my reminder 1 hour before instead of 24”, “change the reminder text to …” or “also email the host”. The assistant can change:

• The workflow’s name
• Its trigger, such as before the event, after the event, a new booking or a cancellation
• How long before or after the event it runs, up to 365 days, for a workflow that runs before or after the event
• Its steps: add an email or text step, change a step’s recipient, subject or message, switch a step to another email or text action, or remove a step

Before saving, the assistant shows an approval card with each change before and after, for example Runs: 24 hours before event starts → 1 hour before event starts, and waits for you to approve. After saving, it reports the workflow’s trigger, timing and steps as they were saved.

You can also ask what a step sends, for example “what does my reminder email say?”. The assistant quotes the step’s current message, and an email’s subject, with variables such as {EVENT_NAME} left as they are. This works for email, text and WhatsApp steps. A step with no text of its own sends the template’s standard text, and the assistant says so.

A new message replaces the whole current one. When you ask to change part of it, for example “make the text friendlier” or “add the meeting link”, the assistant starts from the current message and keeps the rest of it and its variables as they are. It doesn’t add wording you didn’t ask for, and asks you for the text if you ask for a change without saying what it should be. A message can be up to 5,000 characters; if the change would make it longer, the assistant links you to the workflow to edit it there instead of shortening it. A new step without a message sends the standard reminder. To switch a step between email and text, the assistant removes it and adds a new one in the same change.

The assistant follows the same rules as the workflow editor. It refuses a change, without showing a card, when it would send to an email address or phone number that isn’t verified in Cal.com, use custom message text on the free plan, or set a timing on a trigger that doesn’t run before or after the event. Steps that text attendees add a phone number field to the workflow’s booking links and can use SMS credits.

The assistant can change your own workflows and team workflows you have permission to edit, when they run on event types. Organization workflows, routing form workflows and workflows with Cal.ai phone call, path or filter steps are changed in Cal.com, and the assistant links you there. WhatsApp, delay and lead enrichment steps can only be removed. The assistant can’t reorder steps or change sender names.

​

Delete a workflow through the assistant

You can ask the Cal.com assistant to delete a workflow you no longer need, for example “delete my thank-you workflow”. If more than one workflow matches the name you give, the assistant asks which one you mean.

Before deleting it, the assistant shows an approval card, Delete this workflow?, that names the workflow, says its scheduled reminders are cancelled and that this can’t be undone, and waits for you to approve. When the workflow has Cal.ai phone call steps, the card also says its Cal.ai phone agents and their numbers are removed. If you choose Keep workflow, nothing is deleted.

Deleting through the assistant works the same way as deleting on the Workflows page: reminders already scheduled for upcoming bookings are cancelled, and the phone number fields the workflow added to your booking links are removed.

The assistant can delete your own workflows and team workflows you have permission to delete. For any other workflow, it says it couldn’t find one you can delete.

​

Change booking questions through the assistant

You can ask the Cal.com assistant to add, edit, remove or reorder the questions bookers answer on an event type you can edit, for example “add a required Work email question that only accepts acme.com”, “rename Additional notes to ‘What would you like to discuss?’”, “ask for first and last name separately” or “move Company above notes”. The assistant accepts the same booking-question settings as PATCH /v2/event-types/{eventTypeId}/booking-fields:

• Any question: label, placeholder, required, hidden, and whether a prefilled answer is locked so the booker can’t change it. A question can’t be both required and hidden.
• Email questions: domains or addresses that can’t book, or the only ones that can, such as acme.com. A new list replaces the old one.
• Long text questions: a minimum and maximum number of characters, from 0 to 1000.
• Select, multiselect, radio and checkbox questions: their options. A new list replaces the old one.
• Name: one full-name field, or first and last name asked separately, with their own labels and placeholders. First name is always required; last name can be optional.
• Order: a new order for all of the event type’s questions.

Built-in questions, such as name, email, location and additional notes, can be relabelled and take only the settings the API accepts for each of them. They can’t be removed, and location only takes a new label. Questions a workflow adds, such as the phone number for text reminders, can’t be changed and keep their place in the order.

Before saving, the approval card names each question and each change, including label changes, email rules and the split-name labels, and waits for you to approve.

​

Change an event type’s CRM app or calendar invite text through the assistant

You can ask the Cal.com assistant to turn HubSpot or Salesforce on or off for an event type you can edit, or to change the description on the calendar invites its hosts and guests receive, for example “turn on HubSpot for my Discovery Call and don’t create contacts” or “change the guest invite description to ‘Meeting with {ATTENDEE}’”. The assistant makes the same changes as crm and calendarInvites on PATCH /v2/event-types/{eventTypeId}:

• HubSpot and Salesforce: turn the app on or off for the event type, and choose whether it leaves guests added to a booking out of the CRM and whether it skips creating a contact for the booker. Those two options need the app to be on already, or turned on in the same request. The assistant only turns an app on when you ask it to.
• Calendar invite descriptions: for the host invite, the guest invite or both, use your organization’s default, Cal.com’s standard description, or your own text of up to 5000 characters with template variables such as {ATTENDEE} and {ORGANIZER_NAME}. Markup that could run as code is removed before it’s saved, and the card shows the text as it will be saved.

Before saving, the approval card, Change this booking link?, lists each change, such as HubSpot: on, HubSpot skips creating the booker’s contact: on or Guest calendar invite description: Meeting with {ATTENDEE}, and waits for you to approve.

You can also ask what’s set now, for example “is HubSpot on for my Discovery Call?” or “what does the guest calendar invite say?”. For an event type you can open, the assistant tells you whether HubSpot and Salesforce are on and how their two options are set, and for the host and guest invites, whether each uses your organization’s default, Cal.com’s standard description or your own text, and what that text says.

You can also set both when you ask the assistant to create a personal or team event type, for example “create a ‘Demo’ event type with HubSpot on and a guest invite that says ‘Kickoff with {ATTENDEE}’”, the same way as crm and calendarInvites on POST /v2/event-types and POST /v2/teams/{teamId}/event-types. The Create this booking link? card lists them with the event type’s other settings, and you approve everything at once.

The app must already be installed for the event type’s owner: you for your own event types, or the team or its organization for a team event type. Otherwise the assistant tells you it isn’t installed, and nothing changes: when you’re creating an event type, it isn’t created. Other CRM apps, and HubSpot’s and Salesforce’s other options, are set in the event type’s Apps tab. A member’s copy of a managed event type uses its team’s invite text, which is changed on the team’s event type.

​

Switch a team event type between collective and round robin through the assistant

You can ask the Cal.com assistant to switch a team event type you can edit from collective, where every host is on every booking, to round robin, where each booking goes to one host, or back again, for example “switch our Sales Demo from collective to round robin, with Sam as a mandatory host”. The assistant makes the same change as schedulingType on PATCH /v2/teams/{teamId}/event-types/{eventTypeId}:

• Hosts: a switch needs the hosts for the new type in the same request: every team member, or the members you name. Without them, the assistant doesn’t switch the event type.
• To round robin: a host is mandatory only if you say so.
• To collective: every host is mandatory, and host priority, weight, host groups and round-robin settings can’t be set.

The approval card shows the switch, such as Scheduling: Collective → Round robin, then the hosts as they’ll be after the switch, and waits for you to approve.

Managed event types, and members’ copies of them, can’t be switched: create a new team event type and delete the old one instead. Personal event types can’t be collective or round robin.

​

Create a managed event type through the assistant

You can ask the Cal.com assistant to create a managed event type for a team, where each assigned member gets their own copy on their booking page, for example “create a 30-minute managed Customer check-in for Sales, for Ana and Ben” or “for everyone on Sales”. The assistant creates it the same way as schedulingType: managed on POST /v2/teams/{teamId}/event-types, with one of:

• Selected members: only the members you name get a copy. Name only members who have accepted the team invitation: if one of them hasn’t, nothing is created.
• All team members: every member of the team gets a copy, including people who join later.

The approval card says Each assigned member gets their own copy, live on their booking page, names the members who get one, such as Managed members added: Ana, Ben, and waits for you to approve. The managed event type starts with the same locked fields as one created on the Event Types page. Each copy is live on its member’s booking page as soon as it’s created, so the assistant doesn’t give a booking link for the managed event type itself.

Creating a team event type needs permission to create event types on that team. A managed event type has no hosts, and the assistant can’t create one with seats, recurring bookings, several durations or booking confirmation. It tells you before showing the card, and you can set those in the event type’s settings in Cal.com.

​

Give several event types the same description through the assistant

You can ask the Cal.com assistant to set one description on several event types at once, for example “change the description of all my event types to ‘hello’”. The assistant changes them in one request, the same way it changes other settings that mean the same on every event type, such as length or minimum notice.

Instead of one approval card per event type, you get a single card, Change these booking links?, with the new description, such as Description: hello, and the name of each event type it changes. Select Change 3 booking links (with your number) to update them all.

One request can change up to 20 event types you can edit. Markup that could run as code is removed from the description before it’s saved, and the card shows the description as it will be saved. Titles, links, locations and hosts are still changed one event type at a time.

​

Write a description with the assistant

On the web, description editors have a sparkle button, Write with Agent, at the right end of their toolbar. It asks the Cal.com assistant to write the description for you without leaving the page. You’ll find it on:

• An event type’s description, under Basics
• A Cal Event’s description
• About in Settings → My Account → Profile
• About on a team’s or organization’s profile settings

1. Select the sparkle button

   The assistant panel opens a new chat and sends the request for you. If the field has text, the request is “Rewrite my description and make it more descriptive:” followed by your text. If the field is empty, it’s “Write a description for” followed by the name of the event type, Cal Event, person or team.

2. Review the draft

   The assistant replies with an approval card, Use this description?, that shows its draft. Select Confirm to use it, or Cancel and ask for a different version.

3. Save the page

   The draft replaces the text in the field, but it isn’t saved yet. Select Save on an event type or Update on a profile to keep it. If you leave without saving, the old description stays.

The draft can use bold, italic, links and paragraphs, up to 5,000 characters. The assistant is asked to keep the facts from your text and not to add prices, dates or claims, so read the draft before you save it. The sparkle button needs the assistant panel, so it works on larger screens; on a small screen it shows Open the Agent to write a description instead. In Slack, Telegram and iMessage, the assistant can’t fill a field for you.

​

Create private links through the assistant

In the Cal.com web chat, you can ask the Cal.com assistant for a private link to an event type you can edit, for example “a link for my intro call that works 5 times, until Friday” or “a link for the demo that never expires”. The assistant sets the same limits as POST /v2/event-types/{eventTypeId}/private-links:

• No limit given: single use, so the link allows one booking.
• A number of bookings: for example “good for 5 bookings” (maxUses: 5).
• An expiry: a date and time with its time zone offset (expiresAt). For a day, such as “expires Friday”, the assistant uses the end of that day in your time zone. An expiry that has already passed is refused.
• Both: the link stops working at whichever limit is reached first.
• No limit at all: maxUses: -1 with no expiry, so the link works until it’s deleted. With an expiry, -1 means no limit on bookings until then.

The approval card names the event type and each limit, such as Works until …, Allows 5 bookings or No limit: works until it’s deleted. After you approve, the link is shown once in the chat for you to copy.

​

Ask about event types of organization teams you haven’t joined

If you belong to an organization, you can ask the Cal.com assistant about the event types of an organization team you haven’t joined, for example “what event types does the Support team have?”. The assistant lists that team’s event types with the team’s name and each event type’s booking link, the same way it does for teams you’re on.

You can also ask for every team event type in your organization, for example “list all event types in our org”. The assistant lists the event types of every team in your organization, including teams you haven’t joined, team by team with each team’s name and each event type’s booking link. You can narrow the list by title, or ask for the newest or oldest event types across the whole organization. Personal event types aren’t included.

To find a team you haven’t joined, you need permission to see your organization’s teams. Its event types are listed only if your organization role already lets you view that team’s event types; otherwise the assistant tells you it couldn’t read them. Listing every team event type in your organization needs the View booking links for all teams in the organization permission on your organization. Without it, the assistant tells you the organization-wide list isn’t available and offers your own and your teams’ event types instead.

​

Ask about the settings of organization teams you haven’t joined

If you belong to an organization, you can ask the Cal.com assistant about the settings of an organization team you haven’t joined, for example “what time zone is the Support team in?”. The assistant reads the same details it does for teams you’re on, such as the team’s time zone, week start, time format, whether it’s private, its bio and its brand colours. Since you aren’t on the team, it doesn’t give you a role in it.

This needs the View team details and settings permission on that team through your organization role. A team from another organization, or one you don’t have that permission on, is answered as if it doesn’t exist.

​

Find webhooks on an event type through the assistant

You can ask the Cal.com assistant which webhooks you have set up, for example “which webhooks fire when a booking is cancelled?” or “which webhooks are on my 30 min intro call?”. Along with the webhooks on your Webhooks settings page, the assistant lists the webhooks set on your own event types and on the event types of teams where you have the View webhooks permission. Name an event type to see only the webhooks set on it.

For each webhook, the assistant shows the host it sends to, its triggers, whether it’s active, and its team and event type. It lists up to 50 webhooks at a time, tells you how many match in total, and fetches the next page when you ask for the rest.

For a managed event type, the assistant lists only the webhooks set on that event type itself, not the ones it inherits from its parent. Webhooks on a team event type aren’t listed without the View webhooks permission on that team, even if you created the event type. The assistant never shows a webhook’s full URL or signing secret, doesn’t list Zapier or Make subscriptions, and can’t create, change or delete webhooks.

​

Ask what a team role permits

You can ask the Cal.com assistant what a role on one of your teams or your organization lets someone do, for example “what can someone with our Recruiter role do?”. The assistant looks the role up among the team’s roles and describes its permissions in plain words, such as “view bookings”, along with the role’s description and when it was created and last changed.

This works for custom roles and for the built-in Owner, Admin and Member roles. For a built-in role, the assistant describes the permissions it has on that team, as the team’s roles settings page shows them. The assistant can’t create, edit or delete roles.

Seeing a team’s role names needs the View roles permission. To see what a role permits, you also need View team roles and their permissions on a team, or View organization roles and their permissions on an organization. Without it, the assistant tells you that you can see the role names but not what each role permits, and points you to the roles page in the team’s or organization’s settings.

​

Find your Cal Events through the assistant

You can ask the Cal.com assistant to list your Cal Events by where they are in their lifecycle, for example “show me all my past events from this year” or “which drafts haven’t I published?”:

• Upcoming: published events that haven’t ended, soonest first. Events cancelled before they started are included.
• Past: published events that have ended, and cancelled events that had already started, latest first.
• Draft: events that aren’t published yet, soonest first.

If you don’t name one, the assistant lists every status, newest start first. To find a specific event, give part of its name, or paste its event page link and the assistant finds the event that link opens.

The assistant reads your events 50 at a time. When more match, it keeps reading the next pages before it counts your events or says a list is complete, so answers cover every matching event rather than only the first 50.

​

Ask about a Cal Event’s guests through the assistant

You can ask the Cal.com assistant about the guests of a Cal Event, for example “is Priya registered for the product meetup?”, “who said maybe?”, “who’s coming to the Berlin venue?” or “who got refunded?”. The assistant reads the event’s guest list in registration order and can narrow it by:

• Name: part of a guest’s name, such as “Priya”, to find one guest without going through the whole list.
• RSVP: guests who answered yes, no or maybe.
• Location: guests who registered for one of the event’s locations.
• Status: for example only guests who have a seat. If you don’t name one, the assistant looks at guests in every status.

For each guest, it can tell you their registration status, their RSVP, which location they registered for, when they registered, when a host approved or declined them, and when they were checked in at the door. It can also say whether they paid, the amount, and whether the payment was refunded, and whether a host marked them as a no-show. A guest promoted from the waitlist who still has to confirm their seat before a deadline shows as pending confirmation.

The assistant reads up to 50 guests at a time and keeps reading the next pages before it says a list is complete.

Only the event’s hosts, accepted co-hosts and, for a team event, team members with the View events permission can ask about its guests. The assistant never sees guests’ email addresses, phone numbers or registration answers; open the event in Cal.com for those.

​

Approve or decline Cal Event guests through the assistant

You can ask the Cal.com assistant which guests are waiting for approval on a Cal Event, then approve or decline one of them, for example “who’s waiting for approval for the product meetup?”, “approve Priya for the product meetup” or “decline Ben”. The assistant finds the guest in the event’s guest list first and acts on that one guest.

Before anything changes, the approval card, Approve this guest? or Decline this guest?, names the guest and the event, says what will happen and waits for you to select Approve guest or Decline guest:

• Approve: the guest is confirmed if a seat is available. If they chose a paid location, they’re sent a payment request instead and are confirmed only after paying. If the event is full, they stay pending.
• Decline: the guest is declined and emailed. You can also decline a guest on the waitlist.

Only the event’s hosts, accepted co-hosts and, for a team event, team members with permission to edit the event can approve or decline guests. If you can’t manage the event, or the guest isn’t registered for it, the assistant says it can’t find them.

​

Approve all pending Cal Event guests through the assistant

You can also ask the Cal.com assistant to approve everyone waiting for approval on a Cal Event in one go, for example “approve everyone waiting for the product meetup”. To approve only some of them, narrow the request by part of a guest’s name or email, by one of the event’s locations, or both, for example “approve everyone waiting for the Berlin venue”.

Before anything changes, the approval card, Approve all matching pending guests?, names the event, shows how many pending guests currently match and lists any name, email or location filter. Select Approve matching guests to approve them, or Leave unchanged to cancel. The count is taken when the card appears, so guests who register and match before you approve are approved too.

• Free event: matching guests are confirmed while seats are available, and the assistant tells you how many were approved and how many stayed pending because the event is full.
• Paid event: approval runs in the background and sends each matching guest a payment request. They’re confirmed only after paying, and stay pending if the event is full. The assistant tells you the approval has started and how many guests it covers, not that they’re confirmed.

The same people who can approve one guest can approve all of them. The event must be published and not cancelled, and a paid event can approve up to 1,000 pending guests per request. If you can’t manage the event, the assistant says it can’t find it, and nobody is approved.

​

Email a Cal Event’s guests through the assistant

You can ask the Cal.com assistant to email one group of a Cal Event’s guests, for example “tell everyone going to the product meetup that the venue moved to the second floor”. It sends to one of the same groups as Message guests on the Guests board: Going, Maybe or Pending. If you don’t say which guests, the assistant asks. You can narrow the group to the guests at one of the event’s locations, to guests who have checked in, or to guests who haven’t, for example “email the maybes at the Berlin venue”. The assistant writes the subject and message in plain text from your words, with links as plain URLs; if you don’t say what the message should say, it asks instead of making one up.

Before anything is sent, the approval card, Email these guests?, names the event and shows the group, any location or check-in filter, how many guests will be emailed, the subject, the full message and that it’s sent at once and can’t be unsent. If some guests in the group have only a phone number, the card also says how many will be texted instead or won’t get it. Select Send message to send it, or Leave unchanged to cancel. The card and the result of the send show counts only, never a guest’s name, email address or phone number.

After you approve, the message goes out right away. To find out whether it was delivered, ask the assistant, as in Check a Cal Event’s message delivery through the assistant.

The event’s hosts, the owner of a personal event and, for a team event, team members with permission to update its Cal Events can message its guests. Co-hosts can’t. If you can’t message the event’s guests, the assistant says it couldn’t find an event whose guests you can message, and nothing is sent. The same limits apply as on the Guests board; when you’ve sent too many messages, the assistant asks you to try again later. Scheduling a message for later, cancelling a scheduled message and retrying a failed one are done on the event’s page in Cal.com.

​

Check a Cal Event’s message delivery through the assistant

You can ask the Cal.com assistant about messages sent or scheduled to a Cal Event’s guests, for example “did my message to the Going guests go out, and how many failed?”. It reads the message history newest first and reports each message’s guest group, sender, creation time, scheduled send time and delivery status, with email and text counts for sent, failed or skipped deliveries when available. Counts aren’t available while a message is scheduled or sending, or when nothing was delivered.

The assistant can’t read a message’s subject or body, or schedule, cancel or retry these messages. Open the event in Cal.com for those actions.

Only the event’s hosts and, for a team event, team members with permission to update its Cal Events can read its message history. Co-hosts can’t read it through the assistant.

​

Change agenda links through the assistant

You can ask the Cal.com assistant which links the people on a Cal Event’s agenda have, or to change them, for example “add Priya’s LinkedIn to her agenda slot” or “remove Ben’s links from the Q&A”. The assistant can add a link to a person, replace their links or remove all of them. Each person on an agenda item can have up to five links, and their photo stays when their links change.

Before saving, the approval card lists the new links of each person whose links change, such as Priya’s links: https://www.linkedin.com/in/priya, and the people whose links are removed, such as Removes the links of: Ben. People whose links stay the same aren’t listed.

The assistant changes an agenda the same way as PATCH /v2/events/{uuid}, so the same people can change it and links are checked the same way as links added in the event editor. If the agenda is edited after the assistant read it, the card warns you and nothing is saved.

​

Change lineup media players through the assistant

You can ask the Cal.com assistant which media players the people on a Cal Event’s lineup have, or to change them, for example “add DJ Nova’s Spotify playlist to the lineup” or “remove Ben’s players”. The assistant can add a player to a person, replace their players or remove all of them. Each person on the lineup can have up to six players, each with an optional label of up to 100 characters shown above it, and their photo and links stay when their players change.

A player must be a Spotify artist, album, track, playlist, episode or show, a YouTube video, or a SoundCloud profile, track or playlist. The assistant can add any other link to the person’s links instead.

Before saving, the approval card lists the new players of each person whose players change, with each player’s label and link, such as DJ Nova’s players: Nova’s set (https://open.spotify.com/playlist/…), and the people whose players are removed, such as Removes the players of: Ben. People whose players stay the same aren’t listed.

The assistant changes a lineup the same way as PATCH /v2/events/{uuid}, so the same people can change it and players are checked the same way as players added in the event editor. Photos can only be uploaded in the event editor. If the lineup is edited after the assistant read it, the card warns you and nothing is saved.

​

Change a Cal Event’s registration window through the assistant

You can ask the Cal.com assistant when registration opens and closes for one of your Cal Events, or to change it, for example “open registration for the product meetup on June 1 at 9am” or “close registration two hours before the meetup starts”. When it lists or reads your events, the assistant sees each event’s registration window. An event without an opening time opens registration when it’s published, and one without a closing time closes registration when it starts.

You can change the opening time, the closing time or both. To go back to the default for either one, ask the assistant to clear it. A time you don’t mention stays as it is.

Before saving, the approval card shows the opening and closing times as they will be saved. A time that isn’t set reads when the event is published or when the event starts, for example Registration opens when the event is published and closes when the event starts.

The assistant follows the same rules as the event editor: registration must open before it closes, and close at or before the event starts. Co-hosts can’t change the window. If the event is edited after the assistant read it, the card warns you and nothing is saved.

​

Set a Cal Event’s URL, visibility or approval through the assistant

When you ask the Cal.com assistant to create a Cal Event, you can also choose its page URL and whether registrations need approval, for example “create a product meetup on June 12 at cal.com/product-meetup-june, and approve each guest”. Without a URL, the assistant makes one from the event’s name. The approval card shows the URL, such as Page URL: https://cal.com/product-meetup-june, and Registrations: a host approves each guest when you turn approval on.

For an existing Cal Event, you can ask the assistant to change its URL, make it public or unlisted, or turn approval on or off, for example “make the product meetup unlisted” or “let guests register without approval”. The approval card shows each change, such as Page URL: https://cal.com/product-meetup-june (currently https://cal.com/product-meetup), Unlisted: once published, only people with its link can find it or Registrations: guests get a seat right away.

A URL must be 10–100 lowercase letters or digits, with single hyphens between them, and can’t already be taken. Only a draft’s URL can change: once the event is published, the card says its URL can’t change and approving saves nothing. The event’s hosts and team members can change these settings, but co-hosts can’t; for a co-host, the card says approving saves nothing.

​

Change a Cal Event’s guest list, category, payment timeout or live streams through the assistant

You can also ask the Cal.com assistant to change how an existing Cal Event’s page appears to guests, for example “hide the guest names on the product meetup, just show a count”, “don’t show my email and hold seats for 30 minutes while guests pay” or “add the YouTube livestream link to the meetup”. The assistant can change:

• Guest list: show the names of guests who agreed to be listed, show only how many are going, or hide the guest list
• Organizer email: whether guests see the organizer’s email
• Presented by: whether the page shows who presents the event
• Category: meetup, conference, music or sports
• Payment timeout: how long a guest’s seat is held while they pay, from 10 minutes to 7 days (10,080 minutes). Ask the assistant to clear it to go back to the default of 10 minutes.
• Live streams: up to five links where people can watch the event live. The assistant keeps the event’s current links when you add one, and can remove them all.

The approval card shows each change, such as Guest list: shows how many are going, without names, Guests don’t see the organizer’s email, Seats are held 30 minutes while guests pay or Live streams: followed by every link the event will have.

Only a draft’s guest list can change: once the event is published, the card says its guest list setting can’t change and approving saves nothing. The event’s hosts and team members can change the guest list, organizer email, presented-by and category, but co-hosts can’t; for a co-host, the card says approving saves nothing. Co-hosts can change the payment timeout and live stream links.

​

Remove a Cal Event’s cover image through the assistant

You can ask the Cal.com assistant to remove the cover image from one of your Cal Events, for example “remove the cover image from the product meetup”. It removes the cover image and any poster design from the event page, the same as DELETE /v2/events/{uuid}/cover-image.

• Before removing it, the assistant shows an approval card, Remove the cover image?, with the event and that the cover image and any poster design are removed from the event page. Select Remove cover image to remove it, or Leave unchanged to keep it.
• If the event has no cover image, the card says so and approving changes nothing.

The event’s hosts, accepted co-hosts and, for a team event, team members with permission to update its Cal Events can remove its cover image. If you can’t change the event, the assistant says it couldn’t find an event whose cover image you can remove, and nothing changes. Uploading or replacing a cover image is done in the event editor.

​

Share Cal Event links and invite guests through the assistant

You can ask the Cal.com assistant for the link to one of your Cal Events, for example “send me the RSVP link for the product meetup”. It replies with the event’s public page, where guests RSVP. Until the event is published, that page returns a 404 to everyone else, and the assistant says so when it shares a draft’s link.

When the assistant creates, copies or publishes a Cal Event for you, its reply includes a link to the event’s page. For a new draft or a copy, open the link to preview the page; only you and the event’s hosts can see it until it’s published. After publishing, the link opens the live page, which you can share with guests.

You can also ask the assistant to invite guests by email, for example “invite [e-mail] and [e-mail] to the product meetup”. For a Cal Event, “invite” means invite as a guest. The assistant only adds a co-host when you ask for one.

• Each request can include up to 20 email addresses and an optional note to guests of up to 500 characters, without links.
• The assistant only invites addresses you type in the conversation. If you give only a name, it asks for the email address.
• Before sending, the assistant shows the event, each address, your note and that each guest will get an email invitation to RSVP, and waits for you to select Send invitations.
• After sending, it reports the result for each address: invited, already registered, already invited, invited too recently, not a valid address, can’t receive email, listed twice in the request, or couldn’t be saved.

Only the event’s hosts, accepted co-hosts and, for a team event, team members with permission to edit the event can invite guests, and only to a published event that hasn’t started or been cancelled. You need a verified email address, and invitation limits apply.

​

See who’s on a team through the assistant

You can ask the Cal.com assistant who is on one of your teams or your organization, for example “who’s on the Sales team?” or “who have we invited to Sales that hasn’t joined yet?”. The assistant lists people as the team’s members page does, including people who were invited but haven’t accepted yet.

• For each person, the assistant shows their name, username, role (or custom role) and the bio from their profile. Anyone who hasn’t accepted their invitation gets a Pending badge. An invitee may not have a name or username yet.
• You can ask for accepted members only, or for pending invitations only. Otherwise both are listed.
• You can narrow the list by name, username or an exact email address. The assistant never shows email addresses.
• The assistant reads members in pages of up to 25 and tells you how many match in total.
• In an organization, you can also ask about a team of your organization you haven’t joined, for example “who’s on Support?”. The assistant lists its members the same way, and you can mention them in your messages as you would members of your own teams.

For a team you’ve joined, you need the List team members permission, or List private team members for a private team. For an organization, the matching organization permissions apply. For an organization team you haven’t joined, your organization role must let you view that team’s settings as well as list its members (or its private members, for a private team). To find a team you haven’t joined by name, you also need permission to see your organization’s teams. Otherwise the assistant tells you it couldn’t find a team you can access. The assistant can’t change an invitee’s role until they’ve joined.

You can also ask the assistant to cancel a pending invitation, for example “cancel the invite I sent Sam to Sales”. Before cancelling, it shows an approval card, Cancel this invitation to the team?, with the team and the invitee, and waits for you to select Cancel invitation. After you approve, they can no longer join the team with that invitation, and you can invite them again later. You need the Remove team members permission on the team. To cancel an invitation to your organization, see Cancel an organization invitation through the assistant.

​

Read a teammate’s working hours through the assistant

If you belong to an organization, you can ask the Cal.com assistant about a member’s availability schedule, for example “what are Jane’s working hours?”. The assistant finds the member, then reads their default schedule: its time zone, the working hours it sets for each weekday and any date overrides.

Every schedule the assistant reads, yours or a teammate’s, includes the user id of the person it belongs to.

This needs the View availability of organization members permission on your organization, and the person must be an accepted member of it. Sharing a team with them isn’t enough. A schedule you can’t read, or one that belongs to someone else, is answered the same way as one that doesn’t exist. The assistant can read a teammate’s schedule, but it can only change your own schedules.

​

List a team’s or organization’s schedules through the assistant

You can also ask the Cal.com assistant to list availability schedules beyond your own, for example “show me the Sales team’s schedules”, “which schedules in our org are on UTC?” or “what schedules does Sam have?”. It can list:

• A team’s schedules: the schedules of every member of a team.
• Your organization’s schedules: the schedules of every member of your organization.
• A member’s schedules: every schedule one member owns, not just their default.

Each schedule shows its name, its time zone, whether it’s the owner’s default and the user id of the person it belongs to. Working hours aren’t in the list; ask about a schedule to read its hours. Members who have been invited but haven’t joined yet are included, the same as in the API.

You can narrow a team’s or a member’s schedules to one event type, for example “which schedules do the hosts of Sales Demo use?”. The assistant then shows the schedule each host uses for that event type: the event type’s own schedule if it has one, otherwise the host’s schedule for it, otherwise the host’s default. This filter doesn’t work on your organization’s schedules.

The assistant lists 20 schedules at a time by default, up to 50, and tells you when there are more so it can fetch the next page.

A team’s schedules, or a member’s schedules within a team, need the View availability of team members permission on that team. Your organization’s schedules, or a member’s schedules without a team, need the View availability of organization members permission on your organization. The member must belong to that team or organization, either as a member or as a pending invitee. If you don’t have the permission, the assistant answers with an empty list, the same as for a team with no schedules.

​

Block time on one of your schedules through the assistant

You can ask the Cal.com assistant to block part of a day, for example “block Friday 2–4pm”. It makes that window unbookable and keeps the rest of the day’s hours, by saving a date override for that day. A block stays within one day, and a time that has already passed can’t be blocked.

If you have more than one availability schedule, name the one to block, for example “block Friday 2–4pm on my Sales schedule”. The assistant finds that schedule in your list of schedules and blocks the time there. If you don’t name a schedule, it blocks your default schedule. If it can’t find the schedule you named, or more than one could match, it asks which one you mean.

The assistant always asks first. The approval card shows the times and says Your “Sales” availability schedule stops offering this time, or Your default availability schedule stops offering this time when you didn’t name one. After the block is saved, the assistant tells you which of your other schedules still offer that time, and offers to block those too.

The assistant can only block time on your own schedules. A schedule that belongs to someone else is answered the same way as one that doesn’t exist, and nothing is changed.

​

Mark a teammate out of office through the assistant

You can ask the Cal.com assistant to mark a teammate out of office, for example “mark Sam out of office next week, he’s off sick”. The assistant finds them in your team’s member list and saves the entry for them, with the days, reason, private note and the teammate their bookings go to, just like for your own out of office.

• The assistant always asks first. The approval card reads Mark Sam out of office? with the days and Nobody can book them on these days, plus any reason, note and the teammate who gets their bookings. Select Mark out of office to save it, or Don’t mark to leave it.
• Bookings can only go to someone who shares a team with the teammate you’re marking out of office.
• When an entry is saved, the assistant gets its id, and for a teammate’s entry, the teammate’s member id. The assistant uses them to change the entry if you ask later in the chat.

You can also ask the assistant to change a teammate’s existing entry, for example “extend Sam’s out of office to Friday”. The assistant finds the entry among your teammates’ out of office entries, then changes its days, reason, private note or the teammate who gets their bookings, or stops sending their bookings to anyone. The approval card reads Change Sam’s out of office? and shows the entry before and after. Select Change out of office to save it, or Keep as it is to leave it.

To mark a teammate out of office, you need the Create out of office and Update out of office permissions on a team or organization the teammate has accepted their membership of. Otherwise the assistant tells you it couldn’t find a teammate you can set out of office for, and nothing is saved. To change a teammate’s entry, you need the Update out of office permission on such a team or organization. Otherwise the assistant tells you it couldn’t find that out of office entry, and nothing changes.

​

Change a member’s role in an organization team you haven’t joined

If you belong to an organization, you can ask the Cal.com assistant to change a member’s role in an organization team you haven’t joined, for example “make Priya an admin of Marketing”. The assistant shows the same Change this team member’s role? approval card it shows for teams you’re on, naming the team and the member, and changes the role only after you approve. The change is recorded in the audit log as made by you, and the same rules apply as for teams you’re on: you can’t change your own role, give a role above your own or demote the team’s last owner.

This needs the Change role of team members permission on that team through your organization role. To give a custom role there, you also need View team roles and their permissions; without it, only Member, Admin and Owner can be given. A team from another organization, or one you don’t have that permission on, is answered as if it doesn’t exist, and no role changes.

​

Add an organization member to a team through the assistant

If you belong to an organization, you can ask the Cal.com assistant to add a colleague to one of the organization’s teams by name, for example “add Sam from the org to the Sales team as an admin”. You don’t need their email address: the assistant finds them in your organization’s member list.

• The role can be Member, Admin or Owner. If you don’t say, they join as a member. A custom role can’t be given this way, but the assistant can change their role once they’re on the team.
• Before adding anyone, the assistant shows an approval card, Add this organization member to the team?, with the team, the member’s name and the role, and waits for you to select Add to team. The card never shows the member’s email address.
• After you approve, the member joins the team straight away and gets an email saying they were added. The assistant tells you whether they’re on the team now or were sent an invitation they still have to accept.

To invite someone who isn’t in your organization, or if you don’t belong to an organization, give the assistant their email address and it sends them an invitation instead.

You need permission to invite people to the team, and the team must belong to your organization. The person must have accepted their invitation to the organization. Otherwise the assistant tells you it couldn’t find a team you can add that person to, and nobody is added.

​

Remove a member from an organization team you haven’t joined

If you belong to an organization, you can ask the Cal.com assistant to remove someone from an organization team you haven’t joined, for example “remove Sam from the Support team”. The assistant removes them the same way as from a team you’re on.

• Before removing anyone, the assistant shows an approval card, Remove this member from the team?, with the team and the member’s name, and waits for you to select Remove from team. Select Keep member to leave the team as it was.
• After you approve, the member stops hosting the team’s event types and loses their copies of its managed event types. They stay in your organization and in their other teams.

You need the Remove team members permission on that team through your organization role. To find the team by name, you also need permission to see your organization’s teams. A team from another organization, or one you don’t have that permission on, is answered as if it doesn’t exist, and nobody is removed. Only an owner of the team can remove another owner, so you can’t remove a team owner from a team you haven’t joined.

​

Cancel an organization invitation through the assistant

If you invited someone to your organization and they haven’t accepted yet, you can ask the Cal.com assistant to cancel the invitation, for example “cancel the invitation I sent to Sam”.

• Before cancelling, the assistant shows an approval card, Cancel this invitation to the organization?, with the organization and the invitee, and waits for you to select Cancel organization invitation. Select Keep invitation to leave it as it is.
• After you approve, the invitee can no longer join the organization with that invitation. If they were also added to any of the organization’s teams, they leave those teams too. You can invite them again later.
• The assistant tells you the invitation was cancelled, not that a member was removed.

You need the Remove organization members permission. The assistant can’t cancel the invitation of someone invited as an owner: do that from the organization’s members page. If the person isn’t a member of your organization or invited to it, or you don’t have permission, the assistant tells you it couldn’t find a member you can remove, and nothing changes.

​

Change a team’s name, link or bio through the assistant

You can ask the Cal.com assistant to rename one of your teams, change its link or change its bio, for example “rename the Sales team to Revenue and change its link to revenue”. It makes the same change as the team’s profile settings page.

• Before saving, the assistant shows an approval card, Change this team’s profile?, with the team and each field it changes, from the current value to the new one. Select Change team to save, or Leave unchanged to keep the team as it is.
• The link is the last part of the team’s public page address. It’s saved in lowercase, with dashes for spaces, and the old link redirects to the new one.
• A new bio replaces the whole current bio, and you can also ask the assistant to clear it. The bio is shown on the team’s public page.
• If the team hasn’t been published yet, the new link is kept and takes effect once the team is published.

You need the Update team settings permission on the team. In an organization, this also works for a team you haven’t joined if your organization role gives you that permission there. A team name can’t contain a link, and a link another team already uses or that is reserved is refused. A team you can’t change is answered as if it doesn’t exist, and nothing changes. An organization’s own name, link and bio, and a team’s logo and other settings, are changed in Cal.com settings.

​

Create a team through the assistant

If you belong to an organization, you can ask the Cal.com assistant to create a team in it, for example “create a Partnerships team”. It creates the team the same way as your organization’s teams page.

• Before creating it, the assistant shows an approval card, Create this team in your organization?, with the organization, the team’s name and link, and that you become the team’s owner and only member. Select Create team to create it, or Don’t create to cancel.
• The team’s link is made from its name, in lowercase with dashes for spaces.
• After it’s created, you’re the team’s only member, as its owner. You can then ask the assistant to invite people to it.

You need the Create teams permission on your organization. The assistant only creates teams in your own organization: if you aren’t in one, it points you to create a team in Cal.com instead. A team name can’t contain a link, and a name whose link another team or member of your organization already has is refused, with no team created. Moving an existing team into your organization, and setting a team’s logo or other settings, are done in Cal.com.

​

Create a team invite link through the assistant

In the Cal.com web chat, you can ask the Cal.com assistant for a link that anyone can use to join one of your teams or your organization, for example “give me an invite link for the Sales team”. The assistant creates the same link as the team’s invite dialog and POST /v2/teams/{teamId}/invite.

• Before creating it, the assistant shows an approval card, Create a team invite link? (or Create an organization invite link?), with the team or organization, that anyone with the link can join for 7 days, and that the link is shown once for you to copy. Select Create link to create it, or Don’t create to cancel.
• After you approve, the link appears in a card in the chat, ready to copy. The assistant never sees the link itself.
• The link expires after 7 days. Each request creates a new link, and earlier links keep working until they expire.

You need the Invite team members permission on the team, or the Invite organization members permission for your organization’s own link. In an organization, this also works for a team you haven’t joined if your organization role gives you that permission there. A team you can’t invite people to is answered as if it doesn’t exist, and no link is created. Invite links can only be created in the Cal.com web chat: in Slack and other channels, start a new chat in the Cal.com web app, or copy a link from the invite dialog on the team’s members page.

​

Send a follow-up while the assistant is still answering

In Slack, Telegram and iMessage, you can send another message while the Cal.com assistant is still working on your last one, for example “only Tuesday” right after “what’s on my calendar this week?”. The assistant takes the follow-up into the request it’s already working on, so one reply accounts for both messages and you don’t have to wait for an outdated answer and repeat yourself.

A follow-up counts toward your rate limit and needs AI credits or a free question, the same as any other message.

The answer to a follow-up is posted in the same chat even when it takes a while, and it’s posted only once:

• If there’s no answer after about a minute, the assistant replies once with “Still working on this — I’ll reply here when it’s done.” and posts the answer when it’s ready.
• If the assistant hasn’t started on your follow-up after about five minutes, it replies “I couldn’t confirm an answer to your follow-up — please send it again.” That follow-up is then never carried out, so sending it again can’t, for example, book the same meeting twice.
• If the assistant has already started on your follow-up, it doesn’t ask you to send it again. It keeps working and posts the answer for up to 15 minutes.

Only text messages from the person who started the request join it. In a shared Slack thread, a message from another member waits for the current reply and gets its own, as before. In the web app, a message sent while the assistant is answering still gets its own reply after the current one.

​

Chat with the assistant in Slack DMs

In Slack, each conversation with the Cal.com assistant lives in its own thread:

• Each new top-level message you send the assistant in your DM starts a new conversation. The assistant replies in that message’s thread, without the history of your earlier top-level messages.
• To follow up, reply in the thread. The assistant keeps the context of that conversation, so you can say “cancel the 3pm” after asking what’s on your calendar tomorrow.
• When you ask a question with /cal, for example /cal what's on today?, the assistant posts “You asked: what’s on today?” in your DM and answers in that message’s thread, as a new conversation. If your Slack account isn’t linked to Cal.com yet, you only get a prompt to connect it.

While the assistant works on a reply, including after you approve a change, Slack shows that it’s processing your message. The status ends when the assistant finishes, whether it replied, declined or ran into an error.

​

Answer an approval by replying in Slack

When the Cal.com assistant in Slack asks you to approve a change, you can reply in the same DM or thread instead of clicking the card’s Approve or Deny button. The reply answers the card when your whole message, ignoring the bot mention and letter case, is one of these words, optionally starting with “please” and ending with one . or !:

• To approve: approve, approved, yes, y, ok, okay or confirm
• To deny: deny, denied, no, n, decline or reject

The card changes to “Approved by” or “Denied by” you and the assistant carries on, the same as if you had clicked the button. Only the person who made the request can answer their card this way. When a teammate mentions the assistant with “approve” in your thread, your card stays as it is and the assistant treats it as a new message from them.

A reply only answers a card when exactly one of your cards in that conversation is still waiting. If several are waiting, only you see a message asking you to use the button on the one you mean, and nothing changes. Any other message, such as “yes please” or “approve the 3pm one”, goes to the assistant as a normal message. /cal approve doesn’t answer a card either.

​

Answer iMessage approvals one at a time

When the Cal.com assistant on iMessage needs your approval for several changes, it asks about them one at a time. Each prompt describes one change and ends with “Reply YES to approve or NO to deny.”

• To answer, reply with one of these words, in any letter case. To approve: yes, y, yeah, yep, yup, approve, approved or ok. To deny: no, n, nope, nah or deny. The word can be followed by “please”, “thanks” or “thank you” (with a space or comma), and the reply can end with ., , or !, so “Yes!” and “Yes please” both approve. Your reply answers only the prompt that’s waiting.
• After you answer, the next prompt arrives. Once every prompt has its own answer, the assistant carries on, making the changes you approved and skipping the ones you denied.
• If a prompt couldn’t be sent, the assistant asks you to reply RETRY. RETRY sends the prompt again and doesn’t count as an answer. Until the prompt is sent, YES or NO goes to the assistant as a normal message.
• If the assistant can’t carry on after your last answer, for example because you’re out of AI credits, your answers are cleared and the first prompt is sent again.

Only the person who started the conversation can answer its prompts.

Sending any other message while a prompt is waiting, such as a question about the change or “yes but move it to 3pm”, cancels the request. The assistant first replies “Your earlier request is no longer pending approval.”, makes none of the changes from that request, then answers your new message and asks again if approval is still needed. Prompts don’t carry a reference, so a YES sent after a newer prompt arrives answers the newer prompt.

​

Add Connect now to a Cal.ai phone agent’s prompt

When an inbound Cal.ai phone agent has an Instant meeting booking link selected in its Incoming calls tab, callers can ask to talk to someone now. The agent requests an instant meeting and keeps the caller on the line, but it only knows when to offer this and what to say if its prompt tells it. Choosing the booking link doesn’t change your prompt, so add a Connect now section yourself:

1. Open the suggested prompt

   In the agent’s Incoming calls tab, expand Suggested prompt under Instant meeting booking link.

2. Copy it

   Select Copy to copy the section to your clipboard.

3. Add it to the general prompt

   Paste the section into the agent’s General prompt and select Save.

The suggested section tells the agent to collect the caller’s details, ask whether they can stay on the line for up to a couple of minutes before sending the request, explain the wait and that the meeting link arrives by email and text message, and check the request’s status only when the caller asks. If instant meetings aren’t available or the request fails, it books the earliest available time instead. You can edit the wording after pasting it.

​

Rate limits

API key authentication allows 120 requests per minute by default. Contact support if you need higher limits for production agents.

The Markdown documents Cal.com serves for agents, /<user>/llms.txt for a profile and /<user>/<event>.md for an event, are limited to 300 requests per minute per client IP address. When you go over the limit, the response is a plain-text 429 with a Retry-After header giving the number of seconds to wait before trying again.

​

API reference

For complete endpoint documentation, see the API v2 Reference.

Key endpoints for agents:

Endpoint	Description
GET /v2/slots	Check available time slots
POST /v2/bookings	Create a new booking
POST /v2/bookings/:uid/reschedule	Reschedule a booking
POST /v2/bookings/:uid/cancel	Cancel a booking
GET /v2/event-types	List event types
GET /v2/schedules	Get user schedules
POST /v2/webhooks	Configure webhooks
GET /v2/credits/available	Check credit balance
POST /v2/credits/charge	Charge credits for usage