> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# EspoCRM

使用以下 [webhook 工具](/docs/zh/reception-ai/integrations/webhooks)，接待员可识别已存在于 EspoCRM 中的来电者，并将新来电者添加为潜在客户，记录其姓名、电话号码和需求，方便团队后续跟进。EspoCRM 的 API 使用固定 API 密钥和 JSON 请求正文，因此 EspoCRM Cloud 与自托管安装的配置方式相同。

## 开始前

### 创建角色

在 EspoCRM 中，前往 **管理** → **角色**，创建一个可读取和创建 **潜在客户**、读取 **联系人** 的角色。其他所有范围均保持禁用。

### 创建 API 用户

前往 **管理** → **API 用户**，创建一个用户。将身份验证方式设为 **API 密钥**，并分配刚创建的角色。保存后，从用户详情视图复制 API 密钥。

以下每个工具都会在名为 `X-Api-Key` 的请求标头中发送该密钥。将其 **类型** 设为 **密钥**。

> **Warning**
>
> API 密钥可读取和更改其角色允许的所有内容。请限制角色权限；如果密钥泄露，请在 EspoCRM 中重新生成。

### 查找 EspoCRM 地址

工具的 URL 以你在浏览器中打开 EspoCRM 时使用的地址开头，后接 `/api/v1/`。下表使用 `https://YOUR-CRM.example.com`；请替换为自己的地址。

## 创建工具

对于每个工具，前往 **集成**，选择 **添加集成**，选择 **Webhook 工具**，然后将 **分配给智能体** 设为 **接待员**。对于下方标记为“始终”的每个参数，将 **值** 设为 **固定值**。

### 查找潜在客户

| 字段       | 值                                                                                                                      |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| **名称**   | `find_espocrm_lead`                                                                                                    |
| **描述**   | “按电话号码在潜在客户中查找来电者。请在通话开始时使用，确认对方之前是否联系过我们。”                                                                            |
| **方法**   | GET                                                                                                                    |
| **URL**  | `https://YOUR-CRM.example.com/api/v1/Lead`                                                                             |
| **请求标头** | `X-Api-Key`：API 密钥                                                                                                     |
| **查询参数** | `textFilter`（字符串，必填）：“包含国家/地区代码的来电者电话号码，例如 +14155550123。”  `select`（字符串）：始终为 `id,name,status`。  `maxSize`（整数）：始终为 `5`。 |

如需同时识别现有客户，请创建第二个名为 `find_espocrm_contact` 的工具，使用相同设置，并将 URL 设为 `https://YOUR-CRM.example.com/api/v1/Contact`。

### 添加新潜在客户

| 字段       | 值                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **名称**   | `create_espocrm_lead`                                                                                                                                                                                                                                      |
| **描述**   | “当 `find_espocrm_lead` 未找到来电者时，将其添加为新潜在客户。”                                                                                                                                                                                                                |
| **方法**   | POST                                                                                                                                                                                                                                                       |
| **URL**  | `https://YOUR-CRM.example.com/api/v1/Lead`                                                                                                                                                                                                                 |
| **请求标头** | `X-Api-Key`：API 密钥                                                                                                                                                                                                                                         |
| **正文参数** | `firstName`（字符串，必填）：“来电者的名字。”  `lastName`（字符串，必填）：“来电者的姓氏。”  `phoneNumber`（字符串，必填）：“国际格式的来电者电话号码，例如 +14155550123。”  `emailAddress`（字符串）：“来电者提供的电子邮件地址（如有）。”  `description`（字符串，必填）：“来电者的需求，以及希望何时回电。”  `status`（字符串）：始终为 `New`。  `source`（字符串）：始终为 `Call`。 |

如需将新潜在客户分配给一名销售人员，请将 `assignedUserId`（字符串）添加为固定值，并填入该用户的 ID。你可以在 EspoCRM 中打开该用户时，从地址栏查看其 ID。

在每个工具上选择 **启用**，然后以请求报价的新来电者身份[测试接待员](/docs/zh/reception-ai/receptionist/testing)。潜在客户将出现在 EspoCRM 中，状态为 **新建**，来源为 **通话**。

> **Tip**
>
> 添加一项[流程](/docs/zh/reception-ai/receptionist/rules-and-procedures)，让接待员先搜索，仅在未找到匹配项时添加潜在客户。

> **Warning**
>
> 搜索也会匹配姓名和电子邮件地址，因此来电者可能会尝试查询其他人。
> 添加一条规则：接待员绝不向来电者读出 CRM 记录，并将 **select**
> 限制为 `id,name,status`。

## 限制

* `textFilter` 与 EspoCRM 自带搜索框使用相同的搜索方式：会搜索姓名、电子邮件地址和电话号码。按电话号码搜索时，也可能匹配到号码以相同数字开头的其他记录，因此接待员应确认来电者姓名。
* 使用这些工具，接待员无法向现有潜在客户或联系人添加备注或任务。新潜在客户的描述会记录通话详情。
* 工具不会设置团队。EspoCRM 将团队作为团队 ID 列表（`teamsIds`）接收，而 webhook 工具始终会根据对话填充列表，因此无法将每个潜在客户设为同一团队，接待员也不应选择团队。请改用 `assignedUserId` 分配潜在客户。

## 故障排除

| 问题                     | 检查项                                                                   |
| ---------------------- | --------------------------------------------------------------------- |
| EspoCRM 返回 401         | 标头必须命名为 `X-Api-Key`，并包含 API 用户详情视图中的密钥。确认 API 用户处于活动状态。               |
| EspoCRM 返回 403         | API 用户的角色无权读取或创建潜在客户。请在 **管理** → **角色** 中编辑该角色。                       |
| 添加潜在客户时出现 409          | EspoCRM 发现可能重复的记录，例如姓名或电子邮件地址相同的潜在客户。接待员应先搜索。                         |
| 未找到已知来电者               | 请以国际格式存储电话号码，例如 `+14155550123`，并确认号码位于潜在客户或联系人中，而不只是在账户中。             |
| `status` 或 `source` 错误 | 这些值必须与 **管理** → **实体管理器** → **潜在客户** 中设置的潜在客户 **状态** 和 **来源** 选项完全一致。 |