Cal.com Integration

Integrate with Cal.com to list event types, create/cancel bookings, get available slots, manage availability, and retrieve user info via the REST API.

gaoLfun@gaolfun

Install

openclaw skills install @gaolfun/calcom-integration

Cal.com Calendar Integration Skill

Metadata

name: cal-com
description: Integrate with Cal.com calendar: list event types, create/cancel bookings, get available slots, and manage availability schedules via the Cal.com REST API.
version: 1.0.0
author: OpenClaw CCD Team
platform: OpenClaw (ClawHub Skill)

Trigger Phrases

"list my Cal.com event types"
"show available Cal.com bookings"
"book a meeting on Cal.com"
"cancel my Cal.com reservation"
"get open slots on Cal.com"
"what event types do I have on Cal.com"
"create a Cal.com booking for"
"remove my Cal.com booking"
"sync Cal.com availability"
"check my Cal.com schedule"
"set up Cal.com availability"
"update my Cal.com working hours"
"Cal.com integration"
"connect to my Cal.com account"
"get my Cal.com user info"

Capabilities

This skill enables the following operations against the Cal.com REST API (v2):

List Event Types — Retrieve all event types defined in your Cal.com account, including slug, title, duration, and description.
Create a Booking — Book a time slot for a specific event type on behalf of a user.
Cancel a Booking — Cancel an existing booking by its unique UID.
List Bookings — Fetch upcoming and/or past bookings for the authenticated user.
Get Available Slots — Query available time slots for a given event type and date range.
Create / Update Availability Schedule — Define or modify weekly availability rules (working hours, date overrides).
Get User Info — Retrieve the authenticated user's profile, timezone, and default settings.

All API calls target https://api.cal.com/v1. Authentication uses a Bearer token (API key).

Prerequisites

Before using this skill, you must have:

A Cal.com account (self-hosted or on cal.com)
A Cal.com API Key (v2 format) with appropriate read/write scopes
Your Cal.com username or user ID (e.g., johnsmith or 123456)

Environment Variables

Store these in your OpenClaw environment or skill config:

text

CAL_COM_API_KEY=your_calcom_api_key_here
CAL_COM_USERNAME=your_calcom_username_here

Detailed Steps

1 — List Event Types

Endpoint: GET /event-types

Headers:

text

Authorization: Bearer {CAL_COM_API_KEY}
Content-Type: application/json

Example cURL:

bash

curl -s "https://api.cal.com/v1/event-types" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}"

Example Response (success):

json

{
  "event_types": [
    {
      "id": "evt_abc123",
      "slug": "30-min-meeting",
      "title": "30 Minute Meeting",
      "duration": 30,
      "description": "A quick 30-minute call",
      "active": true
    },
    {
      "id": "evt_def456",
      "slug": "60-min-consultation",
      "title": "60 Minute Consultation",
      "duration": 60,
      "description": "Deep dive session",
      "active": true
    }
  ]
}

Failure Response:

json

{
  "error": "unauthorized",
  "message": "Invalid or expired API key."
}

2 — Create a Booking

Endpoint: POST /bookings

Headers:

text

Authorization: Bearer {CAL_COM_API_KEY}
Content-Type: application/json

Request Body:

json

{
  "eventTypeId": "evt_abc123",
  "startTime": "2026-07-10T14:00:00Z",
  "endTime": "2026-07-10T14:30:00Z",
  "attendee": {
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "timezone": "Asia/Shanghai"
  },
  "notes": "Looking forward to the call"
}

Example cURL:

bash

curl -s -X POST "https://api.cal.com/v1/bookings" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeId": "evt_abc123",
    "startTime": "2026-07-10T14:00:00Z",
    "endTime": "2026-07-10T14:30:00Z",
    "attendee": {
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "timezone": "Asia/Shanghai"
    }
  }'

Example Response (success):

json

{
  "booking": {
    "id": "bk_xyz789",
    "uid": "bk_xyz789",
    "eventTypeId": "evt_abc123",
    "title": "30 Minute Meeting",
    "startTime": "2026-07-10T14:00:00Z",
    "endTime": "2026-07-10T14:30:00Z",
    "status": "accepted",
    "attendees": [
      {
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
      }
    ]
  }
}

