> 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.

# Zendesk

## 概览

将 ElevenLabs AI 智能体连接到 [Zendesk](https://www.zendesk.com/)，以管理支持工单、用户和组织。此集成让智能体能够创建和更新工单、搜索现有记录、管理用户，以及回复传入的工单评论。

## 功能

| 功能         | 支持情况                                                                              |
| ---------- | --------------------------------------------------------------------------------- |
| 零留存模式（ZRM） | 不支持                                                                               |
| 触发器中的附件    | 当智能体设置中启用 **允许文件附件**，且智能体的 LLM 支持图像或文档输入时，支持传入工单评论中的图像（PNG、JPEG、GIF、WebP）和 PDF 文件 |
| 工具中的附件     | 不支持——`zendesk_show_ticket` 和 `zendesk_list_ticket_comments` 等工具会返回文本字段，不会下载附件     |

## 设置

此集成支持 3 种身份验证方式：ElevenLabs OAuth 应用、自定义 OAuth 客户端和 API 令牌。

> **Note**
>
> Zendesk 正在[弃用 API 令牌](https://support.zendesk.com/hc/en-us/articles/10851263566234)
> 这一身份验证方式，并转向仅 OAuth 访问。现有基于 API 令牌的 Zendesk 集成将持续可用至 2027 年 4 月 30 日。
> ElevenLabs 正在支持此次迁移，并会主动联系受影响的客户，协助在此之前迁移到 OAuth。你可随时切换到下方的
> **自定义 OAuth 客户端** 方法。

#### OAuth

#### 查找子域名

Zendesk 子域名是 Zendesk URL 的第一部分（例如，`mycompany.zendesk.com` 中的 `mycompany`）。

#### 在 ElevenLabs 中连接

在 ElevenLabs 集成设置中，选择 **OAuth2** 凭据，输入 **子域名**，然后点击 **连接**。

#### 授权连接

Zendesk 会显示授权页面，列出 ElevenLabs 应用请求的访问权限：整个账户的读取权限，以及对工单、用户、webhook 和触发器的写入权限。请以拥有智能体所需权限的用户身份登录，然后点击 **允许**。Zendesk 会将你重定向回 ElevenLabs，并创建连接。

如果计划使用 Zendesk 触发器，请以管理员身份授权——创建 webhook 和编辑触发器仅限 Zendesk 管理员。

#### API 令牌

#### 启用 API 令牌访问

在 [Zendesk Admin Center](https://support.zendesk.com/hc/en-us/articles/4581766374554-Using-Admin-Center) 中，前往 **Apps and integrations > APIs > Zendesk API**，然后启用 **Token Access**。

#### 生成 API 令牌

前往 **Apps and integrations > APIs > API tokens**，然后点击 **Add API token**。请立即复制令牌——关闭对话框后将不再显示。

#### 查找子域名

Zendesk 子域名是 Zendesk URL 的第一部分（例如，`mycompany.zendesk.com` 中的 `mycompany`）。

#### 在 ElevenLabs 中连接

在 ElevenLabs 集成设置中，输入 **邮箱**、**API 令牌**和 **子域名**。

#### 自定义 OAuth 客户端

#### 复制重定向 URL

在 ElevenLabs Zendesk 集成设置中，复制 **重定向 URL**。

#### 在 Zendesk 中创建 OAuth 客户端

在 [Zendesk Admin Center](https://support.zendesk.com/hc/en-us/articles/4581766374554-Using-Admin-Center) 中，前往 **Apps and integrations > APIs > OAuth clients**，然后点击 **Add Client**。输入 **名称**和唯一的 **标识符**。

#### 添加重定向 URL

将从 ElevenLabs 复制的 **重定向 URL** 粘贴到 OAuth 客户端配置中。

#### 保存密钥

保存 OAuth 客户端。Zendesk 会显示一个 **密钥**——请复制并妥善保存。关闭对话框后将不再显示。

#### 在 ElevenLabs 中连接

在 ElevenLabs 集成设置中，将 **标识符** 作为客户端 ID 输入，并提供 **密钥**。Zendesk 会将你重定向以授权连接。

## OAuth 作用域

使用 **OAuth2** 凭据连接后，ElevenLabs 将获得以下 [Zendesk OAuth 作用域](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/)。读取权限覆盖整个账户；写入权限则按资源请求，因此令牌无法修改集成未使用的资源。

| 作用域              | 用途                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| `read`           | GET 端点的读取权限。用于获取工单、工单评论及其附件、用户、组织、问题工单和搜索结果；在连接触发器时，也用于查询 Zendesk 触发器并读取 ElevenLabs 创建的 webhook 的签名密钥。 |
| `tickets:write`  | 创建、更新、删除和合并工单，发布公开和内部评论，以及添加或移除标签。供工单工具使用，并在 Zendesk 触发器触发时发布智能体回复。                                    |
| `users:write`    | 创建、更新和删除用户，包括批量创建或更新。供用户管理工具使用。                                                                        |
| `webhooks:write` | 激活 Zendesk 触发器时，创建将工单事件传送至智能体的 webhook；停用触发器时，删除该 webhook。                                             |
| `triggers:write` | 将 ElevenLabs webhook 操作添加到指定的 Zendesk 触发器；停用触发器时，移除该操作。                                                |

令牌权限绝不会超过授权用户的权限——实际访问权限是这些作用域与该用户 Zendesk 角色权限的交集。

这些作用域不适用于另外两种身份验证方式：自定义 OAuth 客户端会请求 `read` 和 `write`（完整读写权限），而 API 令牌拥有其所属 Zendesk 用户的全部权限。

## 数据披露

下表列出集成会访问 Zendesk 账户中的所有字段、ElevenLabs 是否存储这些字段，以及访问的时间和原因。**读取** 表示该值会在处理期间使用，但不会持久化。**读取并存储** 表示该值会持久化到 ElevenLabs 对话记录中。**写入** 表示集成会将其发送到 Zendesk。

| 数据                              | 访问权限  | 原因                                                                                                                 |
| ------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------ |
| 工单 ID                           | 读取并存储 | 通过触发器 webhook 负载传入，这是 Zendesk 推送给 ElevenLabs 的唯一工单数据。会存储为对话的外部 ID、`integration__zendesk_ticket_id` 动态变量，以及返回工单的链接。 |
| 工单主题                            | 读取并存储 | 触发器触发时从工单中读取。存储为 `integration__zendesk_ticket_subject` 动态变量，以便系统提示词和工具可以引用工单内容。                                    |
| 工单创建时间戳                         | 读取并存储 | 与工单一同读取。存储为 `integration__zendesk_ticket_created_at` 动态变量，用于提示词，例如判断工单存在时长。                                        |
| 请求者 ID                          | 读取并存储 | 与工单一同读取。存储为 `integration__zendesk_ticket_requester_id` 动态变量，并用于标注评论归属——即使请求者同时是员工，仍视为客户。                           |
| 工单标签                            | 读取    | 每次运行触发器时读取，以检测 `agent-rating-<score>` 标签和 `force-agent` 标签。对话中仅存储最终评分，不会持久化标签列表本身。                                 |
| 公开和内部评论正文                       | 读取并存储 | 每次运行触发器时从工单评论中读取。存储为对话转录文本并发送给智能体的 LLM——这是智能体回复的对话内容。                                                              |
| 评论 ID                           | 读取并存储 | 与评论一同读取。最新 ID 会存储为上次处理标记，以便下次运行触发器时跳过智能体已回复的评论。                                                                    |
| 评论作者 ID                         | 读取并存储 | 与评论一同读取，并用于查找作者。当作者没有邮箱地址时，会存储为转录消息的用户标识符。                                                                         |
| 评论作者角色                          | 读取    | 按评论作者读取，以决定评论在转录文本中应成为客户消息还是员工消息。不会持久化角色本身，仅存储每条消息最终的归属。                                                           |
| 评论作者邮箱地址                        | 读取并存储 | 按评论作者读取。存储为归属客户的转录消息中的用户标识符，以便跨工单将对话关联到同一人。                                                                        |
| 请求者邮箱地址                         | 读取并存储 | 与请求者用户记录一同读取。存储为 `integration__zendesk_ticket_requester_email` 动态变量，以便提示词和工具称呼或查找客户。                               |
| 附件元数据：文件名、MIME 类型、大小            | 读取并存储 | 与评论一同读取，以检查附件是否为支持的类型且未超出大小限制。存储在附件所属的转录消息中。                                                                       |
| 附件文件内容                          | 读取并存储 | 仅当智能体启用 **允许文件附件** 且其 LLM 支持该文件类型时下载。存储为对话文件，以便智能体读取客户发送的内容。                                                       |
| Zendesk 子域名                     | 读取并存储 | 连接时由你提供。存储在集成连接设置中，因为它构成 API 基础 URL。                                                                               |
| Zendesk 账户邮箱，仅用于 API token 身份验证 | 读取并存储 | 连接时由你提供。存储在连接设置中，因为 API token 身份验证会将账户邮箱与 token 一同发送。                                                              |
| API token、OAuth 访问和刷新 token     | 读取并存储 | 静态加密存储，仅用于验证 API 调用身份。绝不会暴露给智能体、提示词或 API。                                                                          |
| Webhook 签名密钥                    | 读取并存储 | 激活触发器时读取一次。加密存储，用于验证传入的 webhook 确实来自 Zendesk 账户。                                                                   |
| 触发器标题、条件和操作                     | 读取    | 激活触发器时读取，以按名称查找触发器，并在添加 ElevenLabs webhook 操作时保留其现有操作。不会持久化。                                                       |
| 智能体回复                           | 写入    | 作为工单公开评论发布；启用影子模式时则作为内部评论发布。这是集成的核心用途。                                                                             |
| 对话链接                            | 写入    | 每个工单发布一次内部评论，以便员工在 ElevenLabs 中打开对话。                                                                               |
| 附件错误通知                          | 写入    | 当附件因类型不受支持、文件过大或下载失败而被跳过时，会作为内部评论发布，以便员工知道智能体未看到该附件。                                                               |
| ElevenLabs webhook 注册           | 写入    | 激活 Zendesk 触发器时创建，停用时删除。这是 Zendesk 在工单事件发生时调用的端点。                                                                  |
| 触发器上的 webhook 操作                | 写入    | 激活时添加到你指定的触发器，停用时移除。会保留触发器上的现有操作。                                                                                  |
| 工单、评论、标签、用户和组织                  | 写入    | 仅由你在智能体上启用的 Zendesk 工具写入，并使用智能体在对话期间提供的参数。工具调用或触发器回复之外不会发生写入操作。                                                    |

仅当已连接的触发器触发，或智能体调用 Zendesk 工具时，集成才会调用 Zendesk API。它不会轮询 Zendesk 账户，也不会批量导出数据。

Zendesk 工具返回的记录会作为工具调用结果的一部分存储在对话转录文本中，因此读取记录的工具也会存储该记录。存储数据的保留期限遵循处理该工单的智能体隐私设置，包括转录文本和 PII 删除设置。

## Zendesk 工具

将 Zendesk 工具添加到智能体，让它在对话期间管理工单、用户和组织。连接集成后，可在智能体配置页面启用各个工具。

### 可用工具

该集成提供 30 多个工具，分为以下类别：

* **工单** — 创建、更新、删除、列出和搜索工单。还支持批量操作（批量创建、批量更新、批量删除）。
* **评论和标签** — 向工单添加公开或内部评论，以及添加或移除标签。
* **用户** — 查找、创建、更新和删除用户。支持批量创建或更新，以同步用户数据。
* **组织** — 获取组织详情并列出组织的工单。
* **搜索** — 在工单、用户和组织中运行 Zendesk 搜索查询（例如 `type:ticket status:open`）。

### 示例工具

#### zendesk_create_ticket

创建新的支持工单。智能体会从来电者收集详细信息，并代表他们创建工单。

| 参数                       | 类型      | 说明                                                |
| ------------------------ | ------- | ------------------------------------------------- |
| `ticket.subject`         | string  | 工单简短主题                                            |
| `ticket.comment.body`    | string  | 问题的详细描述                                           |
| `ticket.requester.email` | string  | 请求者的邮箱地址                                          |
| `ticket.requester.name`  | string  | 请求者的全名                                            |
| `ticket.priority`        | string  | `urgent`、`high`、`normal` 或 `low`                  |
| `ticket.status`          | string  | `new`、`open`、`pending`、`hold`、`solved` 或 `closed` |
| `ticket.assignee_id`     | integer | 要分配工单的智能体 ID                                      |
| `ticket.group_id`        | integer | 工单要路由到的组 ID                                       |
| `ticket.custom_fields`   | array   | 自定义字段的 `{id, value}` 对象数组                         |

#### zendesk_search

使用 Zendesk 搜索查询语法，搜索工单、用户或组织。

| 参数      | 类型     | 说明                                                                      |
| ------- | ------ | ----------------------------------------------------------------------- |
| `query` | string | 搜索查询（例如 `type:ticket status:open` 或 `type:user email:user@example.com`） |

#### zendesk_add_comment

向现有工单添加公开或内部评论，适合发布通话摘要或后续说明。

| 参数                         | 类型      | 说明              |
| -------------------------- | ------- | --------------- |
| `ticket_id`                | integer | 要添加评论的工单        |
| `ticket.comment.body`      | string  | 纯文本评论内容         |
| `ticket.comment.html_body` | string  | 评论的 HTML 版本（可选） |
| `ticket.comment.public`    | boolean | 评论是否对请求者可见      |

#### zendesk_get_user

获取用户资料，以便智能体按姓名问候来电者或验证其身份。

| 参数        | 类型      | 说明                 |
| --------- | ------- | ------------------ |
| `user_id` | integer | 要查找的 Zendesk 用户 ID |

### 配置工具

#### 添加集成工具

在智能体配置页面，点击 **添加工具**，然后选择 **添加集成工具**。

![添加集成工具](/docs/_fern-img/ef3a82e0747f1b1da18fb6b4755812abe161d436582312e47836e621a44d83c7.webp)

#### 选择 Zendesk 工具

选择 Zendesk 连接，然后启用希望智能体使用的工具。可按需启用任意数量的工具。例如，只读分诊智能体可能只需要搜索和列表工具，而全功能智能体还可能需要创建和更新工单。

![选择 Zendesk 工具](/docs/_fern-img/9161ae75a4c514d477174622bd4857d6faf62a11825bc7d4d191176e52a72f91.webp)

#### （可选）提供参数

每个工具的参数都会由智能体在对话中根据来电者所说的内容填写，无需硬编码参数值。不过，也可选择预填或限制特定参数，例如设置默认 `priority` 或 `group_id`，以引导智能体的行为。

#### 旧版 webhook 设置

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

旧版集成使用 3 个 webhook 工具创建支持智能体。请在下方标签页中查看各工具的配置。

#### zendesk_get_ticket_comments

**名称：** zendesk_get_ticket_comments
**说明：** 获取工单的评论。
**方法：** GET
**URL：** `https://acmecorp.zendesk.com/api/v2/tickets/{ticket_id}/comments.json`

**请求头：**

* **Content-Type：** `application/json`
* **Authorization：** *（密钥：`zendesk_key`）*

**路径参数：**

* **ticket_id：** 从 get_resolved_tickets 结果的 `id` 字段中提取该值。

**工具 JSON：**

```json
{
  "type": "webhook",
  "name": "zendesk_get_ticket_comments",
  "description": "Retrieves the comments of a ticket.",
  "api_schema": {
    "url": "https://acmecorp.zendesk.com/api/v2/tickets/{ticket_id}/comments.json",
    "method": "GET",
    "path_params_schema": [
      {
        "id": "ticket_id",
        "type": "string",
        "description": "Extract the value from the id field in the get_resolved_tickets results.",
        "dynamic_variable": "",
        "constant_value": "",
        "required": false,
        "value_type": "llm_prompt"
      }
    ],
    "query_params_schema": [],
    "request_body_schema": null,
    "request_headers": [
      {
        "type": "secret",
        "name": "Authorization",
        "secret_id": "zendesk_api_token"
      },
      {
        "type": "value",
        "name": "Content-Type",
        "value": "application/json"
      }
    ]
  },
  "response_timeout_secs": 20,
  "dynamic_variables": {
    "dynamic_variable_placeholders": {}
  }
}
```

#### zendesk_get_resolved_tickets

**名称：** zendesk_get_resolved_tickets
**说明：** 获取 Zendesk 中所有已解决的支持工单。
**方法：** GET
**URL：** `https://acmecorp.zendesk.com/api/v2/search.json?query=type:ticket+status:solved`

**请求头：**

* **Content-Type：** `application/json`
* **Authorization：** *（密钥：`zendesk_key`）*

**工具 JSON：**

```json
{
  "type": "webhook",
  "name": "zendesk_get_resolved_tickets",
  "description": "Retrieves all resolved support tickets from Zendesk.",
  "api_schema": {
    "url": "https://acmecorp.zendesk.com/api/v2/search.json?query=type:ticket+status:solved",
    "method": "GET",
    "path_params_schema": [],
    "query_params_schema": [],
    "request_body_schema": null,
    "request_headers": [
      {
        "type": "secret",
        "name": "Authorization",
        "secret_id": "zendesk_api_token"
      },
      {
        "type": "value",
        "name": "Content-Type",
        "value": "application/json"
      }
    ]
  },
  "response_timeout_secs": 20,
  "dynamic_variables": {
    "dynamic_variable_placeholders": {}
  }
}
```

#### zendesk_open_ticket

**名称：** zendesk_open_ticket
**说明：** 创建新的支持工单。
**方法：** POST
**URL：** `https://acmecorp.zendesk.com/api/v2/tickets.json`

**请求头：**

* **Content-Type：** `application/json`
* **Authorization：** *（密钥：`zendesk_key`）*

**正文参数：**

* **ticket：** 包含以下内容的对象：
  * **comment：**
    * **body：** 支持问题的详细描述。
  * **subject：** 简短主题。
  * **requester：**
    * **name：** 请求者的全名。
    * **email：** 有效邮箱地址。

**工具 JSON：**

```json
{
  "type": "webhook",
  "name": "zendesk_open_ticket",
  "description": "API endpoint to open a customer support ticket\nMake sure the authorization header is formated as \"Authorization: Basic <auth>\".",
  "api_schema": {
    "url": "https://acmecorp.zendesk.com/api/v2/tickets.json",
    "method": "POST",
    "path_params_schema": [],
    "query_params_schema": [],
    "request_body_schema": {
      "id": "body",
      "type": "object",
      "description": "Details for the support ticket",
      "required": false,
      "properties": [
        {
          "id": "ticket",
          "type": "object",
          "description": "This is the main ticket body which contains all of the information needed to open a ticket.",
          "required": true,
          "properties": [
            {
              "id": "comment",
              "type": "object",
              "description": "This is the comment with information about the issue.",
              "required": true,
              "properties": [
                {
                  "id": "body",
                  "type": "string",
                  "description": "Body of the issue. Include all relevant details for the issue. ",
                  "dynamic_variable": "",
                  "constant_value": "",
                  "required": true,
                  "value_type": "llm_prompt"
                }
              ]
            },
            {
              "id": "subject",
              "type": "string",
              "description": "Create a short subject line for the support issue. Add \"DEMO: \" before the subject.",
              "dynamic_variable": "",
              "constant_value": "",
              "required": true,
              "value_type": "llm_prompt"
            },
            {
              "id": "requester",
              "type": "object",
              "description": "The details of the support requester",
              "required": true,
              "properties": [
                {
                  "id": "email",
                  "type": "string",
                  "description": "The email address of the requester. This should look like \njohnsmith@hotmail.com\nYou MUST use the @ symbol and remove any spaces.",
                  "dynamic_variable": "",
                  "constant_value": "",
                  "required": true,
                  "value_type": "llm_prompt"
                },
                {
                  "id": "name",
                  "type": "string",
                  "description": "The full name of the requester. ",
                  "dynamic_variable": "",
                  "constant_value": "",
                  "required": true,
                  "value_type": "llm_prompt"
                }
              ]
            }
          ]
        }
      ]
    },
    "request_headers": [
      {
        "type": "secret",
        "name": "Authorization",
        "secret_id": "zendesk_api_token"
      },
      {
        "type": "value",
        "name": "Content-Type",
        "value": "application/json"
      }
    ]
  },
  "response_timeout_secs": 20,
  "dynamic_variables": {
    "dynamic_variable_placeholders": {}
  }
}
```

> **Warning**
>
> 请确保已将工作区的 Zendesk 密钥添加到智能体密钥中。

## Zendesk 触发器

配置 Zendesk 触发器，让智能体监控并响应传入的工单评论，提供一线支持。

### 设置

#### 在 Zendesk 中创建触发器

在 Zendesk 管理中心，前往 **对象和规则 > 业务规则 > 触发器**，然后点击 **添加触发器**。配置用于确定智能体应响应哪些工单事件的条件（例如特定组中的新工单、带有特定标签的工单评论）。记下触发器名称——下一步需要用到它。

如果由于缺少操作而无法保存触发器，请添加一个简单操作，例如为工单添加“智能体正在处理”标签。

#### 在 ElevenLabs 中连接触发器

在智能体配置页面添加新的触发器，然后选择 **Zendesk 触发器**。配置以下字段：

* **智能体**：处理传入对话的智能体。
* **触发器规则名称**：上一步创建的 Zendesk 触发器名称。
* **每日工单上限**（可选）：智能体每天处理的最大工单数。留空表示不限数量。

激活触发器后，ElevenLabs 会在 Zendesk 账户中创建 webhook，并将其作为操作添加到指定的触发器。停用触发器会移除 webhook 和操作。

#### （可选）在 Zendesk 中检查触发器

在 Zendesk 管理中心，前往 **对象和规则 > 业务规则 > 触发器**，并查看之前创建的触发器。应该会看到其中新增了一项操作。

如果之前创建了其他操作，现在可以再次将其移除。

### 影子模式

在 Zendesk 触发器上启用影子模式，让智能体观察并起草回复，而不直接回复客户。影子模式启用后，智能体会将回复作为工单的 **内部评论**，而不是公开回复。只有 Zendesk 智能体和管理员可以看到内部评论——终端用户不会收到通知。

> **Warning**
>
> 影子模式仅影响智能体发布回复的方式。如果智能体使用修改工单的工具
> （例如更改状态、添加标签或分配工单），这些更改仍会生效。为防止意外修改，请使用移除了修改工具
> 调用的独立智能体分支。

影子模式适合在正式上线前评估智能体质量。将内部评论与实际支持回复进行对照，比较准确性和语气；确认输出符合预期后，再将智能体切换为活跃模式。

### 避免循环

当智能体通过 Zendesk API 回复工单评论时，该回复本身也是一条新评论——这可能再次触发智能体并形成无限循环。请在 Zendesk 触发器中添加以下任一条件以防止这种情况。

**在触发器中排除服务账户。** 为集成创建一个单独的 Zendesk 用户（例如 `ai-agent@yourcompany.com`），并在 ElevenLabs 中连接时使用该账户凭据。然后在 Zendesk 触发器中添加以下条件：

* **当前用户**、**不是**、**\<服务账户>**

**在触发器中排除 API 更新。** 这会筛除通过 Zendesk API 进行的所有更新，无论由哪个用户执行：

* **工单 > 更新方式**、**不是**、**Web Service (API)**

## 实用链接

* [Zendesk API 文档](https://developer.zendesk.com/api-reference/)
* [管理 API token](https://support.zendesk.com/hc/en-us/articles/4408889192858-Managing-API-token-access-to-the-Zendesk-API)
* [Zendesk 触发器指南](https://support.zendesk.com/hc/en-us/articles/203662246-About-triggers-and-how-they-work)