> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Cal.com

## 概述

将 ElevenLabs AI 智能体与 [Cal.com](https://cal.com) 连接，管理日程安排和日历预订。通过此集成，智能体可通过自然对话查询可用时间、预约、取消或重新安排会议，以及查找现有预订。

## 功能

| 功能         | 支持情况          |
| ---------- | ------------- |
| 零保留模式（ZRM） | 不支持           |
| 工具中的附件     | 不支持 — 工具仅处理文本 |

## 设置

此集成使用 **Cal.com API 密钥**进行身份验证（而非 OAuth 应用）。

#### 在 Cal.com 中生成 API 密钥

在 Cal.com 账户中前往 **Settings > Developer > API Keys**，然后点击 **New**。请立即复制生成的密钥 — 之后将不会再次显示。

#### 使用正式密钥

Cal.com 会生成两种密钥 — 测试密钥（以 `cal_` 开头）和正式密钥（以 `cal_live_` 开头）。请使用**正式密钥**，以便智能体访问真实日历数据。

#### 在 ElevenLabs 中连接

在 ElevenLabs 集成设置中，将 Cal.com API 密钥粘贴到 **API Key** 字段。

## 演示

> **Note**
>
> 此演示使用旧版 webhook 工具。如果你使用原生 Cal.com 集成，工具会自动配置，
> 无需手动设置 webhook。

## 工作原理

智能体通过工具调用逐步完成预约流程。以下标签页展示高级概览和详细系统提示词。

#### 高级概览

#### 初步咨询与会议详情

智能体会询问会议目的、首选日期和时间以及时长，以收集日程安排信息。

#### 查询日历可用时间

智能体会通过以下方式查询日历可用时间：

* 使用 `get_available_slots` 工具获取空闲时段。
* 确认请求的时间是否可用。
* 如果请求的时间不可用，建议其他时间。
* 与来电者确认所选时间。

#### 收集联系信息

确定时间后，智能体会：

* 收集并验证参会者全名。
* 核实邮箱地址是否准确。
* 确认时区信息。
* 收集 Cal.com 事件类型所需的其他字段。

#### 创建会议

智能体会：

* 验证所有信息后调用 `book_meeting` 工具。
* 遵循预约模板结构。
* 向参会者确认会议已创建。
* 告知对方将收到日历邀请。

#### 详细系统提示词

```
You are a helpful receptionist responsible for scheduling meetings using the Cal.com integration. Be friendly, precise, and concise.

Begin by briefly asking for the purpose of the meeting and the caller's preferred date and time.
Then, ask about the desired meeting duration (15, 30, or 60 minutes), and wait for the user's response before proceeding.

Once you have the meeting details, say you will check calendar availability:
- Call get_available_slots with the appropriate date range
- Verify if the requested time slot is available
- If not available, suggest alternative times from the available slots
- Continue until a suitable time is agreed upon

After confirming a time slot, gather the following contact details:
- The attendee's full name
- A valid email address. Note that the email address is transcribed from voice, so ensure it is formatted correctly.
- The attendee's time zone (in 'Continent/City' format like 'America/New_York')
- Read the email back to the caller to confirm accuracy

Once all details are confirmed, explain that you will create the meeting.
Create the meeting by using the book_meeting tool with the following parameters:
- start: The agreed meeting time in ISO 8601 format
- eventTypeId: The appropriate ID based on the meeting duration (15min: 1351800, 30min: 1351801, 60min: 1351802)
- attendee: An object containing the name, email, and timeZone

Thank the attendee and inform them they will receive a calendar invitation shortly.

Clarifications:
- Do not inform the user that you are formatting the email; simply do it.
- If the caller asks you to proceed with booking, do so with the existing information.

Guardrails:
- Do not share any internal IDs or API details with the caller.
- If booking fails, check for formatting issues in the email or time conflicts.
```

## 手动设置 webhook

> **Note**
>
> 如果使用原生 Cal.com 集成，工具会自动配置。以下步骤
> 仅适用于手动设置 webhook。

#### 存储 Cal.com 密钥

发起经过身份验证的请求前，请安全存储 API 密钥。如果尚未生成，请新建一个 [Cal.com API 密钥](https://cal.com/docs/api-reference/v1/introduction#get-your-api-keys)。

Cal.com API 要求使用以下身份验证标头：

**`Cal 请求标头结构`**

```plaintext Cal 请求标头结构
'Authorization': 'Bearer YOUR_API_KEY'
```

将密钥存储在智能体的密钥存储中，确保安全，并在发起请求时可访问。

> **Warning**
>
> 为匹配 Cal.com 所需的身份验证结构，创建密钥时请记得在 API 密钥前添加 `Bearer `。

![工具密钥](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp)

#### 向智能体添加工具

创建以下两个工具以启用日历预约：

1. **`get_available_slots`**：当用户询问 *"Louis 周二上午 10:30 有空吗？"* 时，智能体会使用 [Cal.com 的“获取可用时段”端点](https://cal.com/docs/api-reference/v2/slots/find-out-when-is-an-event-type-ready-to-be-booked)检查空闲时段。

2. **`book_meeting`**：确定合适的时间后，智能体会使用 [Cal.com 的“创建预约”端点](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#create-a-booking)预约会议。

前往控制台的 **Tools** 部分并选择 **Add Tool**。选择 **Webhook** 作为工具类型，然后填写以下部分：

#### 工具 1：get_available_slots

#### 配置

智能体用于确定何时调用工具的元数据：

| 字段  | 值                                                            |
| --- | ------------------------------------------------------------ |
| 名称  | get_available_slots                                          |
| 描述  | 此工具用于检查日历中特定时段是否可用。                                          |
| 方法  | GET                                                          |
| URL | [https://api.cal.com/v2/slots](https://api.cal.com/v2/slots) |

#### 标头

与[此处](https://cal.com/docs/api-reference/v2/slots/get-available-slots#get-available-slots)定义的请求标头一致：

| 类型  | 名称              | 值          |
| --- | --------------- | ---------- |
| 密钥  | Authorization   | 选择上方创建的密钥  |
| 字符串 | cal-api-version | 2024-09-04 |

#### 查询参数

与[此处](https://cal.com/docs/api-reference/v2/slots/get-available-slots#get-available-slots)定义的请求查询参数一致：

| 数据类型   | 标识符         | 必填 | 描述                                                           |
| ------ | ----------- | -- | ------------------------------------------------------------ |
| string | start       | 是  | 获取时段的起始日期/时间（UTC），例如 '2024-08-13T09:00:00Z'。                 |
| string | end         | 是  | 获取时段的结束日期/时间（UTC），例如 '2024-08-13T17:00:00Z'。                 |
| string | eventTypeId | 是  | 所预约事件类型的 ID。若为 15 分钟，返回 abc；若为 30 分钟，返回 def；若为 60 分钟，返回 xyz。 |

#### 工具 2：book_meeting

#### 配置

智能体用于确定何时调用工具的元数据：

| 字段  | 值                                                                  |
| --- | ------------------------------------------------------------------ |
| 名称  | book_meeting                                                       |
| 描述  | 确定时间后，此工具会在日历中预约会议。                                                |
| 方法  | POST                                                               |
| URL | [https://api.cal.com/v2/bookings](https://api.cal.com/v2/bookings) |

#### 标头

与[此处](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#create-a-booking)定义的请求标头一致：

| 类型  | 名称              | 值          |
| --- | --------------- | ---------- |
| 密钥  | Authorization   | 选择上方创建的密钥  |
| 字符串 | cal-api-version | 2024-08-13 |

#### 请求正文参数

与[此处](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#create-a-booking)定义的请求正文参数一致：

| 标识符         | 数据类型   | 必填 | 描述                                                           |
| ----------- | ------ | -- | ------------------------------------------------------------ |
| start       | String | 是  | UTC 时区的 ISO 8601 格式预约开始时间，例如 '2024-08-13T09:00:00Z'。         |
| eventTypeId | Number | 是  | 所预约事件类型的 ID。若为 15 分钟，返回 abc；若为 30 分钟，返回 def；若为 60 分钟，返回 xyz。 |
| attendee    | Object | 是  | 参会者详情。必须从用户处收集这些字段。                                          |

> **Note**
>
> `eventTypeId` 必须对应你在 Cal 中可用的事件类型。调用
> [此](https://cal.com/docs/api-reference/v1/event-types/find-all-event-types#find-all-event-types)
> 端点可获取账户事件类型列表（或者创建另一个工具自动完成此操作）。

**参会者对象：**

| 标识符      | 数据类型   | 必填 | 描述                                                                   |
| -------- | ------ | -- | -------------------------------------------------------------------- |
| name     | String | 是  | 预约会议人员的全名。                                                           |
| email    | String | 是  | 预约会议人员的邮箱地址。                                                         |
| timeZone | String | 是  | 来电者的时区。格式应为 'Continent/City'，如 'Europe/London' 或 'America/New_York'。 |

> **Success**
>
> 点击 **Test AI agent** 按钮测试智能体。按需调整系统提示词。

#### 添加日期和时间感知

默认情况下，智能体不知道当前日期或时间。使用以下任一方法：

1. **创建时间获取工具**：添加一个获取当前日期和时间的工具。

2. **Overrides**：使用 [overrides](/docs/zh/eleven-agents/customization/personalization/overrides) 功能，在每次对话开始时将当前日期和时间注入系统提示词。

## 安全注意事项

* 所有 webhook 调用均使用 HTTPS 端点。
* 使用 ElevenLabs Secrets Manager 将敏感值存储为密钥。
* 验证所有授权标头是否采用所需格式（`Bearer YOUR_API_KEY`）。
* 绝不向来电者透露事件类型 ID 或 API 详情。

## 实用链接

* [Cal.com API 文档](https://cal.com/docs/api-reference/v2/introduction)
* [Cal.com API 密钥指南](https://cal.com/blog/where-is-my-api-key-and-what-can-it-do)
* [ElevenLabs 工具概览](/docs/zh/eleven-agents/customization/tools/server-tools)