Failure Response:

json

{
  "error": "booking_conflict",
  "message": "The requested time slot is no longer available."
}

3 — Cancel a Booking

Endpoint: DELETE /bookings/{uid}

Headers:

text

Authorization: Bearer {CAL_COM_API_KEY}

Example cURL:

bash

curl -s -X DELETE "https://api.cal.com/v1/bookings/bk_xyz789" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}"

Example Response (success):

json

{
  "booking": {
    "id": "bk_xyz789",
    "status": "cancelled"
  },
  "message": "Booking cancelled successfully."
}

Failure Response:

json

{
  "error": "not_found",
  "message": "Booking with UID bk_xyz789 not found."
}

4 — List Bookings

Endpoint: GET /bookings

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `upcoming`, `past`, `cancelled`
`limit`	integer	Max results (default: 20, max: 100)
`cursor`	string	Pagination cursor

Example cURL:

bash

curl -s "https://api.cal.com/v1/bookings?status=upcoming&limit=10" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}"

Example Response (success):

json

{
  "bookings": [
    {
      "id": "bk_xyz789",
      "uid": "bk_xyz789",
      "title": "30 Minute Meeting",
      "startTime": "2026-07-10T14:00:00Z",
      "endTime": "2026-07-10T14:30:00Z",
      "status": "accepted",
      "eventType": {
        "slug": "30-min-meeting",
        "title": "30 Minute Meeting"
      },
      "attendees": [
        {
          "name": "Jane Doe",
          "email": "jane.doe@example.com"
        }
      ]
    }
  ],
  "nextPageCursor": null
}

5 — Get Available Slots

Endpoint: GET /slots

Query Parameters:

Parameter	Type	Description
`eventTypeId`	string	The event type ID to check
`startTime`	ISO 8601	Range start (e.g., `2026-07-10T00:00:00Z`)
`endTime`	ISO 8601	Range end (e.g., `2026-07-15T23:59:59Z`)

Example cURL:

bash

curl -s "https://api.cal.com/v1/slots?eventTypeId=evt_abc123&startTime=2026-07-10T00:00:00Z&endTime=2026-07-15T23:59:59Z" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}"

Example Response (success):

json

{
  "slots": [
    {
      "startTime": "2026-07-10T09:00:00Z",
      "endTime": "2026-07-10T09:30:00Z",
      "available": true
    },
    {
      "startTime": "2026-07-10T10:00:00Z",
      "endTime": "2026-07-10T10:30:00Z",
      "available": true
    },
    {
      "startTime": "2026-07-10T10:30:00Z",
      "endTime": "2026-07-10T11:00:00Z",
      "available": false
    }
  ]
}

6 — Create / Update Availability Schedule

Endpoint: POST /schedules (create) or PATCH /schedules/{id} (update)

Headers:

text

Authorization: Bearer {CAL_COM_API_KEY}
Content-Type: application/json

Request Body (create):

json

{
  "name": "My Working Hours",
  "timezone": "Asia/Shanghai",
  "weeklyAvailability": [
    {
      "day": "Monday",
      "startTime": "09:00",
      "endTime": "18:00"
    },
    {
      "day": "Tuesday",
      "startTime": "09:00",
      "endTime": "18:00"
    },
    {
      "day": "Wednesday",
      "startTime": "09:00",
      "endTime": "18:00"
    },
    {
      "day": "Thursday",
      "startTime": "09:00",
      "endTime": "18:00"
    },
    {
      "day": "Friday",
      "startTime": "09:00",
      "endTime": "17:00"
    }
  ],
  "dateOverrides": [
    {
      "date": "2026-07-04",
      "startTime": "10:00",
      "endTime": "14:00"
    }
  ]
}

Example cURL:

bash

curl -s -X POST "https://api.cal.com/v1/schedules" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Working Hours",
    "timezone": "Asia/Shanghai",
    "weeklyAvailability": [
      {"day": "Monday", "startTime": "09:00", "endTime": "18:00"},
      {"day": "Tuesday", "startTime": "09:00", "endTime": "18:00"},
      {"day": "Wednesday", "startTime": "09:00", "endTime": "18:00"},
      {"day": "Thursday", "startTime": "09:00", "endTime": "18:00"},
      {"day": "Friday", "startTime": "09:00", "endTime": "17:00"}
    ]
  }'

