Cal.com 团队配置全指南：从创建到事件管理-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00147/article/details/148326037

Cal.com 团队配置全指南：从创建到事件管理

cal.com cal.com: cal.com是一款开源的日历应用，提供了一种统一的方式来管理个人或团队的日程安排和事件，具有良好的用户体验和强大的API。项目地址: https://gitcode.com/gh_mirrors/ca/cal.com

前言

在现代协作环境中，团队协作工具已成为提高工作效率的关键。Cal.com 作为一款优秀的日程管理平台，提供了完善的团队配置功能。本文将深入讲解如何通过 API v2 在 Cal.com 中配置团队，包括创建团队、添加成员、设置团队事件类型等核心功能。

准备工作

在开始配置团队前，请确保满足以下条件：

OAuth 客户端配置：需要预先设置 OAuth 客户端，获取客户端 ID 和密钥
订阅计划：至少需要 ESSENTIALS 或更高级别的订阅
管理员权限：
- 创建团队和访问团队信息需要组织管理员/所有者权限
- 创建和访问团队事件类型需要团队管理员/所有者权限
API 请求头：所有团队相关 API 请求都需要提供 x-cal-client-id 和 x-cal-secret-key 头部信息

团队配置详细步骤

第一步：创建团队

创建团队是整个流程的基础，以下是创建团队的核心要点：

{
    "name": "平台团队",
    "slug": "platform-team",
    "bio": "这是我们的平台团队！"
}

关键参数说明：

name：团队名称，用于显示
slug：团队唯一标识符，用于URL等场景
bio：团队简介，可选

响应示例：

{
  "status": "success",
  "data": {
    "id": 35137,
    "name": "平台团队",
    "slug": "platform-team",
    // 其他团队属性...
  }
}

最佳实践：

务必保存返回的 teamId，后续操作都将依赖此ID
建议为团队设置合理的时区(timeZone)和周起始日(weekStart)

第二步：添加团队成员

空团队没有实际意义，我们需要添加成员：

首先创建托管用户
然后为该用户创建团队会员资格

添加会员请求示例：

{
  "userId": 1278670,
  "teamId": 36147,
  "role": "ADMIN"
}

角色说明：

ADMIN：团队管理员，拥有最高权限
MEMBER：普通成员，权限受限

响应关键字段：

accepted：表示会员是否已接受邀请
disableImpersonation：是否禁用模拟功能

第三步：创建团队事件类型

团队事件是团队协作的核心，以下是创建团队事件的关键参数：

{
  "lengthInMinutes": 60,
  "title": "每日站会",
  "slug": "platform-daily-standup",
  "description": "平台团队的每日站会！",
  "schedulingType": "COLLECTIVE",
  "hosts": [{"userId": 1399}]
}

调度类型说明：

COLLECTIVE：集体类型，适合团队会议
ROUND_ROBIN：轮询类型，适合轮流主持的会议

响应关键信息：

locations：会议地点设置
bookingFields：预订表单字段配置
hosts：会议主持人列表

第四步：前端集成

完成后端配置后，需要在前端展示团队事件：

基础集成示例：

<Booker
  isTeamEvent={true}
  teamId={35243}
  eventSlug="daily-standup-for-platform"
  onCreateBookingSuccess={(booking) => {
    console.log("预订创建成功", booking);
  }}
/>

使用自定义Hook获取团队数据：

import { useTeams, useTeamEventTypes } from "@calcom/atoms";

function TeamEvent(){
    const { data: teams } = useTeams();
    const { data: teamEventTypes } = useTeamEventTypes(teams?.[0]?.id || 0);
    // 渲染团队事件...
}