核心用法
Calendly skill 提供对 Calendly 日程管理平台的完整 API 访问能力，采用 Maton 托管的 OAuth 2.0 认证方案，开发者仅需配置 MATON_API_KEY 即可调用所有 Calendly 原生接口。核心功能覆盖六大模块：
用户与组织管理：获取当前用户信息、查询组织成员关系，支持多账号场景下的连接切换。
事件类型（Event Types）：列出用户的所有可预约时段模板（如"30分钟会议"），包含时长、颜色标识、公开链接等元数据，但不支持程序化创建或修改事件类型。
已预约事件（Scheduled Events）：查询、筛选（按时间范围、状态、邀请人邮箱）及取消已预约会议。取消操作需显式提供原因，且系统要求在执行写入前向用户确认目标资源。
邀请人管理（Invitees）：获取会议参与者详情，包括自定义问答、追踪参数（UTM）、取消/改期链接。支持通过 Scheduling API 程序化创建预约，但需 Calendly 付费计划（Standard/Teams/Enterprise）。
可用性查询：获取特定事件类型的可预约时段（7天范围限制）、用户忙碌时间（集成外部日历冲突检测）、以及用户的可用性规则配置。
Webhook 自动化：订阅 invitee.created、invitee.canceled 等事件实现实时通知，需付费计划，支持组织级或用户级作用域，可配置签名密钥验证回调真实性。
显著优点
- 零OAuth开发成本：Maton 代理层自动处理令牌刷新、权限协商和密钥安全存储，开发者无需搭建 OAuth 服务器或管理
client_secret。 - 原生Calendly体验：完整保留 Calendly 的 URI 资源标识体系和业务逻辑，与官方 API 文档 1:1 对应。
- 多账户灵活切换：通过
Maton-Connection头部可在单次请求中指定不同 Calendly 账号，适合代运营或企业多成员场景。 - 实时可用性计算：服务端自动合并 Calendly 内置规则与外部日历（Google/Outlook）冲突，返回精确到30分钟颗粒度的可约时段。
潜在缺点与局限性
- 功能不对称：只读操作丰富，但事件类型创建、修改完全缺失； Scheduling API 的邀请人创建功能受限于付费计划门槛。
- 时间范围硬限制：可用性查询强制 7 天最大窗口，且
start_time必须为未来时间，无法做历史分析或远期规划（>7天）。 - Webhook 付费墙：免费计划用户无法使用任何事件订阅能力，自动化集成成本较高。
- 间接依赖风险：所有请求经 Maton 代理中转，若 Maton 服务故障或策略变更，将直接影响业务连续性；同时需信任第三方托管 OAuth 令牌。
- 无内嵌UI组件：纯 API 层集成，不提供 Calendly 官方提供的嵌入调度界面（embeddable widget），前端需自行构建预约流程。
适合人群
- SaaS 产品经理：需在内部系统嵌入"找客户约个会"流程，但不想跳转到 Calendly 域名。
- 销售/CSM 自动化工程师：构建线索分配→自动预约→CRM 回写的闭环，依赖 Webhook 实时触发。
- 行政与HR系统开发者：批量查询高管可用时段、统一管控企业级预约策略。
常规风险
- 误操作取消会议：
POST .../cancellation为不可逆操作，文档明确要求执行前向用户二次确认；若自动化脚本逻辑缺陷，可能导致客户会议被批量取消。 - 时区处理陷阱：API 返回 ISO 8601 带时区偏移时间，但用户配置的 "timezone" 字段仅为展示偏好，实际预约以传入的
start_time时区为准，跨时区团队易约定错误。 - 隐私合规：获取 invitee 数据时包含邮箱、姓名及自定义问答内容，需确保符合 GDPR/CCPA 数据最小化原则，避免过度采集。
- 速率限制（429）：Calendly 底层限流策略未公开具体阈值，高频同步场景需实现指数退避重试。