Example Response (success):

json

{
  "schedule": {
    "id": "sc_abc123",
    "name": "My Working Hours",
    "timezone": "Asia/Shanghai",
    "weeklyAvailability": [
      {"day": "Monday", "startTime": "09:00", "endTime": "18:00"}
    ],
    "dateOverrides": []
  }
}

7 — Get User Info

Endpoint: GET /users/me

Example cURL:

bash

curl -s "https://api.cal.com/v1/users/me" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}"

Example Response (success):

json

{
  "user": {
    "id": "123456",
    "username": "johnsmith",
    "email": "john.smith@example.com",
    "timezone": "Asia/Shanghai",
    "weekStart": "Monday",
    "defaultEventDuration": 30,
    "locale": "en"
  }
}

Output Format

Success Output

Always returns a structured JSON block with a status field set to "success":

json

{
  "status": "success",
  "action": "list_event_types",
  "data": { ... }
}

Failure Output

Always returns a structured JSON block with a status field set to "error":

json

{
  "status": "error",
  "action": "create_booking",
  "error": "booking_conflict",
  "message": "The requested time slot is no longer available."
}

Example Conversations

Example 1 — List Event Types

User: "What event types do I have set up on Cal.com?"

Agent: I'll list your Cal.com event types now.

bash

curl -s "https://api.cal.com/v1/event-types" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}"

Parsed Response:

json

{
  "status": "success",
  "action": "list_event_types",
  "data": {
    "event_types": [
      {"id": "evt_abc123", "slug": "30-min-meeting", "title": "30 Minute Meeting", "duration": 30},
      {"id": "evt_def456", "slug": "60-min-consultation", "title": "60 Minute Consultation", "duration": 60},
      {"id": "evt_ghi789", "slug": "15-min-intro", "title": "15 Minute Intro Call", "duration": 15}
    ]
  }
}

Summary for User: You have 3 active event types on Cal.com:

Title	Duration	Slug
15 Minute Intro Call	15 min	15-min-intro
30 Minute Meeting	30 min	30-min-meeting
60 Minute Consultation	60 min	60-min-consultation

Example 2 — Book a Meeting

User: "Book a 30-minute meeting with Jane Doe at jane.doe@example.com for July 10th at 2 PM Shanghai time."

Agent: Creating a booking for July 10, 2026 at 14:00 Shanghai time (UTC+8).

bash

curl -s -X POST "https://api.cal.com/v1/bookings" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeId": "evt_abc123",
    "startTime": "2026-07-10T06:00:00Z",
    "endTime": "2026-07-10T06:30:00Z",
    "attendee": {
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "timezone": "Asia/Shanghai"
    }
  }'

Parsed Response:

json

{
  "status": "success",
  "action": "create_booking",
  "data": {
    "booking": {
      "id": "bk_xyz789",
      "title": "30 Minute Meeting",
      "startTime": "2026-07-10T06:00:00Z",
      "endTime": "2026-07-10T06:30:00Z",
      "status": "accepted",
      "attendees": [{"name": "Jane Doe", "email": "jane.doe@example.com"}]
    }
  }
}

Summary for User: ✅ Booking confirmed!

Title: 30 Minute Meeting
Date: July 10, 2026 at 2:00 PM (Shanghai / UTC+8)
Attendee: Jane Doe (jane.doe@example.com)
Booking ID: bk_xyz789

Example 3 — Check Available Slots

User: "What slots are available next week for the 60-minute consultation?"

Agent: Checking available slots for your 60-minute consultation from July 13–17, 2026.

bash

curl -s "https://api.cal.com/v1/slots?eventTypeId=evt_def456&startTime=2026-07-13T00:00:00Z&endTime=2026-07-17T23:59:59Z" \
  -H "Authorization: Bearer ${CAL_COM_API_KEY}"

Parsed Response:

json

