mcpField
C
calcom-api

calcom-api

github.com/calcom生产力49.5k235 次安装今天更新
代码仓库

关于 calcom-api

为 AI Agent 提供 Cal.diy API v2 使用指引，涵盖日程自动化、预订管理和日历集成。内容按 API 域组织，并包含认证、可用时段、预订与 Webhook 参考。

主要功能

  1. 01查询可预订时段
  2. 02创建、取消和改期预订
  3. 03配置活动类型与日程
  4. 04查看日历连接和忙碌时段
  5. 05设置 Webhook 通知

适用场景

  1. 01查找时段并创建会议预订
  2. 02修改或取消现有预订
  3. 03接收预订事件的实时通知

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calcom/cal.diy --skill calcom-api

安装后在 Claude Code 中输入/calcom-api确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
authentication.md
bookings.md
calendars.md
event-types.md
schedules.md
slots-availability.md
webhooks.md

详细介绍

Cal.diy API v2

本技能为 AI Agent 提供与 Cal.diy API v2 交互的指导，支持日程安排自动化、预约管理和日历集成。

基础 URL

所有 API 请求应发送至：

https://api.cal.com/v2

所需凭证

环境变量是否必需描述
CAL_API_KEY是Cal.diy API 密钥（以 cal_live_ 或 cal_test_ 为前缀）。用作所有 API 请求的 Bearer token。从 Settings > Developer > API Keys 生成。
CAL_CLIENT_ID否用于代表他人管理用户的平台集成的 OAuth 客户端 ID。作为 x-cal-client-id 请求头发送。
CAL_SECRET_KEY否用于平台集成的 OAuth 客户端密钥。作为 x-cal-secret-key 请求头发送。
CAL_WEBHOOK_SECRET否用于通过 X-Cal-Signature-256 请求头验证 webhook 负载签名的密钥。

身份验证

所有 API 请求都需要通过 Bearer token 进行身份验证：

Authorization: Bearer cal_<your_api_key>

有关包括 OAuth/平台身份验证在内的详细身份验证方法，请参阅 references/authentication.md。

核心概念

事件类型定义了可预约的会议配置（时长、地点、可用性规则）。每个事件类型都有一个唯一的 slug，用于预约 URL 中。

预约是当有人预约某个事件类型时创建的已确认的会面。每个预约都有一个唯一的 UID 用于识别。

日程表定义了用户可供预约的时间。用户可以有多个具有不同工作时间的日程表。

时间段表示根据事件类型配置和用户可用性可以预约的可用时间窗口。

参考文档

本技能包含每个领域的详细 API 参考文档：

参考描述
references/authentication.mdAPI 密钥和 OAuth 身份验证、速率限制、安全最佳实践
references/bookings.md创建、列出、取消、重新安排预约
references/event-types.md配置可预约的会议类型
references/schedules.md管理用户可用性日程表
references/slots-availability.md查询可用时间段
references/calendars.md日历连接和忙碌时间
references/webhooks.md实时事件通知

快速开始

1. 检查可用时间段

在创建预约之前，检查可用时间段：

GET /v2/slots?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&eventTypeId=123

完整详情请参阅 references/slots-availability.md。

2. 创建预约
POST /v2/bookings
Content-Type: application/json

{
  "start": "2024-01-15T10:00:00Z",
  "eventTypeId": 123,
  "attendee": {
    "name": "John Doe",
    "email": "[email protected]",
    "timeZone": "America/New_York"
  }
}

所有预约操作请参阅 references/bookings.md。

3. 设置 Webhook

接收预约事件的实时通知：

POST /v2/webhooks
Content-Type: application/json

{
  "subscriberUrl": "https://your-app.com/webhook",
  "triggers": ["BOOKING_CREATED", "BOOKING_CANCELLED"]
}

可用的触发器和负载格式请参阅 references/webhooks.md。

常见工作流

预约会议：检查时间段 -> 创建预约 -> 存储预约 UID

重新安排：获取新时间段 -> POST /v2/bookings/{uid}/reschedule

取消：POST /v2/bookings/{uid}/cancel，可附带可选原因

最佳实践

  1. 在创建预约之前始终检查时间段可用性
  2. 存储预约 UID 以便后续操作（取消、重新安排）
  3. 对所有时间戳使用 ISO 8601 格式
  4. 实现 webhook 处理程序以实现实时更新
  5. 使用指数退避处理速率限制

其他资源

评论

支持 Markdown