{
  "status": "success",
  "action": "get_available_slots",
  "data": {
    "slots": [
      {"startTime": "2026-07-13T02:00:00Z", "endTime": "2026-07-13T03:00:00Z", "available": true},
      {"startTime": "2026-07-13T03:00:00Z", "endTime": "2026-07-13T04:00:00Z", "available": true},
      {"startTime": "2026-07-14T02:00:00Z", "endTime": "2026-07-14T03:00:00Z", "available": true},
      {"startTime": "2026-07-14T04:00:00Z", "endTime": "2026-07-14T05:00:00Z", "available": false},
      {"startTime": "2026-07-15T02:00:00Z", "endTime": "2026-07-15T03:00:00Z", "available": true}
    ]
  }
}

Summary for User: Available 60-minute slots next week (Shanghai timezone):

Mon Jul 13: 10:00 AM, 11:00 AM
Tue Jul 14: 10:00 AM only (11:00 AM is booked)
Wed Jul 15: 10:00 AM

(UTC times shown; subtract 8 hours for Shanghai local time.)

Installation Guide

Step 1 — Get Your Cal.com API Key

Log in to your Cal.com account at cal.com (or your self-hosted instance).
Navigate to Settings → Developer → API Keys.
Click New API Key.
Give it a descriptive name (e.g., OpenClaw Integration).
Select the required scopes: bookings:read, bookings:write, event-types:read, schedules:read, schedules:write.
Click Create and copy the generated key immediately — it is shown only once.
Store it securely; do not share it publicly.

Step 2 — Find Your Username

Your Cal.com username appears in your profile URL: cal.com/{username}.
Alternatively, after creating the API key, the user ID is visible in Settings → Profile.

Step 3 — Configure the Skill

Set the following environment variables or OpenClaw config entries:

bash

CAL_COM_API_KEY=cal_v2_your_generated_key_here
CAL_COM_USERNAME=your_username_here

Step 4 — Verify Connectivity

Test your setup by asking:

"Get my Cal.com user info"

If successful, you'll see your profile returned. If you get an unauthorized error, double-check that your API key is valid and has not expired.

Caveats

Rate Limiting

Cal.com API v2 enforces rate limits per API key (typically 60 requests/minute for standard plans).
Implement exponential backoff on 429 Too Many Requests responses.
Check the Retry-After header for the exact wait time.
Avoid polling slots or bookings in tight loops; cache results where possible.

Webhook Support

This skill does not handle Cal.com Webhooks directly.
If you need real-time booking notifications, pair this skill with an OpenClaw webhook receiver or an external middleware (e.g., a small Express server) that forwards events to OpenClaw.
Ensure your webhook endpoint is HTTPS and reachable from the internet for Cal.com to deliver events.

Timezone Handling

Always use ISO 8601 format with UTC offsets (e.g., 2026-07-10T14:00:00+08:00) or pure UTC (Z).
The Cal.com API internally normalizes all times to UTC.
When displaying times to the user, always convert back to their local timezone (fetchable from /users/me).
Daylight Saving Time (DST) transitions can shift slots by ±1 hour; verify schedule results after DST changes.
For multi-timezone teams, clarify whose timezone is being used when creating bookings.

Event Type IDs vs. Slugs

Use event type IDs (evt_abc123) in API calls, not slugs, for reliability.
IDs are stable; slugs can be changed by the user and may cause 404 errors.
Fetch the ID from the /event-types list before creating a booking.

Cancellation and Rescheduling

Cancelled bookings are marked with status: "cancelled" but are not deleted from the system.
Rescheduling is not directly supported via this skill; cancel the existing booking and create a new one.
Ensure you check status before attempting cancellation to avoid a not_found error.

Availability Schedules

The PATCH /schedules/{id} endpoint performs a full replace, not a merge.
Always fetch the current schedule first, modify the fields you need, then submit the complete object.
Missing required fields (e.g., timezone) in an update will reset them to Cal.com defaults.

Self-Hosted Instances

If using a self-hosted Cal.com instance, replace the base URL:
text
```
https://api.cal.com/v1
```
with your self-hosted API endpoint, e.g.:
text
```
https://your-calcom-instance.com/api/v1
```
Some features (e.g., certain event type fields) may vary between Cal.com versions. Check your instance's OpenAPI spec at /api/v2/docs.

Changelog

Version	Date	Change
1.0.0	2026-07-04	Initial ClawHub release

Skill ID: cal-com | Compatible with Cal.com API v2